KSTAT(4) | Device Drivers Manual | KSTAT(4)

# NAME

`kstat` — kernel statistics

# SYNOPSIS

`pseudo-device kstat`

# DESCRIPTION

The /dev/kstat device exposes kernel statistics (kstats) to userland.

# IOCTLS

The kstat ioctl(2) calls are provided in `<sys/kstat.h>`.

With the exception of `KSTATIOC_VERSION`, the kstat ioctl(2) calls use the kstat_req structure to request or enumerate kernel statistic data from the kernel:

    struct kstat_req {
    	unsigned int		 ks_rflags;
    #define KSTATIOC_F_IGNVER		(1 << 0)
    	/* the current version of the kstat subsystem */
    	unsigned int		 ks_version;

    	uint64_t		 ks_id;

    	char			 ks_provider[KSTAT_STRLEN];
    	unsigned int		 ks_instance;
    	char			 ks_name[KSTAT_STRLEN];
    	unsigned int		 ks_unit;

    	struct timespec		 ks_created;
    	struct timespec		 ks_updated;
    	struct timespec		 ks_interval;
    	unsigned int		 ks_type;
    	unsigned int		 ks_state;

    	void			*ks_data;
    	size_t			 ks_datalen;
    	unsigned int		 ks_dataver;
    };

The kstat subsystem increments a version number when a kstat is added to or removed from the subsystem so changes to the set of kstats can be detected. The current version can be requested with a `KSTATIOC_VERSION` ioctl(2) call. Programs requesting a kstat with the other ioctl(2) calls pass the current version in ks_version, and if the version differs an error will be returned with errno(2) set to `EINVAL` to indicate that the program should resynchronise with the kernel subsystem. This check can be disabled by setting the `KSTATIOC_F_IGNVER` flag in ks_rflags.

A kstat is identified by a 64bit number, or the combination of a provider name, instance number, name, and unit number.

Unless ks_data is `NULL`, the kstat subsystem will request an update of the statistics data and copy up to ks_datalen bytes of it to the specified memory.

The kstat ioctl(2) calls are as follows:

`KSTATIOC_VERSION` unsigned int
  Get the current version of the set of kernel statistics.
`KSTATIOC_FIND_ID` struct kstat_req
  Request the kstat identified by ks_id.
`KSTATIOC_NFIND_ID` struct kstat_req
  Request a kstat with an identifier greater than or equal to ks_id.
`KSTATIOC_FIND_PROVIDER` struct kstat_req
  Request the kstat identified by ks_provider, ks_instance, ks_name, and ks_unit.
`KSTATIOC_NFIND_PROVIDER` struct kstat_req
  Request the kstat or next kstat from the set of kstats ordered by ks_provider, ks_instance, ks_name, and ks_unit.
`KSTATIOC_FIND_NAME` struct kstat_req
  Request the kstat identified by ks_name, ks_unit, ks_provider, and ks_instance.
`KSTATIOC_NFIND_NAME` struct kstat_req
  Request the kstat or next kstat from the set of kstats ordered by ks_name, ks_unit, ks_provider, and ks_instance.

Upon the successful request of a kstat, the `kstat` driver will update the kstat_req structure with current information about that kstat. Updated fields include:

ks_version
  The current version of the kstat subsystem.
ks_id
  The 64bit unique identifier for the requested kstat. A kstat can be requested using this identifier and the `KSTATIOC_FIND_ID` ioctl(2) call.
ks_provider, ks_instance, ks_name, ks_unit
  The fully specified identifier of the kstat. A kstat can be requested using these identifiers with the `KSTATIOC_FIND_NAME` and `KSTATIOC_FIND_PROVIDER` ioctl(2) calls. Groups of kstats with the same identifier or name can be enumerated or requested with the `KSTATIOC_NFIND_NAME` and `KSTATIOC_NFIND_PROVIDER` ioctl(2) calls without having to fetch the entire set of kstats and filtering them.
ks_created
  The system uptime when the kstat was created and added to the kstat subsystem.
ks_updated
  The system uptime at which the kstat data payload was last updated. A kstat provider may update data when requested, or report when data was last updated by some other process. ks_updated can by used by a program to identify if data has been updated, or for calculating rates of changes of values between updates.
ks_type
  The type or structure of the data payload. Currently supported types are documented in kstat_create(9).
ks_datalen
  The amount of data the kstat provides in bytes. When requesting kstat data, the program specifies the amount of space available at ks_data by setting this variable.

# FILES

/dev/kstat

# SEE ALSO

kstat_create(9), kstat_kv_init(9)

# HISTORY

The `kstat` device appeared in OpenBSD 6.8.

January 14, 2022 | Debian