Current File : //usr/share/man/man3kstat/kstat_read.3kstat

'\" te
.\" Copyright (c) 2004, 2010, Oracle and/or its affiliates. All rights reserved.
.TH kstat_read 3KSTAT "13 Apr 2010" "SunOS 5.11" "Kernel Statistics Library Functions"
.SH NAME
kstat_read, kstat_write \- read or write kstat data
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkstat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <kstat.h>

\fBkid_t\fR \fBkstat_read\fR(\fBkstat_ctl_t *\fR\fIkc\fR, \fBkstat_t *\fR\fIksp\fR, \fBvoid *\fR\fIbuf\fR);
.fi

.LP
.nf
\fBkid_t\fR \fBkstat_write\fR(\fBkstat_ctl_t *\fR\fIkc\fR, \fBkstat_t *\fR\fIksp\fR, \fBvoid *\fR\fIbuf\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBkstat_read()\fR function gets data from the kernel for the kstat pointed to by \fIksp\fR. The \fIksp\fR->\fBks_data\fR field is automatically allocated (or reallocated) to be large enough to hold all of the data. The \fIksp\fR->\fBks_ndata\fR field is set to the number of data fields, \fIksp\fR->\fBks_data_size\fR is set to the total size of the data, and \fIksp\fR->\fBks_snaptime\fR is set to the high-resolution time at which the data snapshot was taken. If \fIbuf\fR is  non-null, the data is copied from \fIksp\fR->\fBks_data\fR to \fIbuf\fR.
.sp
.LP
The \fBkstat_write()\fR function writes data from \fIbuf\fR, or from \fIksp\fR->\fBks_data\fR if \fIbuf\fR is \fINULL\fR, to the corresponding kstat in the kernel.  Only the superuser can use \fBkstat_write()\fR.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBkstat_read()\fR and \fBkstat_write()\fR return the current kstat chain ID (KCID). Otherwise, they return \(mi1 and set \fBerrno\fR to indicate the error.
.SH ERRORS
.sp
.LP
The \fBkstat_read()\fR and \fBkstat_write()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEACCES\fR\fR
.ad
.RS 13n
.rt  
An attempt was made to write to a non-writable kstat.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 13n
.rt  
The kstat was temporarily unavailable for reading or writing.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 13n
.rt  
An attempt was made to write data to a kstat, but the number of elements or the data size does not match.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 13n
.rt  
Insufficient storage space is available.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENXIO\fR\fR
.ad
.RS 13n
.rt  
The given kstat could not be located for reading or writing.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEOVERFLOW\fR\fR
.ad
.RS 13n
.rt  
The data for the given kstat was too large to be stored in the structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEPERM\fR\fR
.ad
.RS 13n
.rt  
An attempt was made to write to a kstat, but {\fBPRIV_SYS_CONFIG\fR} was not asserted in the effective privilege set.
.RE

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/dev/kstat\fR\fR
.ad
.RS 14n
.rt  
kernel statistics driver
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe with exceptions
.TE

.sp
.LP
The \fBkstat_read()\fR function is MT-Safe with the exception that only one thread may actively use a \fBkstat_ctl_t *\fR value at any time. Synchronization is left to the application.
.SH SEE ALSO
.sp
.LP
\fBkstat\fR(3KSTAT), \fBkstat_chain_update\fR(3KSTAT), \fBkstat_lookup\fR(3KSTAT), \fBkstat_open\fR(3KSTAT), \fBattributes\fR(5), \fBprivileges\fR(5)