usr/src/man/man3kstat/kstat_read.3kstat

   1 '\" te
   2 .\" Copyright (c) 2004, 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_READ 3KSTAT "Aug 3, 2004"
   7 .SH NAME
   8 kstat_read, kstat_write \- read or write kstat data
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkstat\fR [ \fIlibrary\fR\&.\|.\|. ]
  13 #include <kstat.h>
  14
  15 \fBkid_t\fR \fBkstat_read\fR(\fBkstat_ctl_t *\fR\fIkc\fR, \fBkstat_t *\fR\fIksp\fR, \fBvoid *\fR\fIbuf\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBkid_t\fR \fBkstat_write\fR(\fBkstat_ctl_t *\fR\fIkc\fR, \fBkstat_t *\fR\fIksp\fR, \fBvoid *\fR\fIbuf\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBkstat_read()\fR function gets data from the kernel for the kstat pointed
  27 to by \fIksp\fR. The \fIksp\fR->\fBks_data\fR field is automatically allocated
  28 (or reallocated) to be large enough to hold all of the data. The
  29 \fIksp\fR->\fBks_ndata\fR field is set to the number of data fields,
  30 \fIksp\fR->\fBks_data_size\fR is set to the total size of the data, and
  31 \fIksp\fR->\fBks_snaptime\fR is set to the high-resolution time at which the
  32 data snapshot was taken. If \fIbuf\fR is  non-null, the data is copied from
  33 \fIksp\fR->\fBks_data\fR to \fIbuf\fR.
  34 .sp
  35 .LP
  36 The \fBkstat_write()\fR function writes data from \fIbuf\fR, or from
  37 \fIksp\fR->\fBks_data\fR if \fIbuf\fR is \fINULL\fR, to the corresponding kstat
  38 in the kernel.  Only the superuser can use \fBkstat_write()\fR.
  39 .SH RETURN VALUES
  40 .sp
  41 .LP
  42 Upon successful completion, \fBkstat_read()\fR and \fBkstat_write()\fR return
  43 the current kstat chain ID (KCID). Otherwise, they return \(mi1 and set
  44 \fBerrno\fR to indicate the error.
  45 .SH ERRORS
  46 .sp
  47 .LP
  48 The \fBkstat_read()\fR and \fBkstat_write()\fR functions will fail if:
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fBEACCES\fR\fR
  53 .ad
  54 .RS 13n
  55 An attempt was made to write to a non-writable kstat.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBEAGAIN\fR\fR
  62 .ad
  63 .RS 13n
  64 The kstat was temporarily unavailable for reading or writing.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBEINVAL\fR\fR
  71 .ad
  72 .RS 13n
  73 An attempt was made to write data to a kstat, but the number of elements or the
  74 data size does not match.
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBENOMEM\fR\fR
  81 .ad
  82 .RS 13n
  83 Insufficient storage space is available.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBENXIO\fR\fR
  90 .ad
  91 .RS 13n
  92 The given kstat could not be located for reading or writing.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBEOVERFLOW\fR\fR
  99 .ad
 100 .RS 13n
 101 The data for the given kstat was too large to be stored in the structure.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBEPERM\fR\fR
 108 .ad
 109 .RS 13n
 110 An attempt was made to write to a kstat, but {\fBPRIV_SYS_CONFIG\fR} was not
 111 asserted in the effective privilege set.
 112 .RE
 113
 114 .SH FILES
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fB/dev/kstat\fR\fR
 119 .ad
 120 .RS 14n
 121 kernel statistics driver
 122 .RE
 123
 124 .SH ATTRIBUTES
 125 .sp
 126 .LP
 127 See \fBattributes\fR(5) for descriptions of the following attributes:
 128 .sp
 129
 130 .sp
 131 .TS
 132 box;
 133 c | c
 134 l | l .
 135 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 136 _
 137 Interface Stability     Stable
 138 _
 139 MT-Level        Unsafe
 140 .TE
 141
 142 .SH SEE ALSO
 143 .sp
 144 .LP
 145 \fBkstat\fR(3KSTAT), \fBkstat_chain_update\fR(3KSTAT),
 146 \fBkstat_lookup\fR(3KSTAT), \fBkstat_open\fR(3KSTAT), \fBattributes\fR(5),
 147 \fBprivileges\fR(5)