.\"
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2021 Oxide Computer Company
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.Dd November 29, 2021
.Dt KSTAT_READ 3KSTAT
.Os
.Sh NAME
.Nm kstat_read ,
.Nm kstat_write
.Nd read or write kstat data
.Sh LIBRARY
.Lb libkstat
.Sh SYNOPSIS
.In kstat.h
.Ft kid_t
.Fo kstat_read
.Fa "kstat_ctl_t *kc"
.Fa "kstat_t *ksp"
.Fa "void *buf"
.Fc
.Ft kid_t
.Fo kstat_write
.Fa "kstat_ctl_t *kc"
.Fa "kstat_t *ksp"
.Fa "void *buf"
.Fc
.Sh DESCRIPTION
The
.Fn kstat_read
function gets data from the kernel for the kstat pointed to by
.Fa ksp .
The
.Ql ksp->ks_data
field is automatically allocated
.Pq or reallocated
to be large enough to hold all of the data.
The
.Ql ksp->ks_ndata
field is set to the number of data fields,
.Ql ksp->ks_data_size
is set to the total size of the data, and
.Ql ksp->ks_snaptime
is set to the high-resolution time at which the data snapshot was taken.
If
.Fa buf
is non-null, the data is copied from
.Ql ksp->ks_data
to
.Fa buf .
.Pp
The
.Fn kstat_write
function writes data from
.Fa buf ,
or from
.Ql ksp->ks_data
if
.Fa buf
is
.Dv NULL
to the corresponding kstat in the kernel.
Only a privileged user can use
.Fn kstat_write .
.Sh RETURN VALUES
Upon successful completion,
.Fn kstat_read
and
.Fn kstat_write
return the current kstat chain ID (KCID).
Otherwise, they return
.Sy -1
and set
.Va errno
to indicate the error.
.Sh FILES
.Bl -tag -width Pa
.It Pa /dev/kstat
kernel statistics driver character device
.El
.Sh ERRORS
The
.Fn kstat_read
and
.Fn kstat_write
functions will fail if:
.Bl -tag -width Er
.It Er EACCES
An attempt was made to write to a non-writable kstat.
.It Er EAGAIN
The kstat was temporarily unavailable for reading or writing.
.It Er EINVAL
An attempt was made to write data to a kstat, but the number of elements or the
data size does not match.
.It Er ENOMEM
Insufficient storage space is available.
.It Er ENXIO
The given kstat could not be located for reading or writing.
.It Er EOVERFLOW
.It Er EPERM
An attempt was made to write to a kstat, but
.Brq Dv PRIV_SYS_CONFIG
was not asserted in the effective privilege set.
.El
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy Unsafe
.Sh SEE ALSO
.Xr kstat 3KSTAT ,
.Xr kstat_chain_update 3KSTAT ,
.Xr kstat_lookup 3KSTAT ,
.Xr kstat_open 3KSTAT ,
.Xr attributes 7 ,
.Xr privileges 7