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_CHAIN_UPDATE 3KSTAT 22.Os 23.Sh NAME 24.Nm kstat_chain_update 25.Nd update the kstat header chain 26.Sh Library 27.Lb libkstat 28.Sh SYNOPSIS 29.In kstat.h 30.Ft kid_t 31.Fo kstat_chain_update 32.Fa "kstat_ctl_t *kc" 33.Fc 34.Sh DESCRIPTION 35The 36.Fn kstat_chain_update 37function brings the user's kstat header chain in sync with that of the kernel. 38The kstat chain is a linked list of kstat headers 39.Po 40.Vt kstat_t Ns 's 41.Pc 42pointed to by 43.Ql kc->kc_chain , 44which is initialized 45by 46.Xr kstat_open 3KSTAT . 47This chain constitutes a list of all kstats currently in the system. 48.Pp 49During normal operation, the kernel creates new kstats and deletes old ones as 50various device instances are added and removed, thereby causing the user's copy 51of the kstat chain to become out of date. 52The 53.Fn kstat_chain_update 54function detects this condition by comparing the kernel's current kstat chain 55ID 56.Pq KCID , 57which is incremented every time the kstat chain changes, to the user's KCID, 58.Ql kc->kc_chain_id . 59If the KCIDs match, 60.Fn kstat_chain_update 61does nothing. 62Otherwise, it deletes any invalid kstat headers from the user's kstat chain, 63adds any new ones, and sets 64.Ql kc->kc_chain_id 65to the new KCID. 66All other kstat headers in the user's kstat chain are unmodified. 67.Pp 68Because of the deletion process, any 69.Vt kstat_t 70structures retrieved by the 71.Xr kstat_lookup 3KSTAT 72function or data pointers obtained through the 73.Xr kstat_data_lookup 3KSTAT 74function are invalidated by a call to 75.Fn kstat_chain_update . 76New lookup calls must be made to obtain fresh structures after each chain 77update. 78.Sh RETURN VALUES 79Upon successful completion, 80.Fn kstat_chain_update 81returns the new KCID if the kstat chain has changed and 0 if it has not changed. 82Otherwise, it returns 83.Sy -1 84and sets 85.Va errno 86to indicate the error. 87.Sh FILES 88.Bl -tag -width Pa 89.It Pa /dev/kstat 90kernel statistics driver character device 91.El 92.Sh ERRORS 93The 94.Fn kstat_chain_update 95function will fail if: 96.Bl -tag -width Er 97.It Er EAGAIN 98The kstat was temporarily unavailable for reading or writing. 99.It Er ENOMEM 100Insufficient storage space is available. 101.It Er ENXIO 102The given kstat could not be located for reading. 103.It Er EOVERFLOW 104The data for the given kstat was too large to be stored in the structure. 105.El 106.Sh INTERFACE STABILITY 107.Sy Committed 108.Sh MT-LEVEL 109.Sy Unsafe 110.Sh SEE ALSO 111.Xr kstat 3KSTAT , 112.Xr kstat_lookup 3KSTAT , 113.Xr kstat_open 3KSTAT , 114.Xr kstat_read 3KSTAT , 115.Xr attributes 7 116