docs: OpenBSD Man Pages Added

1 files changed, 210 insertions, 0 deletions

diff --git a/static/openbsd/man4/kstat.4 b/static/openbsd/man4/kstat.4
new file mode 100644
index 00000000..f7bea1ee
--- /dev/null
+++ b/static/openbsd/man4/kstat.4
@@ -0,0 +1,210 @@
+.\"	$OpenBSD: kstat.4,v 1.8 2022/01/14 04:25:57 dlg Exp $
+.\"
+.\" Copyright (c) 2022 Jonathan Gray <jsg@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: January 14 2022 $
+.Dt KSTAT 4
+.Os
+.Sh NAME
+.Nm kstat
+.Nd kernel statistics
+.Sh SYNOPSIS
+.Cd "pseudo-device kstat"
+.Sh DESCRIPTION
+The
+.Pa /dev/kstat
+device exposes kernel statistics (kstats) to userland.
+.Sh IOCTLS
+The kstat
+.Xr ioctl 2
+calls are provided in
+.In sys/kstat.h .
+.Pp
+With the exception of
+.Dv KSTATIOC_VERSION ,
+the kstat
+.Xr ioctl 2
+calls use the
+.Vt kstat_req
+structure to request or enumerate kernel
+statistic data from the kernel:
+.Bd -literal
+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;
+};
+.Ed
+.Pp
+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
+.Dv KSTATIOC_VERSION
+.Xr ioctl 2
+call.
+Programs requesting a kstat with the other
+.Xr ioctl 2
+calls pass the current version in
+.Va ks_version ,
+and if the version differs an error will be returned with
+.Xr errno 2
+set to
+.Dv EINVAL
+to indicate that the program should resynchronise with the kernel
+subsystem.
+This check can be disabled by setting the
+.Dv KSTATIOC_F_IGNVER
+flag in
+.Va ks_rflags .
+.Pp
+A kstat is identified by a 64bit number, or the combination of a
+provider name, instance number, name, and unit number.
+.Pp
+Unless
+.Va ks_data
+is
+.Dv NULL ,
+the kstat subsystem will request an update of the statistics data
+and copy up to
+.Va ks_datalen
+bytes of it to the specified memory.
+.Pp
+The kstat
+.Xr ioctl 2
+calls are as follows:
+.Bl -tag -width Ds
+.It Dv KSTATIOC_VERSION Fa "unsigned int"
+Get the current version of the set of kernel statistics.
+.It Dv KSTATIOC_FIND_ID Fa "struct kstat_req"
+Request the kstat identified by
+.Va ks_id .
+.It Dv KSTATIOC_NFIND_ID Fa "struct kstat_req"
+Request a kstat with an identifier greater than or equal to
+.Va ks_id .
+.It Dv KSTATIOC_FIND_PROVIDER Fa "struct kstat_req"
+Request the kstat identified by
+.Va ks_provider ,
+.Va ks_instance ,
+.Va ks_name ,
+and
+.Va ks_unit .
+.It Dv KSTATIOC_NFIND_PROVIDER Fa "struct kstat_req"
+Request the kstat or next kstat from the set of kstats ordered by
+.Va ks_provider ,
+.Va ks_instance ,
+.Va ks_name ,
+and
+.Va ks_unit .
+.It Dv KSTATIOC_FIND_NAME Fa "struct kstat_req"
+Request the kstat identified by
+.Va ks_name ,
+.Va ks_unit ,
+.Va ks_provider ,
+and
+.Va ks_instance .
+.It Dv KSTATIOC_NFIND_NAME Fa "struct kstat_req"
+Request the kstat or next kstat from the set of kstats ordered by
+.Va ks_name ,
+.Va ks_unit ,
+.Va ks_provider ,
+and
+.Va ks_instance .
+.El
+.Pp
+Upon the successful request of a kstat, the
+.Nm
+driver will update the
+.Vt kstat_req
+structure with current information about that kstat.
+Updated fields include:
+.Bl -tag -width Ds
+.It Va ks_version
+The current version of the kstat subsystem.
+.It Va ks_id
+The 64bit unique identifier for the requested kstat.
+A kstat can be requested using this identifier and the
+.Dv KSTATIOC_FIND_ID
+.Xr ioctl 2
+call.
+.It Va ks_provider , Va ks_instance , Va ks_name , Va ks_unit
+The fully specified identifier of the kstat.
+A kstat can be requested using these identifiers with the
+.Dv KSTATIOC_FIND_NAME
+and
+.Dv KSTATIOC_FIND_PROVIDER
+.Xr ioctl 2
+calls.
+Groups of kstats with the same identifier or name can be enumerated
+or requested with the
+.Dv KSTATIOC_NFIND_NAME
+and
+.Dv KSTATIOC_NFIND_PROVIDER
+.Xr ioctl 2
+calls without having to fetch the entire set of kstats and filtering
+them.
+.It Va ks_created
+The system uptime when the kstat was created and added to the kstat
+subsystem.
+.It Va 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.
+.Va 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.
+.It Va ks_type
+The type or structure of the data payload.
+Currently supported types are documented in
+.Xr kstat_create 9 .
+.\" .It Va ks_state
+.\" The state of the kstat. create or installed iirc
+.It Va ks_datalen
+The amount of data the kstat provides in bytes.
+When requesting kstat data, the program specifies the amount of
+space available at
+.Va ks_data
+by setting this variable.
+.El
+.Sh FILES
+.Bl -tag -width Pa -compact
+.It Pa /dev/kstat
+.El
+.Sh SEE ALSO
+.\".Xr kstat 1 ,
+.Xr kstat_create 9 ,
+.Xr kstat_kv_init 9
+.Sh HISTORY
+The
+.Nm
+device appeared in
+.Ox 6.8 .