Проект OpenNet: MAN ks_snapshot (9) Ядро (FreeBSD и Linux)

Интерактивная система просмотра системных руководств (man-ов)

ks_snapshot (9)

>> ks_snapshot (9) ( Solaris man: Ядро )

NAME

ks_snapshot - take a snapshot of kstat data

SYNOPSIS

#include <sys/types.h>
#include <sys/kstat.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>



int prefix_ks_snapshot(kstat_t *ksp, void *buf, int rw);

INTERFACE LEVEL

Solaris DDI specific (Solaris DDI).

PARAMETERS

ksp

: Pointer to a kstat(9S) structure.

buf

: Pointer to a buffer to copy the snapshot into.

Read/Write flag. Possible values are:

KSTAT_READ

: Copy driver statistics from the driver to the buffer.

KSTAT_WRITE

: Copy statistics from the buffer to the driver.

DESCRIPTION

The kstat mechanism allows for an optional ks_snapshot() function to copy kstat data. This is the routine that is called to marshall the kstat data to be copied to user-land. A driver can opt to use a custom snapshot routine rather than the default snapshot routine; to take advantage of this feature, set the ks_snapshot field before calling kstat_install(9F).

The ks_snapshot() function must have the following structure:

static int
xx_kstat_snapshot(kstat_t *ksp, void *buf, int rw)
{
    if (rw == KSTAT_WRITE) {
/* set the native stats to the values in buf */
/* return EACCES if you don't support this */
    } else {
/* copy the kstat-specific data into buf */
    }
    return (0);
}

In general, the ks_snapshot() routine might need to refer to provider-private data; for example, it might need a pointer to the provider's raw statistics. The ks_private field is available for this purpose. Its use is entirely at the provider's discretion.

No kstat locking should be done inside the ks_update() routine. The caller will already be holding the kstat's ks_lock (to ensure consistent data) and will prevent the kstat from being removed.

1.: ks_snaptime must be set (via gethrtime(9F)) to timestamp the data.

2.: Data gets copied from the kstat to the buffer on KSTAT_READ, and from the buffer to the kstat on KSTAT_WRITE.

RETURN VALUES

: Success

EACCES

: If KSTAT_WRITE is not allowed

EIO

: For any other error

CONTEXT

This function is called from user context only.

EXAMPLES

Example 1 Named kstats with Long Strings (KSTAT_DATA_STRING)

static int
xxx_kstat_snapshot(kstat_t *ksp, void *buf, int rw)
{
   if (rw == KSTAT_WRITE) {
        return (EACCES);
   } else {
        kstat_named_t *knp = buf;
        char *end = knp + ksp->ks_ndata;
        uint_t i;

        bcopy(ksp->ks_data, buf,
                sizeof (kstat_named_t) * ksp->ks_ndata);
/*
* Now copy the strings to the end of the buffer, and
* update the pointers appropriately.
*/
        for (i = 0; i < ksp->ks_ndata; i++, knp++)
                if (knp->data_type == KSTAT_DATA_STRING &&
                    KSTAT_NAMED_STR_PTR(knp) != NULL) {
                        bcopy(KSTAT_NAMED_STR_PTR(knp), end,
                                KSTAT_NAMED_STR_BUFLEN(knp));
                        KSTAT_NAMED_STR_PTR(knp) = end;
                        end += KSTAT_NAMED_STR_BUFLEN(knp);
                } 
   }
   return (0);
}