Go to main content

man pages section 9: DDI and DKI Driver Entry Points

Exit Print View

Updated: Thursday, June 13, 2019



ks_snapshot - take a snapshot of kstat data


#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).



Pointer to a kstat(9S) structure.


Pointer to a buffer to copy the snapshot into.


Read/Write flag. Possible values are:


Copy driver statistics from the driver to the buffer.


Copy statistics from the buffer to the driver.


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.

  1. ks_snaptime must be set through the gethrtime() function to timestamp the data. For more information, see the gethrtime(9F) man page.

  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




If KSTAT_WRITE is not allowed


For any other error


This function is called from user context only.


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_PTR(knp) = end;
                         end += KSTAT_NAMED_STR_BUFLEN(knp);
    return (0);

See Also

ks_update(9E), kstat_create(9F), kstat_install(9F), kstat(9S), kstat2_create(9F), kstat2_install(9F), kstat2(9S)

Writing Device Drivers in Oracle Solaris 11.4


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