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