Driver Entry Points                               kssnapshot(9E)



NAME
     kssnapshot - take a snapshot of kstat data

SYNOPSIS
     #include 
     #include 
     #include 
     #include 



     int prefixkssnapshot(kstatt *ksp, void *buf, int rw);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI).

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:

             KSTATREAD     Copy  driver  statistics   from   the
                            driver to the buffer.


             KSTATWRITE    Copy statistics from  the  buffer  to
                            the driver.



DESCRIPTION
     The kstat mechanism allows  for  an  optional  kssnapshot()
     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   kssnapshot   field   before  calling
     kstatinstall(9F).


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

       static int
       xxkstatsnapshot(kstatt *ksp, void *buf, int rw)
       {
            if (rw == KSTATWRITE) {



SunOS 5.11           Last change: 4 Dec 2002                    1






Driver Entry Points                               kssnapshot(9E)



       /* set the native stats to the values in buf */
       /* return EACES if you don't support this */
            } else {
       /* copy the kstat-specific data into buf */
            }
            return (0);
       }




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


     No kstat locking should be done inside the ksupdate()  rou-
     tine. The caller will already be holding the kstat's kslock
     (to ensure consistent data) and will prevent the kstat  from
     being removed.

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

         2.   Data gets copied from the kstat to  the  buffer  on
              KSTATREAD,  and  from  the  buffer to the kstat on
              KSTATWRITE.

RETURN VALUES
     0         Success


     EACES    If KSTATWRITE 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 (KSTATDATASTRING)

       static int
       xxxkstatsnapshot(kstatt *ksp, void *buf, int rw)
       {
           if (rw == KSTATWRITE) {
                return (EACES);
           } else {



SunOS 5.11           Last change: 4 Dec 2002                    2






Driver Entry Points                               kssnapshot(9E)



                kstatnamedt *knp = buf;
                char *end = knp ] ksp->ksndata;
                uintt i;

                bcopy(ksp->ksdata, buf,
                        sizeof (kstatnamedt) * ksp->ksndata);
       /*
        * Now copy the strings to the end of the buffer, and
        * update the pointers appropriately.
        */
                for (i = 0; i < ksp->ksndata; i], knp])
                        if (knp->datatype == KSTATDATASTRING &&
                            KSTATNAMEDSTRPTR(knp) != NUL) {
                                bcopy(KSTATNAMEDSTRPTR(knp), end,
                                        KSTATNAMEDSTRBUFLEN(knp));
                                KSTATNAMEDSTRPTR(knp) = end;
                                end ]= KSTATNAMEDSTRBUFLEN(knp);
                        }
           }
           return (0);
       }



SEE ALSO
     ksupdate(9E),     kstatcreate(9F),      kstatinstall(9F),
     kstat(9S)


     Writing Device Drivers

























SunOS 5.11           Last change: 4 Dec 2002                    3