xref: /illumos-gate/usr/src/man/man3kstat/kstat_read.3kstat (revision 15f90b02bdacbf0ae47fa105944f15b6596f9748)
1.\"
2.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3.\" Copyright 2021 Oxide Computer Company
4.\"
5.\" The contents of this file are subject to the terms of the
6.\" Common Development and Distribution License (the "License").
7.\" You may not use this file except in compliance with the License.
8.\"
9.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10.\" or http://www.opensolaris.org/os/licensing.
11.\" See the License for the specific language governing permissions
12.\" and limitations under the License.
13.\"
14.\" When distributing Covered Code, include this CDDL HEADER in each
15.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16.\" If applicable, add the following below this CDDL HEADER, with the
17.\" fields enclosed by brackets "[]" replaced with your own identifying
18.\" information: Portions Copyright [yyyy] [name of copyright owner]
19.\"
20.Dd November 29, 2021
21.Dt KSTAT_READ 3KSTAT
22.Os
23.Sh NAME
24.Nm kstat_read ,
25.Nm kstat_write
26.Nd read or write kstat data
27.Sh LIBRARY
28.Lb libkstat
29.Sh SYNOPSIS
30.In kstat.h
31.Ft kid_t
32.Fo kstat_read
33.Fa "kstat_ctl_t *kc"
34.Fa "kstat_t *ksp"
35.Fa "void *buf"
36.Fc
37.Ft kid_t
38.Fo kstat_write
39.Fa "kstat_ctl_t *kc"
40.Fa "kstat_t *ksp"
41.Fa "void *buf"
42.Fc
43.Sh DESCRIPTION
44The
45.Fn kstat_read
46function gets data from the kernel for the kstat pointed to by
47.Fa ksp .
48The
49.Ql ksp->ks_data
50field is automatically allocated
51.Pq or reallocated
52to be large enough to hold all of the data.
53The
54.Ql ksp->ks_ndata
55field is set to the number of data fields,
56.Ql ksp->ks_data_size
57is set to the total size of the data, and
58.Ql ksp->ks_snaptime
59is set to the high-resolution time at which the data snapshot was taken.
60If
61.Fa buf
62is non-null, the data is copied from
63.Ql ksp->ks_data
64to
65.Fa buf .
66.Pp
67The
68.Fn kstat_write
69function writes data from
70.Fa buf ,
71or from
72.Ql ksp->ks_data
73if
74.Fa buf
75is
76.Dv NULL
77to the corresponding kstat in the kernel.
78Only a privileged user can use
79.Fn kstat_write .
80.Sh RETURN VALUES
81Upon successful completion,
82.Fn kstat_read
83and
84.Fn kstat_write
85return the current kstat chain ID (KCID).
86Otherwise, they return
87.Sy -1
88and set
89.Va errno
90to indicate the error.
91.Sh FILES
92.Bl -tag -width Pa
93.It Pa /dev/kstat
94kernel statistics driver character device
95.El
96.Sh ERRORS
97The
98.Fn kstat_read
99and
100.Fn kstat_write
101functions will fail if:
102.Bl -tag -width Er
103.It Er EACCES
104An attempt was made to write to a non-writable kstat.
105.It Er EAGAIN
106The kstat was temporarily unavailable for reading or writing.
107.It Er EINVAL
108An attempt was made to write data to a kstat, but the number of elements or the
109data size does not match.
110.It Er ENOMEM
111Insufficient storage space is available.
112.It Er ENXIO
113The given kstat could not be located for reading or writing.
114.It Er EOVERFLOW
115.It Er EPERM
116An attempt was made to write to a kstat, but
117.Brq Dv PRIV_SYS_CONFIG
118was not asserted in the effective privilege set.
119.El
120.Sh INTERFACE STABILITY
121.Sy Committed
122.Sh MT-LEVEL
123.Sy Unsafe
124.Sh SEE ALSO
125.Xr kstat 3KSTAT ,
126.Xr kstat_chain_update 3KSTAT ,
127.Xr kstat_lookup 3KSTAT ,
128.Xr kstat_open 3KSTAT ,
129.Xr attributes 7 ,
130.Xr privileges 7
131