kstat-1 - API for kernel statistics
#include <rad/client/1/kstat.h>
cc [ flag... ] file... -lkstat1_client [ library... ]
interface Kstat
kstat_Kstatinfo_t * info ; (ro)
boolean_t stale ; (ro)
kstat_Snapshot_t * snapshot ; (ro)
rc_err_t kstat_Kstat_fresh_snapshot(rc_instance_t *inst,
kstat_Snapshot_t **result);
interface Control
rc_err_t kstat_Control_update(rc_instance_t *inst);
Enumerated Types
enum Ksdtype
typedef enum kstat_Ksdtype {
KK_CHAR = 0,
KK_INT32 = 1,
KK_UINT32 = 2,
KK_INT64 = 3,
KK_UINT64 = 4,
KK_FLOAT = 5,
KK_DOUBLE = 6,
KK_STRING = 7,
} kstat_Ksdtype_t;
enum Kstype
typedef enum kstat_Kstype {
KK_RAW = 0,
KK_NAMED = 1,
KK_INTR = 2,
KK_IO = 3,
KK_TIMER = 4,
KK_UNKNOWN = 5,
} kstat_Kstype_t;
Structured Types
struct Ksvalue
typedef struct kstat_Ksvalue kstat_Ksvalue_t;
struct kstat_Ksvalue {
kstat_Ksdtype_t kk_discriminant;
char *kk_CHAR;
int kk_INT32;
unsigned int kk_UINT32;
long long kk_INT64;
unsigned long long kk_UINT64;
float kk_FLOAT;
double kk_DOUBLE;
char *kk_STRING;
};
void kstat_Ksvalue_free(kstat_Ksvalue_t *in);
struct Kstat_named
typedef struct kstat_Kstat_named kstat_Kstat_named_t;
struct kstat_Kstat_named {
char *kkn_name;
kstat_Ksvalue_t *kkn_value;
};
void kstat_Kstat_named_free(kstat_Kstat_named_t *in);
struct Kstat_intr
typedef struct kstat_Kstat_intr kstat_Kstat_intr_t;
struct kstat_Kstat_intr {
unsigned int kki_hard;
unsigned int kki_soft;
unsigned int kki_watchdog;
unsigned int kki_spurious;
unsigned int kki_multsvc;
};
void kstat_Kstat_intr_free(kstat_Kstat_intr_t *in);
struct Kstat_timer
typedef struct kstat_Kstat_timer kstat_Kstat_timer_t;
struct kstat_Kstat_timer {
char *kkt_name;
unsigned long long kkt_num_events;
unsigned long long kkt_elapsed_time;
unsigned long long kkt_min_time;
unsigned long long kkt_max_time;
unsigned long long kkt_start_time;
unsigned long long kkt_stop_time;
};
void kstat_Kstat_timer_free(kstat_Kstat_timer_t *in);
struct Kstat_io
typedef struct kstat_Kstat_io kstat_Kstat_io_t;
struct kstat_Kstat_io {
unsigned long long kki_nread;
unsigned long long kki_nwritten;
unsigned int kki_reads;
unsigned int kki_writes;
unsigned long long kki_wtime;
unsigned long long kki_wlentime;
unsigned long long kki_wlastupdate;
unsigned long long kki_rtime;
unsigned long long kki_rlentime;
unsigned long long kki_rlastupdate;
unsigned int kki_wcnt;
unsigned int kki_rcnt;
};
void kstat_Kstat_io_free(kstat_Kstat_io_t *in);
struct Ksdata
typedef struct kstat_Ksdata kstat_Ksdata_t;
struct kstat_Ksdata {
kstat_Kstype_t kk_discriminant;
rc_opaque_t *kk_RAW;
kstat_Kstat_named_t **kk_NAMED;
int kk_NAMED_count;
kstat_Kstat_intr_t *kk_INTR;
kstat_Kstat_io_t *kk_IO;
kstat_Kstat_timer_t **kk_TIMER;
int kk_TIMER_count;
char *kk_UNKNOWN;
};
void kstat_Ksdata_free(kstat_Ksdata_t *in);
struct Snapshot
typedef struct kstat_Snapshot kstat_Snapshot_t;
struct kstat_Snapshot {
unsigned long long ks_snaptime;
kstat_Ksdata_t *ks_data;
};
void kstat_Snapshot_free(kstat_Snapshot_t *in);
struct Kstatinfo
typedef struct kstat_Kstatinfo kstat_Kstatinfo_t;
struct kstat_Kstatinfo {
char *kk_module;
char *kk_name;
char *kk_klass;
int kk_instance;
kstat_Kstype_t kk_type;
unsigned long long kk_crtime;
};
void kstat_Kstatinfo_free(kstat_Kstatinfo_t *in);
KSTAT-1(3rad) RAD Module Definitions KSTAT-1(3rad)
NAME
kstat - API for kernel statistics
SYNOPSIS
#include <rad/client/1/kstat.h>
cc [ flag... ] file... -lkstat1_client [ library... ]
interface Kstat
kstat_Kstatinfo_t * info ; (ro)
boolean_t stale ; (ro)
kstat_Snapshot_t * snapshot ; (ro)
rc_err_t kstat_Kstat_fresh_snapshot(rc_instance_t *inst,
kstat_Snapshot_t **result);
interface Control
rc_err_t kstat_Control_update(rc_instance_t *inst);
Enumerated Types
enum Ksdtype
typedef enum kstat_Ksdtype {
KK_CHAR = 0,
KK_INT32 = 1,
KK_UINT32 = 2,
KK_INT64 = 3,
KK_UINT64 = 4,
KK_FLOAT = 5,
KK_DOUBLE = 6,
KK_STRING = 7,
} kstat_Ksdtype_t;
enum Kstype
typedef enum kstat_Kstype {
KK_RAW = 0,
KK_NAMED = 1,
KK_INTR = 2,
KK_IO = 3,
KK_TIMER = 4,
KK_UNKNOWN = 5,
} kstat_Kstype_t;
Structured Types
struct Ksvalue
typedef struct kstat_Ksvalue kstat_Ksvalue_t;
struct kstat_Ksvalue {
kstat_Ksdtype_t kk_discriminant;
char *kk_CHAR;
int kk_INT32;
unsigned int kk_UINT32;
long long kk_INT64;
unsigned long long kk_UINT64;
float kk_FLOAT;
double kk_DOUBLE;
char *kk_STRING;
};
void kstat_Ksvalue_free(kstat_Ksvalue_t *in);
struct Kstat_named
typedef struct kstat_Kstat_named kstat_Kstat_named_t;
struct kstat_Kstat_named {
char *kkn_name;
kstat_Ksvalue_t *kkn_value;
};
void kstat_Kstat_named_free(kstat_Kstat_named_t *in);
struct Kstat_intr
typedef struct kstat_Kstat_intr kstat_Kstat_intr_t;
struct kstat_Kstat_intr {
unsigned int kki_hard;
unsigned int kki_soft;
unsigned int kki_watchdog;
unsigned int kki_spurious;
unsigned int kki_multsvc;
};
void kstat_Kstat_intr_free(kstat_Kstat_intr_t *in);
struct Kstat_timer
typedef struct kstat_Kstat_timer kstat_Kstat_timer_t;
struct kstat_Kstat_timer {
char *kkt_name;
unsigned long long kkt_num_events;
unsigned long long kkt_elapsed_time;
unsigned long long kkt_min_time;
unsigned long long kkt_max_time;
unsigned long long kkt_start_time;
unsigned long long kkt_stop_time;
};
void kstat_Kstat_timer_free(kstat_Kstat_timer_t *in);
struct Kstat_io
typedef struct kstat_Kstat_io kstat_Kstat_io_t;
struct kstat_Kstat_io {
unsigned long long kki_nread;
unsigned long long kki_nwritten;
unsigned int kki_reads;
unsigned int kki_writes;
unsigned long long kki_wtime;
unsigned long long kki_wlentime;
unsigned long long kki_wlastupdate;
unsigned long long kki_rtime;
unsigned long long kki_rlentime;
unsigned long long kki_rlastupdate;
unsigned int kki_wcnt;
unsigned int kki_rcnt;
};
void kstat_Kstat_io_free(kstat_Kstat_io_t *in);
struct Ksdata
typedef struct kstat_Ksdata kstat_Ksdata_t;
struct kstat_Ksdata {
kstat_Kstype_t kk_discriminant;
rc_opaque_t *kk_RAW;
kstat_Kstat_named_t **kk_NAMED;
int kk_NAMED_count;
kstat_Kstat_intr_t *kk_INTR;
kstat_Kstat_io_t *kk_IO;
kstat_Kstat_timer_t **kk_TIMER;
int kk_TIMER_count;
char *kk_UNKNOWN;
};
void kstat_Ksdata_free(kstat_Ksdata_t *in);
struct Snapshot
typedef struct kstat_Snapshot kstat_Snapshot_t;
struct kstat_Snapshot {
unsigned long long ks_snaptime;
kstat_Ksdata_t *ks_data;
};
void kstat_Snapshot_free(kstat_Snapshot_t *in);
struct Kstatinfo
typedef struct kstat_Kstatinfo kstat_Kstatinfo_t;
struct kstat_Kstatinfo {
char *kk_module;
char *kk_name;
char *kk_klass;
int kk_instance;
kstat_Kstype_t kk_type;
unsigned long long kk_crtime;
};
void kstat_Kstatinfo_free(kstat_Kstatinfo_t *in);
DESCRIPTION
API com.oracle.solaris.rad.kstat [1]
This API exposes kernel statistics, or kstats, to rad(8) clients.
Two core interfaces are provided:
1. Kstat - an object that represents a kstat
2. Control - an administration object
Python kstat wrapper.
INTERFACES
interface Kstat
The Kstat interface represents a kernel statistic. Handles to this type
of object can be retrieved from the RAD server using a kstat proxy
object. To retrieve a specific instance, be aware of these additional
keys:
1. a key named "class" paired with a kstat class
2. a key named "module" paired with a kstat module
3. a key named "instance" paired with a kstat module (integer)
instance
4. a key named "name" paired with a kstat name
For example, to print statistics about a particular CPU on a system:
Kstat Properties
kstat_Kstatinfo_t * info (read-only) -- static kstat information
rc_err_t kstat_Kstat_get_info(rc_instance_t *inst,
kstat_Kstatinfo_t **result);
Get property value.
Arguments:
inst -- RAD instance
result -- Property value returned
boolean_t stale (read-only) -- true if the kstat doesn't exist
kstats are often associated with parts of the system that can
come and go over time, and likewise will come and go. To
simplify consumers, a kstat object once referenced will remain
but be marked stale when the underlying kstat object goes away.
rc_err_t kstat_Kstat_get_stale(rc_instance_t *inst,
boolean_t *result);
Get property value.
Arguments:
inst -- RAD instance
result -- Property value returned
kstat_Snapshot_t * snapshot (read-only) -- a snapshot of the kstat
as of the last update
rc_err_t kstat_Kstat_get_snapshot(rc_instance_t *inst,
kstat_Snapshot_t **result);
Get property value.
Arguments:
inst -- RAD instance
result -- Property value returned
Read Error: void ** -- the kstat doesn't currently exist
Kstat Methods
rc_err_t kstat_Kstat_fresh_snapshot(rc_instance_t *inst,
kstat_Snapshot_t **result);
obtains a fresh snapshot of the kstat
Arguments:
inst -- RAD instance
result
Kstat Retrieve
rc_err_t kstat_Kstat__rad_get_name(adr_name_t **result,
int n,
...);
Obtain RAD name of a Kstat object.
Arguments:
result -- RAD name
n -- Number of key-value pairs provided as variadic arguments
... -- Optional key-value pairs that compose the primary key
rc_err_t kstat_Kstat__rad_lookup(rc_conn_t *c,
boolean_t strict,
rc_instance_t **result,
int n,
...);
Lookup a Kstat instance.
Construct a RAD name for the interface based on the provided
key-value pairs and perform a lookup. If successful, instance
reference is returned in the result.
Arguments:
c -- RAD connection handle
strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning
result -- RAD instance
n -- Number of key-value pairs provided as variadic arguments
... -- Optional key-value pairs that compose the primary key
rc_err_t kstat_Kstat__rad_list(rc_conn_t *c,
boolean_t strict,
adr_pattern_scheme_t scheme,
adr_name_t ***result,
int *result_count,
int n,
...);
List RAD names of a available Kstat instances.
Returns an array and array size of matching object names.
Arguments:
c -- RAD connection handle
strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning
scheme -- Apply glob (NS_GLOB) or regex (NS_REGEX) matching
result -- Array of RAD names
result_count -- Number of names in result array
n -- Number of key-value pairs provided as variadic arguments
... -- Optional key-value pairs that compose the primary key
interface Control
The Control interface is an administrative API into the kstats
subsystem. Handles to this type of object can be retrieved from the RAD
server using a simple object proxy.
Control Methods
rc_err_t kstat_Control_update(rc_instance_t *inst);
update the kstat chain
Updates the kstat chain. All referenced kstats' snapshots are
updated. After update, the set of available kstats may change.
Arguments:
inst -- RAD instance
Control Retrieve
rc_err_t kstat_Control__rad_get_name(adr_name_t **result,
int n,
...);
Obtain RAD name of a Control object.
Arguments:
result -- RAD name
n -- Number of key-value pairs provided as variadic arguments
... -- Optional key-value pairs that compose the primary key
rc_err_t kstat_Control__rad_lookup(rc_conn_t *c,
boolean_t strict,
rc_instance_t **result,
int n,
...);
Lookup a Control instance.
Construct a RAD name for the interface based on the provided
key-value pairs and perform a lookup. If successful, instance
reference is returned in the result.
Arguments:
c -- RAD connection handle
strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning
result -- RAD instance
n -- Number of key-value pairs provided as variadic arguments
... -- Optional key-value pairs that compose the primary key
rc_err_t kstat_Control__rad_list(rc_conn_t *c,
boolean_t strict,
adr_pattern_scheme_t scheme,
adr_name_t ***result,
int *result_count,
int n,
...);
List RAD names of a available Control instances.
Returns an array and array size of matching object names.
Arguments:
c -- RAD connection handle
strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning
scheme -- Apply glob (NS_GLOB) or regex (NS_REGEX) matching
result -- Array of RAD names
result_count -- Number of names in result array
n -- Number of key-value pairs provided as variadic arguments
... -- Optional key-value pairs that compose the primary key
ENUMERATED TYPES
enum Ksdtype -- a named kstat data value type
typedef enum kstat_Ksdtype {
KK_CHAR = 0,
KK_INT32 = 1,
KK_UINT32 = 2,
KK_INT64 = 3,
KK_UINT64 = 4,
KK_FLOAT = 5,
KK_DOUBLE = 6,
KK_STRING = 7,
} kstat_Ksdtype_t;
KK_CHAR (0) -- a string (of up to a fixed size)
KK_INT32 (1) -- a signed 32-bit integer
KK_UINT32 (2) -- an unsigned 32-bit integer
KK_INT64 (3) -- a signed 64-bit integer
KK_UINT64 (4) -- an unsigned 64-bit integer
KK_FLOAT (5) -- a 32-bit floating point number
KK_DOUBLE (6) -- a 64-bit floating point number
KK_STRING (7) -- an arbitrary lengthed string
enum Kstype -- kstat type
typedef enum kstat_Kstype {
KK_RAW = 0,
KK_NAMED = 1,
KK_INTR = 2,
KK_IO = 3,
KK_TIMER = 4,
KK_UNKNOWN = 5,
} kstat_Kstype_t;
KK_RAW (0) -- raw data, can be anything
KK_NAMED (1) -- name/value pairs
KK_INTR (2) -- interrupt statistics
KK_IO (3) -- I/O statistics
KK_TIMER (4) -- event timers
KK_UNKNOWN (5)
STRUCTURED TYPES
struct Ksvalue -- a named kstat data value
typedef struct kstat_Ksvalue kstat_Ksvalue_t;
struct kstat_Ksvalue {
kstat_Ksdtype_t kk_discriminant;
char *kk_CHAR;
int kk_INT32;
unsigned int kk_UINT32;
long long kk_INT64;
unsigned long long kk_UINT64;
float kk_FLOAT;
double kk_DOUBLE;
char *kk_STRING;
};
void kstat_Ksvalue_free(kstat_Ksvalue_t *in);
This is a struct representing a named kstat data value. Use the
discriminant enum to determine what type of data the value holds.
Fields:
kk_discriminant
kk_CHAR
kk_INT32
kk_UINT32
kk_INT64
kk_UINT64
kk_FLOAT
kk_DOUBLE
kk_STRING
struct Kstat_named -- a named kstat name/value pair
typedef struct kstat_Kstat_named kstat_Kstat_named_t;
struct kstat_Kstat_named {
char *kkn_name;
kstat_Ksvalue_t *kkn_value;
};
void kstat_Kstat_named_free(kstat_Kstat_named_t *in);
Fields:
kkn_name -- counter name
kkn_value -- counter value
struct Kstat_intr -- interrupt statistics
typedef struct kstat_Kstat_intr kstat_Kstat_intr_t;
struct kstat_Kstat_intr {
unsigned int kki_hard;
unsigned int kki_soft;
unsigned int kki_watchdog;
unsigned int kki_spurious;
unsigned int kki_multsvc;
};
void kstat_Kstat_intr_free(kstat_Kstat_intr_t *in);
Counters for various types of interrupts.
Fields:
kki_hard -- hardware interrupts
kki_soft -- soft interrupts
kki_watchdog -- watchdog interrupts
kki_spurious -- spurious interrupts
kki_multsvc -- multiple-service interrupts
struct Kstat_timer -- a timer kstat statistic
typedef struct kstat_Kstat_timer kstat_Kstat_timer_t;
struct kstat_Kstat_timer {
char *kkt_name;
unsigned long long kkt_num_events;
unsigned long long kkt_elapsed_time;
unsigned long long kkt_min_time;
unsigned long long kkt_max_time;
unsigned long long kkt_start_time;
unsigned long long kkt_stop_time;
};
void kstat_Kstat_timer_free(kstat_Kstat_timer_t *in);
Provides basic counting and timing information.
Fields:
kkt_name -- event name
kkt_num_events -- number of events
kkt_elapsed_time -- cumulative elapsed time
kkt_min_time -- shortest event duration
kkt_max_time -- longest event duration
kkt_start_time -- previous event start time
kkt_stop_time -- previous event stop time
struct Kstat_io -- I/O statistics
typedef struct kstat_Kstat_io kstat_Kstat_io_t;
struct kstat_Kstat_io {
unsigned long long kki_nread;
unsigned long long kki_nwritten;
unsigned int kki_reads;
unsigned int kki_writes;
unsigned long long kki_wtime;
unsigned long long kki_wlentime;
unsigned long long kki_wlastupdate;
unsigned long long kki_rtime;
unsigned long long kki_rlentime;
unsigned long long kki_rlastupdate;
unsigned int kki_wcnt;
unsigned int kki_rcnt;
};
void kstat_Kstat_io_free(kstat_Kstat_io_t *in);
Fields:
kki_nread -- number of bytes read
kki_nwritten -- number of bytes written
kki_reads -- number of read operations
kki_writes -- number of write operations
kki_wtime -- cumulative wait time
kki_wlentime -- cumulative wait length*time product
kki_wlastupdate -- last time wait queue changed
kki_rtime -- cumulative run time
kki_rlentime -- cumulative run length*time product
kki_rlastupdate -- last time run queue changed
kki_wcnt -- count of elements in wait state
kki_rcnt -- count of elements in run state
struct Ksdata -- typed kernel statistics data
typedef struct kstat_Ksdata kstat_Ksdata_t;
struct kstat_Ksdata {
kstat_Kstype_t kk_discriminant;
rc_opaque_t *kk_RAW;
kstat_Kstat_named_t **kk_NAMED;
int kk_NAMED_count;
kstat_Kstat_intr_t *kk_INTR;
kstat_Kstat_io_t *kk_IO;
kstat_Kstat_timer_t **kk_TIMER;
int kk_TIMER_count;
char *kk_UNKNOWN;
};
void kstat_Ksdata_free(kstat_Ksdata_t *in);
Use the discriminant enum to determine what type of data the
structure holds.
Fields:
kk_discriminant
kk_RAW
kk_NAMED
kk_NAMED_count
kk_INTR
kk_IO
kk_TIMER
kk_TIMER_count
kk_UNKNOWN
struct Snapshot -- a snapshot in time of a kernel statistic
typedef struct kstat_Snapshot kstat_Snapshot_t;
struct kstat_Snapshot {
unsigned long long ks_snaptime;
kstat_Ksdata_t *ks_data;
};
void kstat_Snapshot_free(kstat_Snapshot_t *in);
Fields:
ks_snaptime -- when this snapshot was taken
ks_data -- statistic snapshot data
struct Kstatinfo -- static kstat information
typedef struct kstat_Kstatinfo kstat_Kstatinfo_t;
struct kstat_Kstatinfo {
char *kk_module;
char *kk_name;
char *kk_klass;
int kk_instance;
kstat_Kstype_t kk_type;
unsigned long long kk_crtime;
};
void kstat_Kstatinfo_free(kstat_Kstatinfo_t *in);
Fields:
kk_module -- module name
kk_name -- kstat name
kk_klass -- kstat class
kk_instance -- module's instance
kk_type -- kstat data type
kk_crtime -- kstat creation time
VERSION
1.0
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+--------------------+----------------------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+----------------------------------------+
|Availability | system/management/rad/module/rad-kstat |
+--------------------+----------------------------------------+
|Interface Stability | Private |
+--------------------+----------------------------------------+
SEE ALSO
rad(8)
NOTES
1. Accessing Python documentation for this module:
$ pydoc rad.bindings.com.oracle.solaris.rad.kstat_1
Solaris 11.4 2017-02-01 KSTAT-1(3rad)