opensolaris man page for ks_snapshot

ks_snapshot(9E) 						Driver Entry Points						   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 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  consis-
       tent 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 {
		  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							    4 Dec 2002							   ks_snapshot(9E)