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
     kstat_install(9F).

     The ks_snapshot() function must have  the  following  struc-
     ture:

     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()  rou-
     tine. 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

          0     Success

          EACCESS
                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 (EACCESS);
         } 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);
     }

SEE ALSO

     ks_update(9E),     kstat_create(9F),      kstat_install(9F),
     kstat(9S)

     Writing Device Drivers