share/man/man9f/kstat_create.9f

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH KSTAT_CREATE 9F "Sep 7, 2015"
   7 .SH NAME
   8 kstat_create \- create and initialize a new kstat
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/kstat.h>
  14
  15
  16
  17 \fBkstat_t *\fR\fBkstat_create\fR(\fBconst char *\fR\fIks_module\fR, \fBint\fR \fIks_instance\fR,
  18      \fBconst char *\fR\fIks_name\fR, \fBconst char *\fR\fIks_class\fR, \fBuchar_t\fR \fIks_type\fR,
  19      \fBulong_t\fR \fIks_ndata\fR, \fBuchar_t\fR \fIks_flag\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .LP
  24 Solaris DDI specific (Solaris DDI)
  25 .SH PARAMETERS
  26 .ne 2
  27 .na
  28 \fB\fIks_module\fR\fR
  29 .ad
  30 .RS 15n
  31 The name of the provider's module (such as "\fBsd\fR", "\fBesp\fR", ...). The
  32 "\fBcore\fR" kernel uses the name "unix".
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIks_instance\fR\fR
  39 .ad
  40 .RS 15n
  41 The provider's instance number, as from \fBddi_get_instance\fR(9F). Modules
  42 which do not have a meaningful instance number should use \fB0\fR.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIks_name\fR\fR
  49 .ad
  50 .RS 15n
  51 A pointer to a string that uniquely identifies this structure. Only
  52 \fBKSTAT_STRLEN \(mi 1\fR characters are significant.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fIks_class\fR\fR
  59 .ad
  60 .RS 15n
  61 The general class that this kstat belongs to. The following classes are
  62 currently in use: \fBdisk\fR, \fBtape\fR, \fBnet\fR, \fBcontroller\fR,
  63 \fBvm\fR, \fBkvm\fR, \fBhat\fR, \fBstreams\fR, \fBkstat\fR, and \fBmisc\fR.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIks_type\fR\fR
  70 .ad
  71 .RS 15n
  72 The type of \fBkstat\fR to allocate. Valid types are:
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fBKSTAT_TYPE_RAW\fR\fR
  77 .ad
  78 .RS 20n
  79 Raw data; allows more than one data record per \fBkstat\fR.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBKSTAT_TYPE_NAMED\fR\fR
  86 .ad
  87 .RS 20n
  88 Name=value pairs; allows more than one data record per \fBkstat\fR.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fBKSTAT_TYPE_INTR\fR\fR
  95 .ad
  96 .RS 20n
  97 Interrupt; only one data record per \fBkstat\fR.
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fBKSTAT_TYPE_IO\fR\fR
 104 .ad
 105 .RS 20n
 106 \fBI/O\fR; only one data record per \fBkstat\fR.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fBKSTAT_TYPE_TIMER\fR\fR
 113 .ad
 114 .RS 20n
 115 Event timer statistics; allows more than one data record per \fBkstat\fR.
 116 .RE
 117
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fIks_ndata\fR\fR
 124 .ad
 125 .RS 15n
 126 The number of type-specific data records to allocate.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fIks_flag\fR\fR
 133 .ad
 134 .RS 15n
 135 A bit-field of various flags for this \fBkstat\fR. \fIks_flag\fR is some
 136 combination of:
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBKSTAT_FLAG_VIRTUAL\fR\fR
 141 .ad
 142 .RS 25n
 143 Tells \fBkstat_create()\fR not to allocate memory for the \fBkstat\fR data
 144 section; instead, the driver will set the \fBks_data\fR field to point to the
 145 data it wishes to export. This provides a convenient way to export existing
 146 data structures.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBKSTAT_FLAG_WRITABLE\fR\fR
 153 .ad
 154 .RS 25n
 155 Makes the \fBkstat\fR data section writable by root.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBKSTAT_FLAG_PERSISTENT\fR\fR
 162 .ad
 163 .RS 25n
 164 Indicates that this \fBkstat\fR is to be persistent over time. For persistent
 165 \fBkstat\fRs, \fBkstat_delete\fR(9F) simply marks the \fBkstat\fR as dormant; a
 166 subsequent \fBkstat_create()\fR reactivates the kstat. This feature is provided
 167 so that statistics are not lost across driver close/open (such as raw disk
 168 \fBI/O\fR on a disk with no mounted partitions.) Note: Persistent \fBkstat\fRs
 169 cannot be virtual, since \fBks_data\fR points to garbage as soon as the driver
 170 goes away.
 171 .RE
 172
 173 .RE
 174
 175 .SH DESCRIPTION
 176 .LP
 177 \fBkstat_create()\fR is used in conjunction with \fBkstat_install\fR(9F) to
 178 allocate and initialize a \fBkstat\fR(9S) structure. The method is generally as
 179 follows:
 180 .sp
 181 .LP
 182 \fBkstat_create()\fR allocates and performs necessary system initialization of
 183 a \fBkstat\fR(9S) structure. \fBkstat_create()\fR allocates memory for the
 184 entire \fBkstat\fR (header plus data), initializes all header fields,
 185 initializes the data section to all zeroes, assigns a unique kstat \fBID\fR
 186 (\fBKID\fR), and puts the kstat onto the system's \fBkstat\fR chain. The
 187 returned kstat is marked invalid because the provider (caller) has not yet had
 188 a chance to initialize the data section.
 189 .sp
 190 .LP
 191 After a successful call to \fBkstat_create()\fR the driver must perform any
 192 necessary initialization of the data section (such as setting the name fields
 193 in a \fBkstat\fR of type \fBKSTAT_TYPE_NAMED\fR). Virtual \fBkstat\fRs must
 194 have the \fBks_data\fR field set at this time. The provider may also set the
 195 \fBks_update\fR, \fBks_private\fR, and \fBks_lock\fR fields if necessary.
 196 .sp
 197 .LP
 198 Once the \fBkstat\fR is completely initialized, \fBkstat_install\fR(9F) is used
 199 to make the \fBkstat\fR accessible to the outside world.
 200 .SH RETURN VALUES
 201 .LP
 202 If successful, \fBkstat_create()\fR returns a pointer to the allocated
 203 \fBkstat\fR. \fINULL\fR is returned upon failure.
 204 .SH CONTEXT
 205 .LP
 206 \fBkstat_create()\fR can be called from user or kernel context.
 207 .SH EXAMPLES
 208 .LP
 209 \fBExample 1 \fRAllocating and Initializing a \fBkstat\fR Structure
 210 .sp
 211 .in +2
 212 .nf
 213 pkstat_t   *ksp;
 214    ksp = kstat_create(module, instance, name, class, type, ndata, flags);
 215    if (ksp) {
 216       /* ... provider initialization, if necessary */
 217       kstat_install(ksp);
 218    }
 219 .fi
 220 .in -2
 221
 222 .SH SEE ALSO
 223 .LP
 224 \fBkstat\fR(3KSTAT), \fBddi_get_instance\fR(9F), \fBkstat_delete\fR(9F),
 225 \fBkstat_install\fR(9F), \fBkstat_named_init\fR(9F), \fBkstat\fR(9S),
 226 \fBkstat_named\fR(9S)
 227 .sp
 228 .LP
 229 \fIWriting Device Drivers\fR