ks_snapshot(9e)

1ks_snapshot(9E)               Driver Entry Points              ks_snapshot(9E)
2
3
4

NAME

6       ks_snapshot - take a snapshot of kstat data
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/kstat.h>
11       #include <sys/ddi.h>
12       #include <sys/sunddi.h>
13
14
15
16       int prefix_ks_snapshot(kstat_t *ksp, void *buf, int rw);
17
18

INTERFACE LEVEL

20       Solaris DDI specific (Solaris DDI).
21

PARAMETERS

23       ksp     Pointer to a kstat(9S) structure.
24
25
26       buf     Pointer to a buffer to copy the snapshot into.
27
28
29       rw      Read/Write flag. Possible values are:
30
31               KSTAT_READ     Copy  driver  statistics  from the driver to the
32                              buffer.
33
34
35               KSTAT_WRITE    Copy statistics from the buffer to the driver.
36
37
38

DESCRIPTION

40       The kstat mechanism allows for an optional  ks_snapshot()  function  to
41       copy  kstat  data.  This  is the routine that is called to marshall the
42       kstat data to be copied to user-land. A driver can opt to use a  custom
43       snapshot  routine  rather  than  the  default snapshot routine; to take
44       advantage of this feature, set the  ks_snapshot  field  before  calling
45       kstat_install(9F).
46
47
48       The ks_snapshot() function must have the following structure:
49
50         static int
51         xx_kstat_snapshot(kstat_t *ksp, void *buf, int rw)
52         {
53              if (rw == KSTAT_WRITE) {
54         /* set the native stats to the values in buf */
55         /* return EACCES if you don't support this */
56              } else {
57         /* copy the kstat-specific data into buf */
58              }
59              return (0);
60         }
61
62
63
64
65       In  general, the ks_snapshot() routine might need to refer to provider-
66       private data; for example, it might need a pointer  to  the  provider's
67       raw statistics. The ks_private field is available for this purpose. Its
68       use is entirely at the provider's discretion.
69
70
71       No kstat locking should be done inside  the  ks_update()  routine.  The
72       caller  will  already be holding the kstat's ks_lock (to ensure consis‐
73       tent data) and will prevent the kstat from being removed.
74
75           1.     ks_snaptime must be set (via gethrtime(9F)) to timestamp the
76                  data.
77
78           2.     Data gets copied from the kstat to the buffer on KSTAT_READ,
79                  and from the buffer to the kstat on KSTAT_WRITE.
80

RETURN VALUES

82       0         Success
83
84
85       EACCES    If KSTAT_WRITE is not allowed
86
87
88       EIO       For any other error
89
90

CONTEXT

92       This function is called from user context only.
93

EXAMPLES

95       Example 1 Named kstats with Long Strings (KSTAT_DATA_STRING)
96
97         static int
98         xxx_kstat_snapshot(kstat_t *ksp, void *buf, int rw)
99         {
100             if (rw == KSTAT_WRITE) {
101                  return (EACCES);
102             } else {
103                  kstat_named_t *knp = buf;
104                  char *end = knp + ksp->ks_ndata;
105                  uint_t i;
106
107                  bcopy(ksp->ks_data, buf,
108                          sizeof (kstat_named_t) * ksp->ks_ndata);
109         /*
110          * Now copy the strings to the end of the buffer, and
111          * update the pointers appropriately.
112          */
113                  for (i = 0; i < ksp->ks_ndata; i++, knp++)
114                          if (knp->data_type == KSTAT_DATA_STRING &&
115                              KSTAT_NAMED_STR_PTR(knp) != NULL) {
116                                  bcopy(KSTAT_NAMED_STR_PTR(knp), end,
117                                          KSTAT_NAMED_STR_BUFLEN(knp));
118                                  KSTAT_NAMED_STR_PTR(knp) = end;
119                                  end += KSTAT_NAMED_STR_BUFLEN(knp);
120                          }
121             }
122             return (0);
123         }
124
125
126