Manual Pages for UNIX Operating System command usage for man ks_snapshot

Driver Entry Points                               ks_snapshot(9E)



NAME
     ks_snapshot - take a snapshot of kstat data

SYNOPSIS
     #include 
     #include 
     #include 
     #include 



     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) {



SunOS 5.11           Last change: 4 Dec 2002                    1






Driver Entry Points                               ks_snapshot(9E)



       /* 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


     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 {



SunOS 5.11           Last change: 4 Dec 2002                    2






Driver Entry Points                               ks_snapshot(9E)



                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

























SunOS 5.11           Last change: 4 Dec 2002                    3