svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
kstat(3kstat)
kstat(3KSTAT) Kernel Statistics Library Functions kstat(3KSTAT)
NAME
kstat - obsolete kernel statistics facility
DESCRIPTION
The kstat facility is a general-purpose mechanism for providing kernel
statistics to users.
The kstat model
The kernel maintains a linked list of statistics structures, or kstats.
Each kstat has a common header section and a type-specific data sec‐
tion. The header section is defined by the kstat_t structure:
kstat header
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;
The fields that are of significance to the user are:
ks_crtime The time the kstat was created. This allows you to com‐
pute the rates of various counters since the kstat was
created; "rate since boot" is replaced by the more gen‐
eral concept of "rate since kstat creation". All times
associated with kstats (such as creation time, last
snapshot time, kstat_timer_t and kstat_io_t timestamps,
and the like) are 64-bit nanosecond values. The accu‐
racy of kstat timestamps is machine dependent, but the
precision (units) is the same across all platforms. See
gethrtime(3C) for general information about high-reso‐
lution timestamps.
ks_next kstats are stored as a linked list, or chain. ks_next
points to the next kstat in the chain.
ks_kid A unique identifier for the kstat.
ks_module, contain the name and instance of the module that cre‐
ks_instance ated the kstat. In cases where there can only be one
instance, ks_instance is 0.
ks_name gives a meaningful name to a kstat. The full kstat
namespace is <ks_module,ks_instance,ks_name>, so the
name only need be unique within a module.
ks_type The type of data in this kstat. kstat data types are
discussed below.
ks_class 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 ex‐
tract related kstats. The following values are cur‐
rently in use: disk, tape, controller, net, rpc, vm,
kvm, hat, streams, kmem, kmem_cache, kstat, and misc.
(The kstat class encompasses things like kstat_types.)
ks_data, ks_data is a pointer to the kstat's data section. The
ks_ndata, type of data stored there depends on ks_type. ks_ndata
ks_data_size indicates the number of data records. Only some kstat
types support multiple data records. Currently,
KSTAT_TYPE_RAW, KSTAT_TYPE_NAMED and KSTAT_TYPE_TIMER
kstats support multiple data records. KSTAT_TYPE_INTR
and KSTAT_TYPE_IO kstats support only one data record.
ks_data_size is the total size of the data section, in
bytes.
ks_snaptime The timestamp for the last data snapshot. This allows
you to compute activity rates:
rate = (new_count - old_count) / (new_snaptime -
old_snaptime);
kstat data types
The following types of kstats are currently available:
#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 */
To get a list of all kstat types currently supported in the system,
tools can read out the standard system kstat kstat_types (full name
spec is <"unix", 0, "kstat_types">). This is a KSTAT_TYPE_NAMED kstat
in which the name field describes the type of kstat, and the value
field is the kstat type number (for example, KSTAT_TYPE_IO is type 3 --
see above).
Raw kstat
KSTAT_TYPE_RAW raw data
The "raw" kstat type is just treated as an array of bytes. This is gen‐
erally used to export well-known structures, like sysinfo.
Name=value kstat
KSTAT_TYPE_NAMED A list of arbitrary name=value statistics.
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 Committed
KSTAT_DATA_CHAR
KSTAT_DATA_INT32
KSTAT_DATA_LONG
KSTAT_DATA_STRING
KSTAT_DATA_UINT32
KSTAT_DATA_ULONG
KSTAT_DATA_INT64
KSTAT_DATA_UINT64
/* The following types are Obsolete */
KSTAT_DATA_LONGLONG
KSTAT_DATA_ULONGLONG
KSTAT_DATA_FLOAT
KSTAT_DATA_DOUBLE
Some devices need to publish strings that exceed the maximum value for
KSTAT_DATA_CHAR in length; KSTAT_DATA_STRING 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.
#define KSTAT_NAMED_STR_PTR(knptr) ((knptr)->value.str.addr.ptr)
#define KSTAT_NAMED_STR_BUFLEN(knptr) ((knptr)->value.str.len)
KSTAT_NAMED_STR_BUFLEN() returns the number of bytes required to store
the string pointed to by KSTAT_NAMED_STR_PTR(); that is,
strlen(KSTAT_NAMED_STR_PTR()) + 1.
Interrupt kstat
KSTAT_TYPE_INTR Interrupt statistics.
An interrupt is a hard interrupt (sourced from the hardware device it‐
self), a soft interrupt (induced by the system via the use of some sys‐
tem 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 de‐
tected and serviced just prior to returning from any of the other
types).
#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;
Event timer kstat
KSTAT_TYPE_TIMER Event timer statistics.
These provide basic counting and timing information for any type of
event.
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;
I/O kstat
KSTAT_TYPE_IO I/O statistics.
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;
Using libkstat
The kstat library, libkstat, defines the user interface (API) to the
system's kstat facility.
You begin by opening libkstat with kstat_open(3KSTAT), which returns a
pointer to a fully initialized kstat control structure. This is your
ticket to subsequent libkstat operations:
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;
Only the first two fields, kc_chain_id and kc_chain, are of interest to
libkstat clients. (kc_kd is the descriptor for /dev/kstat, the kernel
statistics driver. libkstat functions are built on top of /dev/kstat
ioctl(2) primitives. Direct interaction with /dev/kstat is strongly
discouraged, since it is not a public interface.)
kc_chain 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 dis‐
play all I/O kstats:
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);
}
}
kc_chain_id is the kstat chain ID, or KCID, of your copy of the kstat
chain. See kstat_chain_update(3KSTAT) for an explanation of KCIDs.
FILES
/dev/kstat kernel statistics driver
/usr/include/kstat.h header
/usr/include/sys/kstat.h header
SEE ALSO
ioctl(2), gethrtime(3C), getloadavg(3C), kstat_chain_update(3KSTAT),
kstat_close(3KSTAT), kstat_data_lookup(3KSTAT), kstat_lookup(3KSTAT),
kstat_open(3KSTAT), kstat_read(3KSTAT), kstat_write(3KSTAT), attrib‐
utes(7), kstat2(3KSTAT2), kstat2_open(3KSTAT2),
kstat2_lookup_map(3KSTAT2), kstat2_map_get(3KSTAT2), kstat2_up‐
date(3KSTAT2), kstat2_close(3KSTAT2)
NOTES
The facility described in this document is deprecated and may be re‐
moved in a future release of Oracle Solaris. Use the kstat2() function
instead. For more information, see the kstat2(3KSTAT2) man page.
Oracle Solaris 11.4 02 Feb 2017 kstat(3KSTAT)