diff options
Diffstat (limited to 'usr/src/man/man3kstat')
| -rw-r--r-- | usr/src/man/man3kstat/Makefile | 40 | ||||
| -rw-r--r-- | usr/src/man/man3kstat/kstat.3kstat | 563 | ||||
| -rw-r--r-- | usr/src/man/man3kstat/kstat_chain_update.3kstat | 129 | ||||
| -rw-r--r-- | usr/src/man/man3kstat/kstat_lookup.3kstat | 113 | ||||
| -rw-r--r-- | usr/src/man/man3kstat/kstat_open.3kstat | 136 | ||||
| -rw-r--r-- | usr/src/man/man3kstat/kstat_read.3kstat | 164 |
6 files changed, 1145 insertions, 0 deletions
diff --git a/usr/src/man/man3kstat/Makefile b/usr/src/man/man3kstat/Makefile new file mode 100644 index 0000000000..f8820f04cd --- /dev/null +++ b/usr/src/man/man3kstat/Makefile @@ -0,0 +1,40 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3kstat + +MANFILES = kstat.3kstat \ + kstat_chain_update.3kstat \ + kstat_lookup.3kstat \ + kstat_open.3kstat \ + kstat_read.3kstat + +MANSOFILES = kstat_close.3kstat \ + kstat_data_lookup.3kstat \ + kstat_write.3kstat + +MANFILES += $(MANSOFILES) + +kstat_data_lookup.3kstat := SOSRC = man3kstat/kstat_lookup.3kstat + +kstat_close.3kstat := SOSRC = man3kstat/kstat_open.3kstat + +kstat_write.3kstat := SOSRC = man3kstat/kstat_read.3kstat + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) diff --git a/usr/src/man/man3kstat/kstat.3kstat b/usr/src/man/man3kstat/kstat.3kstat new file mode 100644 index 0000000000..e1469f8ada --- /dev/null +++ b/usr/src/man/man3kstat/kstat.3kstat @@ -0,0 +1,563 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH kstat 3KSTAT "29 Jan 2007" "SunOS 5.11" "Kernel Statistics Library Functions" +.SH NAME +kstat \- kernel statistics facility +.SH DESCRIPTION +.sp +.LP +The \fBkstat\fR facility is a general-purpose mechanism for providing kernel +statistics to users. +.SS "The kstat model" +.sp +.LP +The kernel maintains a linked list of statistics structures, or kstats. Each +kstat has a common header section and a type-specific data section. The header +section is defined by the \fBkstat_t\fR structure: +.SS "kstat header" +.sp +.in +2 +.nf +typedef int kid_t; /* unique kstat id */ + +typedef struct kstat { + /* + * Fields relevant to both kernel and user + */ + hrtime_t ks_crtime; /* creation time */ + struct kstat *ks_next; /* kstat chain linkage */ + kid_t ks_kid; /* unique kstat ID */ + char ks_module[KSTAT_STRLEN]; /* module name */ + uchar_t ks_resv; /* reserved */ + int ks_instance; /* module's instance */ + char ks_name[KSTAT_STRLEN]; /* kstat name */ + uchar_t ks_type; /* kstat data type */ + char ks_class[KSTAT_STRLEN]; /* kstat class */ + uchar_t ks_flags; /* kstat flags */ + void *ks_data; /* kstat type-specific + data */ + uint_t ks_ndata; /* # of data records */ + size_t ks_data_size; /* size of kstat data + section */ + hrtime_t ks_snaptime; /* time of last data + snapshot */ + + /* + * Fields relevant to kernel only + */ + int(*ks_update)(struct kstat *, int); + void *ks_private; + int(*ks_snapshot)(struct kstat *, void *, int); + void *ks_lock; +} kstat_t; +.fi +.in -2 + +.sp +.LP +The fields that are of significance to the user are: +.sp +.ne 2 +.mk +.na +\fB\fBks_crtime\fR\fR +.ad +.RS 16n +.rt +The time the kstat was created. This allows you to compute the rates of various +counters since the kstat was created; "rate since boot" is replaced by the more +general concept of "rate since kstat creation". All times associated with +kstats (such as creation time, last snapshot time, \fBkstat_timer_t\fR and +\fBkstat_io_t\fR timestamps, and the like) are 64-bit nanosecond values. The +accuracy of kstat timestamps is machine dependent, but the precision (units) is +the same across all platforms. See \fBgethrtime\fR(3C) for general information +about high-resolution timestamps. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_next\fR\fR +.ad +.RS 16n +.rt +kstats are stored as a linked list, or chain. \fBks_next\fR points to the next +kstat in the chain. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_kid\fR\fR +.ad +.RS 16n +.rt +A unique identifier for the kstat. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_module\fR,\fR +.ad +.br +.na +\fB\fBks_instance\fR\fR +.ad +.RS 16n +.rt +contain the name and instance of the module that created the kstat. In cases +where there can only be one instance, \fBks_instance\fR is 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_name\fR\fR +.ad +.RS 16n +.rt +gives a meaningful name to a kstat. The full kstat namespace is +<\fBks_module\fR,\fBks_instance\fR,\fBks_name\fR>, so the name only need be +unique within a module. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_type\fR\fR +.ad +.RS 16n +.rt +The type of data in this kstat. kstat data types are discussed below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_class\fR\fR +.ad +.RS 16n +.rt +Each kstat can be characterized as belonging to some broad class of statistics, +such as disk, tape, net, vm, and streams. This field can be used as a filter to +extract related kstats. The following values are currently in use: \fBdisk\fR, +\fBtape\fR, \fBcontroller\fR, \fBnet\fR, \fBrpc\fR, \fBvm\fR, \fBkvm\fR, +\fBhat\fR, \fBstreams\fR, \fBkmem\fR, \fBkmem_cache\fR, \fBkstat\fR, and +\fBmisc\fR. (The kstat class encompasses things like \fIkstat_types\fR.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_data\fR,\fR +.ad +.br +.na +\fB\fBks_ndata\fR,\fR +.ad +.br +.na +\fB\fBks_data_size\fR\fR +.ad +.RS 16n +.rt +\fBks_data\fR is a pointer to the kstat's data section. The type of data stored +there depends on \fBks_type\fR. \fBks_ndata\fR indicates the number of data +records. Only some kstat types support multiple data records. Currently, +\fBKSTAT_TYPE_RAW\fR, \fBKSTAT_TYPE_NAMED\fR and \fBKSTAT_TYPE_TIMER\fR kstats +support multiple data records. \fBKSTAT_TYPE_INTR\fR and \fBKSTAT_TYPE_IO\fR +kstats support only one data record. \fBks_data_size\fR is the total size of +the data section, in bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_snaptime\fR\fR +.ad +.RS 16n +.rt +The timestamp for the last data snapshot. This allows you to compute activity +rates: +.sp +\fBrate = (new_count - old_count) / (new_snaptime - old_snaptime);\fR +.RE + +.SS "kstat data types" +.sp +.LP +The following types of kstats are currently available: +.sp +.in +2 +.nf +#define KSTAT_TYPE_RAW 0 /* can be anything */ +#define KSTAT_TYPE_NAMED 1 /* name/value pairs */ +#define KSTAT_TYPE_INTR 2 /* interrupt statistics */ +#define KSTAT_TYPE_IO 3 /* I/O statistics */ +#define KSTAT_TYPE_TIMER 4 /* event timers */ +.fi +.in -2 + +.sp +.LP +To get a list of all kstat types currently supported in the system, tools can +read out the standard system kstat \fIkstat_types\fR (full name spec is +\fI<``unix'', 0, ``kstat_types''>\fR). This is a \fBKSTAT_TYPE_NAMED\fR kstat +in which the \fIname\fR field describes the type of kstat, and the \fIvalue\fR +field is the kstat type number (for example, \fBKSTAT_TYPE_IO\fR is type 3 -- +see above). +.SS "Raw kstat" +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_RAW\fR\fR +.ad +.RS 18n +.rt +raw data +.RE + +.sp +.LP +The "raw" kstat type is just treated as an array of bytes. This is generally +used to export well-known structures, like \fIsysinfo\fR. +.SS "Name=value kstat" +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_NAMED\fR\fR +.ad +.RS 20n +.rt +A list of arbitrary \fIname=value\fR statistics. +.RE + +.sp +.in +2 +.nf +typedef struct kstat_named { + char name[KSTAT_STRLEN]; /* name of counter */ + uchar_t data_type; /* data type */ + union { + charc[16]; /* enough for 128-bit ints */ + struct { + union { + char *ptr; /* NULL-terminated string */ + } addr; + uint32_t len; /* length of string */ + } str; + int32_t i32; + uint32_t ui32; + int64_t i64; + uint64_t ui64; + + /* These structure members are obsolete */ + + int32_t l; + uint32_t ul; + int64_t ll; + uint64_t ull; + } value; /* value of counter */ +} kstat_named_t; + +/* The following types are Stable + +KSTAT_DATA_CHAR +KSTAT_DATA_INT32 +KSTAT_DATA_LONG +KSTAT_DATA_UINT32 +KSTAT_DATA_ULONG +KSTAT_DATA_INT64 +KSTAT_DATA_UINT64 + +/* The following type is Evolving */ + +KSTAT_DATA_STRING + +/* The following types are Obsolete */ + +KSTAT_DATA_LONGLONG +KSTAT_DATA_ULONGLONG +KSTAT_DATA_FLOAT +KSTAT_DATA_DOUBLE +.fi +.in -2 + +.sp +.LP +Some devices need to publish strings that exceed the maximum value for +\fBKSTAT_DATA_CHAR\fR in length; \fBKSTAT_DATA_STRING\fR is a data type that +allows arbitrary-length strings to be associated with a named kstat. The macros +below are the supported means to read the pointer to the string and its length. +.sp +.in +2 +.nf +#define KSTAT_NAMED_STR_PTR(knptr) ((knptr)->value.str.addr.ptr) +#define KSTAT_NAMED_STR_BUFLEN(knptr) ((knptr)->value.str.len) +.fi +.in -2 +.sp + +.sp +.LP +\fBKSTAT_NAMED_STR_BUFLEN()\fR returns the number of bytes required to store +the string pointed to by \fBKSTAT_NAMED_STR_PTR()\fR; that is, +\fBstrlen(KSTAT_NAMED_STR_PTR()) + 1\fR. +.SS "Interrupt kstat" +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_INTR\fR\fR +.ad +.RS 19n +.rt +Interrupt statistics. +.RE + +.sp +.LP +An interrupt is a hard interrupt (sourced from the hardware device itself), a +soft interrupt (induced by the system via the use of some system interrupt +source), a watchdog interrupt (induced by a periodic timer call), spurious (an +interrupt entry point was entered but there was no interrupt to service), or +multiple service (an interrupt was detected and serviced just prior to +returning from any of the other types). +.sp +.in +2 +.nf +#define KSTAT_INTR_HARD 0 +#define KSTAT_INTR_SOFT 1 +#define KSTAT_INTR_WATCHDOG 2 +#define KSTAT_INTR_SPURIOUS 3 +#define KSTAT_INTR_MULTSVC 4 +#define KSTAT_NUM_INTRS 5 + +typedef struct kstat_intr { + uint_t intrs[KSTAT_NUM_INTRS]; /* interrupt counters */ +} kstat_intr_t; +.fi +.in -2 + +.SS "Event timer kstat" +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_TIMER\fR\fR +.ad +.RS 20n +.rt +Event timer statistics. +.RE + +.sp +.LP +These provide basic counting and timing information for any type of event. +.sp +.in +2 +.nf +typedef struct kstat_timer { + char name[KSTAT_STRLEN]; /* event name */ + uchar_t resv; /* reserved */ + u_longlong_t num_events; /* number of events */ + hrtime_t elapsed_time; /* cumulative elapsed time */ + hrtime_t min_time; /* shortest event duration */ + hrtime_t max_time; /* longest event duration */ + hrtime_t start_time; /* previous event start time */ + hrtime_t stop_time; /* previous event stop time */ +} kstat_timer_t; +.fi +.in -2 + +.SS "I/O kstat" +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_IO\fR\fR +.ad +.RS 17n +.rt +I/O statistics. +.RE + +.sp +.in +2 +.nf +typedef struct kstat_io { +/* + * Basic counters. + */ +u_longlong_t nread; /* number of bytes read */ +u_longlong_t nwritten; /* number of bytes written */ +uint_t reads; /* number of read operations */ +uint_t writes; /* number of write operations */ +/* +* Accumulated time and queue length statistics. +* +* Time statistics are kept as a running sum of "active" time. +* Queue length statistics are kept as a running sum of the +* product of queue length and elapsed time at that length -- +* that is, a Riemann sum for queue length integrated against time. +* +* ^ +* | _________ +* 8 | i4 | +* | | | +* Queue 6 | | +* Length | _________ | | +* 4 | i2 |_______| | +* | | i3 | +* 2_______| | +* | i1 | +* |_______________________________| +* Time-> t1 t2 t3 t4 +* +* At each change of state (entry or exit from the queue), +* we add the elapsed time (since the previous state change) +* to the active time if the queue length was non-zero during +* that interval; and we add the product of the elapsed time +* times the queue length to the running length*time sum. +* +* This method is generalizable to measuring residency +* in any defined system: instead of queue lengths, think +* of "outstanding RPC calls to server X". +* +* A large number of I/O subsystems have at least two basic +* "lists" of transactions they manage: one for transactions +* that have been accepted for processing but for which processing +* has yet to begin, and one for transactions which are actively +* being processed (but not done). For this reason, two cumulative +* time statistics are defined here: pre-service (wait) time, +* and service (run) time. +* +* The units of cumulative busy time are accumulated nanoseconds. +* The units of cumulative length*time products are elapsed time +* times queue length. +*/ +hrtime_t wtime; /* cumulative wait (pre-service) time */ +hrtime_t wlentime; /* cumulative wait length*time product*/ +hrtime_t wlastupdate; /* last time wait queue changed */ +hrtime_t rtime; /* cumulative run (service) time */ +hrtime_t rlentime; /* cumulative run length*time product */ +hrtime_t rlastupdate; /* last time run queue changed */ +uint_t wcnt; /* count of elements in wait state */ +uint_t rcnt; /* count of elements in run state */ +} kstat_io_t; +.fi +.in -2 +.sp + +.SS "Using libkstat" +.sp +.LP +The kstat library, \fBlibkstat\fR, defines the user interface (API) to the +system's kstat facility. +.sp +.LP +You begin by opening libkstat with \fBkstat_open\fR(3KSTAT), which returns a +pointer to a fully initialized kstat control structure. This is your ticket to +subsequent libkstat operations: +.sp +.in +2 +.nf +typedef struct kstat_ctl { + kid_t kc_chain_id; /* current kstat chain ID */ + kstat_t *kc_chain; /* pointer to kstat chain */ + int kc_kd; /* /dev/kstat descriptor */ +} kstat_ctl_t; +.fi +.in -2 + +.sp +.LP +Only the first two fields, \fBkc_chain_id\fR and \fBkc_chain\fR, are of +interest to \fBlibkstat\fR clients. (\fIkc_kd\fR is the descriptor for +\fB/dev/kstat\fR, the kernel statistics driver. libkstat functions are built on +top of \fB/dev/kstat\fR \fBioctl\fR(2) primitives. Direct interaction with +\fB/dev/kstat\fR is strongly discouraged, since it is \fInot\fR a public +interface.) +.sp +.LP +\fBkc_chain\fR points to your copy of the kstat chain. You typically walk the +chain to find and process a certain kind of kstat. For example, to display all +\fBI/O\fR kstats: +.sp +.in +2 +.nf +kstat_ctl_t *kc; +kstat_t *ksp; +kstat_io_t kio; + +kc = kstat_open(); +for (ksp = kc->kc_chain; ksp != NULL; ksp = ksp->ks_next) { + if (ksp->ks_type == KSTAT_TYPE_IO) { + kstat_read(kc, ksp, &kio); + my_io_display(kio); + } +} +.fi +.in -2 + +.sp +.LP +\fBkc_chain_id\fR is the kstat chain \fBID\fR, or \fBKCID\fR, of your copy of +the kstat chain. See \fBkstat_chain_update\fR(3KSTAT) for an explanation of +\fBKCID\fRs. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/dev/kstat\fR\fR +.ad +.RS 28n +.rt +kernel statistics driver +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/include/kstat.h\fR\fR +.ad +.RS 28n +.rt +header +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/usr/include/sys/kstat.h\fR\fR +.ad +.RS 28n +.rt +header +.RE + +.SH SEE ALSO +.sp +.LP +\fBioctl\fR(2), \fBgethrtime\fR(3C), \fBgetloadavg\fR(3C), +\fBkstat_chain_update\fR(3KSTAT), \fBkstat_close\fR(3KSTAT), +\fBkstat_data_lookup\fR(3KSTAT), \fBkstat_lookup\fR(3KSTAT), +\fBkstat_open\fR(3KSTAT), \fBkstat_read\fR(3KSTAT), \fBkstat_write\fR(3KSTAT), +\fBattributes\fR(5) diff --git a/usr/src/man/man3kstat/kstat_chain_update.3kstat b/usr/src/man/man3kstat/kstat_chain_update.3kstat new file mode 100644 index 0000000000..450c04add4 --- /dev/null +++ b/usr/src/man/man3kstat/kstat_chain_update.3kstat @@ -0,0 +1,129 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH kstat_chain_update 3KSTAT "3 Aug 2004" "SunOS 5.11" "Kernel Statistics Library Functions" +.SH NAME +kstat_chain_update \- update the kstat header chain +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkstat\fR [ \fIlibrary\fR\&.\|.\|.] +#include <kstat.h> + + + +\fBkid_t\fR \fBkstat_chain_update\fR(\fBkstat_ctl_t *\fR\fIkc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBkstat_chain_update()\fR function brings the user's kstat header chain in +sync with that of the kernel. The kstat chain is a linked list of kstat headers +(\fBkstat_t\fR's) pointed to by \fIkc\fR->\fBkc_chain\fR, which is initialized +by \fBkstat_open\fR(3KSTAT). This chain constitutes a list of all kstats +currently in the system. +.sp +.LP +During normal operation, the kernel creates new kstats and delete old ones as +various device instances are added and removed, thereby causing the user's copy +of the kstat chain to become out of date. The \fBkstat_chain_update()\fR +function detects this condition by comparing the kernel's current kstat chain +ID (KCID), which is incremented every time the kstat chain changes, to the +user's KCID, \fIkc\fR->\fBkc_chain_id\fR. If the KCIDs match, +\fBkstat_chain_update()\fR does nothing. Otherwise, it deletes any invalid +kstat headers from the user's kstat chain, adds any new ones, and sets +\fIkc\fR->\fBkc_chain_id\fR to the new KCID. All other kstat headers in the +user's kstat chain are unmodified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBkstat_chain_update()\fR returns the new KCID if +the kstat chain has changed and 0 if it has not changed. Otherwise, it returns +\(mi1 and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBkstat_chain_update()\fR function will fail if: +.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\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. +.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 + +.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 StabilityStable +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkstat\fR(3KSTAT), \fBkstat_lookup\fR(3KSTAT), \fBkstat_open\fR(3KSTAT), +\fBkstat_read\fR(3KSTAT), \fBattributes\fR(5) diff --git a/usr/src/man/man3kstat/kstat_lookup.3kstat b/usr/src/man/man3kstat/kstat_lookup.3kstat new file mode 100644 index 0000000000..c57616c872 --- /dev/null +++ b/usr/src/man/man3kstat/kstat_lookup.3kstat @@ -0,0 +1,113 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH kstat_lookup 3KSTAT "3 Aug 2004" "SunOS 5.11" "Kernel Statistics Library Functions" +.SH NAME +kstat_lookup, kstat_data_lookup \- find a kstat by name +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkstat\fR [ \fIlibrary\fR\&.\|.\|.] +#include <kstat.h> + +\fBkstat_t *\fR\fBkstat_lookup\fR(\fBkstat_ctl_t *\fR\fIkc\fR, \fBchar *\fR\fIks_module\fR, \fBint\fR \fIks_instance\fR, + \fBchar *\fR\fIks_name\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBkstat_data_lookup\fR(\fBkstat_t *\fR\fIksp\fR, \fBchar *\fR\fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBkstat_lookup()\fR function traverses the kstat chain, +\fIkc\fR->\fBkc_chain\fR, searching for a kstat with the same \fIks_module\fR, +\fIks_instance\fR, and \fIks_name\fR fields; this triplet uniquely identifies a +kstat. If \fIks_module\fR is \fINULL\fR, \fIks_instance\fR is -1, or +\fIks_name\fR is \fINULL\fR, those fields will be ignored in the search. For +example, \fBkstat_lookup(kc, NULL, -1, "foo")\fR will find the first kstat +with name "foo". +.sp +.LP +The \fBkstat_data_lookup()\fR function searches the kstat's data section for +the record with the specified \fIname\fR. This operation is valid only for +those kstat types that have named data records: \fBKSTAT_TYPE_NAMED\fR and +\fBKSTAT_TYPE_TIMER\fR. +.SH RETURN VALUES +.sp +.LP +The \fBkstat_lookup()\fR function returns a pointer to the requested kstat if +it is found. Otherwise it returns \fINULL\fR and sets \fBerrno\fR to indicate +the error. +.sp +.LP +The \fBkstat_data_lookup()\fR function returns a pointer to the requested data +record if it is found. Otherwise it returns \fINULL\fR and sets \fBerrno\fR to +indicate the error . +.SH ERRORS +.sp +.LP +The \fBkstat_lookup()\fR and \fBkstat_data_lookup()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +An attempt was made to look up data for a kstat that was not of type +\fBKSTAT_TYPE_NAMED\fR or \fBKSTAT_TYPE_TIMER\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 10n +.rt +The requested kstat could not be found. +.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 StabilityStable +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkstat\fR(3KSTAT), \fBkstat_chain_update\fR(3KSTAT), +\fBkstat_open\fR(3KSTAT), \fBkstat_read\fR(3KSTAT), \fBattributes\fR(5) diff --git a/usr/src/man/man3kstat/kstat_open.3kstat b/usr/src/man/man3kstat/kstat_open.3kstat new file mode 100644 index 0000000000..680c6006ce --- /dev/null +++ b/usr/src/man/man3kstat/kstat_open.3kstat @@ -0,0 +1,136 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH kstat_open 3KSTAT "3 Aug 2004" "SunOS 5.11" "Kernel Statistics Library Functions" +.SH NAME +kstat_open, kstat_close \- initialize kernel statistics facility +.SH SYNOPSIS +.LP +.nf +\fBcc\fR[ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkstat\fR [ \fIlibrary\fR\&.\|.\|.] +#include <kstat.h> + +\fBkstat_ctl_t *\fR\fBkstat_open\fR(\fB\fR\fIvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBkstat_close\fR(\fBkstat_ctl_t *\fR\fIkc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBkstat_open()\fR function initializes a kstat control structure that +provides access to the kernel statistics library. It returns a pointer to this +structure, which must be supplied as the \fIkc\fR argument in subsequent +\fBlibkstat\fR function calls. +.sp +.LP +The \fBkstat_close()\fR function frees all resources that were associated with +\fIkc\fR. This is performed automatically on \fBexit\fR(2) and \fBexecve\fR(2). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBkstat_open()\fR returns a pointer to a kstat +control structure. Otherwise, it returns \fINULL\fR, no resources are +allocated, and \fBerrno\fR is set to indicate the error. +.sp +.LP +Upon successful completion, \fBkstat_close()\fR returns 0. Otherwise, \(mi1 is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBkstat_open()\fR function will fail if: +.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\fBEAGAIN\fR\fR +.ad +.RS 13n +.rt +The kstat was temporarily unavailable for reading or writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 13n +.rt +The given kstat could not be located for reading. +.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 +.LP +The \fBkstat_open()\fR function can also return the error values for +\fBopen\fR(2). +.sp +.LP +The \fBkstat_close()\fR function can also return the error values for +\fBclose\fR(2). +.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 StabilityStable +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBexecve\fR(2), \fBopen\fR(2), \fBexit\fR(2), +\fBkstat\fR(3KSTAT), \fBkstat_chain_update\fR(3KSTAT), +\fBkstat_lookup\fR(3KSTAT), \fBkstat_read\fR(3KSTAT), \fBattributes\fR(5) diff --git a/usr/src/man/man3kstat/kstat_read.3kstat b/usr/src/man/man3kstat/kstat_read.3kstat new file mode 100644 index 0000000000..67446c58ac --- /dev/null +++ b/usr/src/man/man3kstat/kstat_read.3kstat @@ -0,0 +1,164 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH kstat_read 3KSTAT "3 Aug 2004" "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 StabilityStable +_ +MT-LevelUnsafe +.TE + +.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) |