Manual Pages for UNIX Operating System command usage for man kstat_create

Kernel Functions for Drivers                     kstat_create(9F)



NAME
     kstat_create - create and initialize a new kstat

SYNOPSIS
     #include 
     #include 



     kstat_t *kstat_create(const char *ks_module, int ks_instance,
          const char *ks_name, const char *ks_class, uchar_t ks_type,
          ulong_t ks_ndata, uchar_t ks_flag);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI)

PARAMETERS
     ks_module      The name of the provider's  module  (such  as
                    "sd", "esp", ...). The "core" kernel uses the
                    name "unix".


     ks_instance    The  provider's  instance  number,  as   from
                    ddi_get_instance(9F).  Modules  which  do not
                    have a meaningful instance number should  use
                    0.


     ks_name        A pointer to a string that  uniquely  identi-
                    fies  this  structure.  Only KSTAT_STRLEN - 1
                    characters are significant.


     ks_class       The general class that this kstat belongs to.
                    The  following  classes are currently in use:
                    disk, tape, net, controller,  vm,  kvm,  hat,
                    streams, kstat, and misc.


     ks_type        The type of kstat to  allocate.  Valid  types
                    are:

                    KSTAT_TYPE_NAMED    Allows more than one data
                                        record per kstat.


                    KSTAT_TYPE_INTR     Interrupt; only one  data
                                        record per kstat.






SunOS 5.11          Last change: 13 Nov 2006                    1






Kernel Functions for Drivers                     kstat_create(9F)



                    KSTAT_TYPE_IO       I/O; only one data record
                                        per kstat



     ks_ndata       The number of type-specific data  records  to
                    allocate.


     ks_flag        A bit-field of various flags for this  kstat.
                    ks_flag is some combination of:

                    KSTAT_FLAG_VIRTUAL       Tells kstat_create()
                                             not    to   allocate
                                             memory for the kstat
                                             data        section;
                                             instead, the  driver
                                             will set the ks_data
                                             field  to  point  to
                                             the  data  it wishes
                                             to export. This pro-
                                             vides  a  convenient
                                             way to export exist-
                                             ing data structures.


                    KSTAT_FLAG_WRITABLE      Makes the kstat data
                                             section  writable by
                                             root.


                    KSTAT_FLAG_PERSISTENT    Indicates that  this
                                             kstat  is to be per-
                                             sistent  over  time.
                                             For       persistent
                                             kstats,
                                             kstat_delete(9F)
                                             simply   marks   the
                                             kstat  as dormant; a
                                             subsequent
                                             kstat_create() reac-
                                             tivates  the  kstat.
                                             This feature is pro-
                                             vided    so     that
                                             statistics  are  not
                                             lost  across  driver
                                             close/open  (such as
                                             raw disk  I/O  on  a
                                             disk with no mounted
                                             partitions.)   Note:
                                             Persistent    kstats
                                             cannot  be  virtual,



SunOS 5.11          Last change: 13 Nov 2006                    2






Kernel Functions for Drivers                     kstat_create(9F)



                                             since ks_data points
                                             to garbage  as  soon
                                             as  the  driver goes
                                             away.



DESCRIPTION
     kstat_create() is used in conjunction with kstat_install(9F)
     to allocate and initialize a kstat(9S) structure. The method
     is generally as follows:


     kstat_create() allocates and performs necessary system  ini-
     tialization  of  a kstat(9S) structure. kstat_create() allo-
     cates memory for the entire kstat (header plus  data),  ini-
     tializes  all header fields, initializes the data section to
     all zeroes, assigns a unique kstat ID (KID),  and  puts  the
     kstat  onto  the system's kstat chain. The returned kstat is
     marked invalid because the provider (caller) has not yet had
     a chance to initialize the data section.


     After a successful call to kstat_create()  the  driver  must
     perform  any  necessary  initialization  of the data section
     (such as  setting  the  name  fields  in  a  kstat  of  type
     KSTAT_TYPE_NAMED).  Virtual  kstats  must  have  the ks_data
     field set at this  time.  The  provider  may  also  set  the
     ks_update, ks_private, and ks_lock fields if necessary.


     Once the kstat is completely initialized,  kstat_install(9F)
     is used to make the kstat accessible to the outside world.

RETURN VALUES
     If successful, kstat_create() returns a pointer to the allo-
     cated kstat. NULL is returned upon failure.

CONTEXT
     kstat_create() can be called from user or kernel context.

EXAMPLES
     Example 1 Allocating and Initializing a kstat Structure

       pkstat_t   *ksp;
          ksp = kstat_create(module, instance, name, class, type, ndata, flags);
          if (ksp) {
             /* ... provider initialization, if necessary */
             kstat_install(ksp);
          }





SunOS 5.11          Last change: 13 Nov 2006                    3






Kernel Functions for Drivers                     kstat_create(9F)



SEE ALSO
     kstat(3KSTAT),    ddi_get_instance(9F),    kstat_delete(9F),
     kstat_install(9F),      kstat_named_init(9F),     kstat(9S),
     kstat_named(9S)


     Writing Device Drivers
















































SunOS 5.11          Last change: 13 Nov 2006                    4