ks_snapshot - man pages section 9: DDI and DKI Driver Entry Points

Language:

ks_snapshot(9E)

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.

rw

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 the kstat_install() function. For more information, see the kstat_install(9F) man page.

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.

ks_snaptime must be set through the gethrtime() function to timestamp the data. For more information, see the gethrtime(9F) man page.
Data gets copied from the kstat to the buffer on KSTAT_READ, and from the buffer to the kstat on KSTAT_WRITE.

Return Values

0: 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);
}

Notes

With the introduction of kstats v2, the ks_snapshot() function is deprecated. It may be removed in a future release of Oracle Solaris.

man pages section 9: DDI and DKI Driver Entry Points