'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
.TH kstat_create 9F "13 Nov 2006" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
kstat_create \- create and initialize a new kstat
.SH SYNOPSIS
.LP
.nf
#include <sys/types.h>
#include <sys/kstat.h>

\fBkstat_t *\fR\fBkstat_create\fR(\fBconst char *\fR\fIks_module\fR, \fBint\fR \fIks_instance\fR, 
     \fBconst char *\fR\fIks_name\fR, \fBconst char *\fR\fIks_class\fR, \fBuchar_t\fR \fIks_type\fR, 
     \fBulong_t\fR \fIks_ndata\fR, \fBuchar_t\fR \fIks_flag\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIks_module\fR\fR
.ad
.RS 15n
.rt  
The name of the provider's module (such as "\fBsd\fR", "\fBesp\fR", ...). The "\fBcore\fR" kernel uses the name "unix".
.RE

.sp
.ne 2
.mk
.na
\fB\fIks_instance\fR\fR
.ad
.RS 15n
.rt  
The provider's instance number, as from \fBddi_get_instance\fR(9F). Modules which do not have a meaningful instance number should use \fB0\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIks_name\fR\fR
.ad
.RS 15n
.rt  
A pointer to a string that uniquely identifies this structure. Only \fBKSTAT_STRLEN \(mi 1\fR characters are significant.
.RE

.sp
.ne 2
.mk
.na
\fB\fIks_class\fR\fR
.ad
.RS 15n
.rt  
The general class that this kstat belongs to. The following classes are currently in use: \fBdisk\fR, \fBtape\fR, \fBnet\fR, \fBcontroller\fR, \fBvm\fR, \fBkvm\fR, \fBhat\fR, \fBstreams\fR, \fBkstat\fR, and \fBmisc\fR. 
.RE

.sp
.ne 2
.mk
.na
\fB\fIks_type\fR\fR
.ad
.RS 15n
.rt  
The type of \fBkstat\fR to allocate. Valid types are: 
.sp
.ne 2
.mk
.na
\fB\fBKSTAT_TYPE_NAMED\fR\fR
.ad
.RS 20n
.rt  
Allows more than one data record per \fBkstat\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBKSTAT_TYPE_INTR\fR\fR
.ad
.RS 20n
.rt  
Interrupt; only one data record per \fBkstat\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBKSTAT_TYPE_IO\fR\fR
.ad
.RS 20n
.rt  
\fBI/O\fR; only one data record per \fBkstat\fR
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIks_ndata\fR\fR
.ad
.RS 15n
.rt  
The number of type-specific data records to allocate.
.RE

.sp
.ne 2
.mk
.na
\fB\fIks_flag\fR\fR
.ad
.RS 15n
.rt  
A bit-field of various flags for this \fBkstat\fR. \fIks_flag\fR is some combination of: 
.sp
.ne 2
.mk
.na
\fB\fBKSTAT_FLAG_VIRTUAL\fR\fR
.ad
.RS 25n
.rt  
Tells \fBkstat_create()\fR not to allocate memory for the \fBkstat\fR data section; instead, the driver will set the \fBks_data\fR field to point to the data it wishes to export. This provides a convenient way to export existing data structures.
.RE

.sp
.ne 2
.mk
.na
\fB\fBKSTAT_FLAG_WRITABLE\fR\fR
.ad
.RS 25n
.rt  
Makes the \fBkstat\fR data section writable by root.
.RE

.sp
.ne 2
.mk
.na
\fB\fBKSTAT_FLAG_PERSISTENT\fR\fR
.ad
.RS 25n
.rt  
Indicates that this \fBkstat\fR is to be persistent over time. For persistent \fBkstat\fRs, \fBkstat_delete\fR(9F) simply marks the \fBkstat\fR as dormant; a subsequent \fBkstat_create()\fR reactivates the kstat. This feature is provided so that statistics are not lost across driver close/open (such as raw disk \fBI/O\fR on a disk with no mounted partitions.) Note: Persistent \fBkstat\fRs cannot be virtual, since \fBks_data\fR points to garbage as soon as the driver goes away.
.RE

.RE

.SH DESCRIPTION
.sp
.LP
\fBkstat_create()\fR is used in conjunction with \fBkstat_install\fR(9F) to allocate and initialize a \fBkstat\fR(9S) structure. The method is generally as follows: 
.sp
.LP
\fBkstat_create()\fR allocates and performs necessary system initialization of a \fBkstat\fR(9S) structure. \fBkstat_create()\fR allocates memory for the entire \fBkstat\fR (header plus data), initializes all header fields, initializes the data section to all zeroes, assigns a unique kstat \fBID\fR (\fBKID\fR), and puts the kstat onto the system's \fBkstat\fR chain. The returned kstat is marked invalid because the provider (caller) has not yet had a chance to initialize the data section.
.sp
.LP
After a successful call to \fBkstat_create()\fR the driver must perform any necessary initialization of the data section (such as setting the name fields in a \fBkstat\fR of type \fBKSTAT_TYPE_NAMED\fR). Virtual \fBkstat\fRs must have the \fBks_data\fR field set at this time. The provider may also set the \fBks_update\fR, \fBks_private\fR, and \fBks_lock\fR fields if necessary.
.sp
.LP
Once the \fBkstat\fR is completely initialized, \fBkstat_install\fR(9F) is used to make the \fBkstat\fR accessible to the outside world.
.SH RETURN VALUES
.sp
.LP
If successful, \fBkstat_create()\fR returns a pointer to the allocated \fBkstat\fR. \fINULL\fR is returned upon failure.
.SH CONTEXT
.sp
.LP
\fBkstat_create()\fR can be called from user or kernel context.
.SH EXAMPLES
.LP
\fBExample 1 \fRAllocating and Initializing a \fBkstat\fR Structure
.sp
.in +2
.nf
pkstat_t   *ksp;
   ksp = kstat_create(module, instance, name, class, type, ndata, flags);
   if (ksp) {
      /* ... provider initialization, if necessary */
      kstat_install(ksp);
   }
.fi
.in -2

.SH SEE ALSO
.sp
.LP
\fBkstat\fR(3KSTAT), \fBddi_get_instance\fR(9F), \fBkstat_delete\fR(9F), \fBkstat_install\fR(9F), \fBkstat_named_init\fR(9F), \fBkstat\fR(9S), \fBkstat_named\fR(9S) 
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR