1.\" $OpenBSD: kstat.4,v 1.8 2022/01/14 04:25:57 dlg Exp $ 2.\" 3.\" Copyright (c) 2022 Jonathan Gray <jsg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: January 14 2022 $ 18.Dt KSTAT 4 19.Os 20.Sh NAME 21.Nm kstat 22.Nd kernel statistics 23.Sh SYNOPSIS 24.Cd "pseudo-device kstat" 25.Sh DESCRIPTION 26The 27.Pa /dev/kstat 28device exposes kernel statistics (kstats) to userland. 29.Sh IOCTLS 30The kstat 31.Xr ioctl 2 32calls are provided in 33.In sys/kstat.h . 34.Pp 35With the exception of 36.Dv KSTATIOC_VERSION , 37the kstat 38.Xr ioctl 2 39calls use the 40.Vt kstat_req 41structure to request or enumerate kernel 42statistic data from the kernel: 43.Bd -literal 44struct kstat_req { 45 unsigned int ks_rflags; 46#define KSTATIOC_F_IGNVER (1 << 0) 47 /* the current version of the kstat subsystem */ 48 unsigned int ks_version; 49 50 uint64_t ks_id; 51 52 char ks_provider[KSTAT_STRLEN]; 53 unsigned int ks_instance; 54 char ks_name[KSTAT_STRLEN]; 55 unsigned int ks_unit; 56 57 struct timespec ks_created; 58 struct timespec ks_updated; 59 struct timespec ks_interval; 60 unsigned int ks_type; 61 unsigned int ks_state; 62 63 void *ks_data; 64 size_t ks_datalen; 65 unsigned int ks_dataver; 66}; 67.Ed 68.Pp 69The kstat subsystem increments a version number when a kstat is added to or 70removed from the subsystem so changes to the set of kstats can be detected. 71The current version can be requested with a 72.Dv KSTATIOC_VERSION 73.Xr ioctl 2 74call. 75Programs requesting a kstat with the other 76.Xr ioctl 2 77calls pass the current version in 78.Va ks_version , 79and if the version differs an error will be returned with 80.Xr errno 2 81set to 82.Dv EINVAL 83to indicate that the program should resynchronise with the kernel 84subsystem. 85This check can be disabled by setting the 86.Dv KSTATIOC_F_IGNVER 87flag in 88.Va ks_rflags . 89.Pp 90A kstat is identified by a 64bit number, or the combination of a 91provider name, instance number, name, and unit number. 92.Pp 93Unless 94.Va ks_data 95is 96.Dv NULL , 97the kstat subsystem will request an update of the statistics data 98and copy up to 99.Va ks_datalen 100bytes of it to the specified memory. 101.Pp 102The kstat 103.Xr ioctl 2 104calls are as follows: 105.Bl -tag -width Ds 106.It Dv KSTATIOC_VERSION Fa "unsigned int" 107Get the current version of the set of kernel statistics. 108.It Dv KSTATIOC_FIND_ID Fa "struct kstat_req" 109Request the kstat identified by 110.Va ks_id . 111.It Dv KSTATIOC_NFIND_ID Fa "struct kstat_req" 112Request a kstat with an identifier greater than or equal to 113.Va ks_id . 114.It Dv KSTATIOC_FIND_PROVIDER Fa "struct kstat_req" 115Request the kstat identified by 116.Va ks_provider , 117.Va ks_instance , 118.Va ks_name , 119and 120.Va ks_unit . 121.It Dv KSTATIOC_NFIND_PROVIDER Fa "struct kstat_req" 122Request the kstat or next kstat from the set of kstats ordered by 123.Va ks_provider , 124.Va ks_instance , 125.Va ks_name , 126and 127.Va ks_unit . 128.It Dv KSTATIOC_FIND_NAME Fa "struct kstat_req" 129Request the kstat identified by 130.Va ks_name , 131.Va ks_unit , 132.Va ks_provider , 133and 134.Va ks_instance . 135.It Dv KSTATIOC_NFIND_NAME Fa "struct kstat_req" 136Request the kstat or next kstat from the set of kstats ordered by 137.Va ks_name , 138.Va ks_unit , 139.Va ks_provider , 140and 141.Va ks_instance . 142.El 143.Pp 144Upon the successful request of a kstat, the 145.Nm 146driver will update the 147.Vt kstat_req 148structure with current information about that kstat. 149Updated fields include: 150.Bl -tag -width Ds 151.It Va ks_version 152The current version of the kstat subsystem. 153.It Va ks_id 154The 64bit unique identifier for the requested kstat. 155A kstat can be requested using this identifier and the 156.Dv KSTATIOC_FIND_ID 157.Xr ioctl 2 158call. 159.It Va ks_provider , Va ks_instance , Va ks_name , Va ks_unit 160The fully specified identifier of the kstat. 161A kstat can be requested using these identifiers with the 162.Dv KSTATIOC_FIND_NAME 163and 164.Dv KSTATIOC_FIND_PROVIDER 165.Xr ioctl 2 166calls. 167Groups of kstats with the same identifier or name can be enumerated 168or requested with the 169.Dv KSTATIOC_NFIND_NAME 170and 171.Dv KSTATIOC_NFIND_PROVIDER 172.Xr ioctl 2 173calls without having to fetch the entire set of kstats and filtering 174them. 175.It Va ks_created 176The system uptime when the kstat was created and added to the kstat 177subsystem. 178.It Va ks_updated 179The system uptime at which the kstat data payload was last updated. 180A kstat provider may update data when requested, or report when 181data was last updated by some other process. 182.Va ks_updated 183can by used by a program to identify if data has been updated, or 184for calculating rates of changes of values between updates. 185.It Va ks_type 186The type or structure of the data payload. 187Currently supported types are documented in 188.Xr kstat_create 9 . 189.\" .It Va ks_state 190.\" The state of the kstat. create or installed iirc 191.It Va ks_datalen 192The amount of data the kstat provides in bytes. 193When requesting kstat data, the program specifies the amount of 194space available at 195.Va ks_data 196by setting this variable. 197.El 198.Sh FILES 199.Bl -tag -width Pa -compact 200.It Pa /dev/kstat 201.El 202.Sh SEE ALSO 203.\".Xr kstat 1 , 204.Xr kstat_create 9 , 205.Xr kstat_kv_init 9 206.Sh HISTORY 207The 208.Nm 209device appeared in 210.Ox 6.8 . 211