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_LOOKUP 3KSTAT 22.Os 23.Sh NAME 24.Nm kstat_lookup , 25.Nm kstat_data_lookup 26.Nd find a kstat by name 27.Sh LIBRARY 28.Lb libkstat 29.Sh SYNOPSIS 30.In kstat.h 31.Ft "kstat_t *" 32.Fo kstat_lookup 33.Fa "kstat_ctl_t *kc" 34.Fa "const char *ks_module" 35.Fa "int ks_instance" 36.Fa "const char *ks_name" 37.Fc 38.Ft "void *" 39.Fo kstat_data_lookup 40.Fa "kstat_t *ksp" 41.Fa "const char *name" 42.Fc 43.Sh DESCRIPTION 44The 45.Fn kstat_lookup 46function traverses the kstat chain, 47.Ql kc->kc_chain , 48searching for a kstat with the same 49.Fa ks_module , 50.Fa ks_instance , 51and 52.Fa ks_name 53fields; this triplet uniquely identifies a kstat. 54If 55.Fa ks_module , 56is 57.Dv NULL , 58.Fa ks_instance 59is -1, or 60.Fa ks_name 61is 62.Dv NULL , 63those fields will be ignored in the search. 64For 65example, 66.Fo kstat_lookup 67.Fa kc , 68.Fa NULL , 69.Fa -1 , 70.Fa "foo" 71.Fc 72will find the first kstat with name 73.Dq foo . 74.Pp 75The 76.Fn kstat_data_lookup 77function searches the kstat's data section for the record with the specified 78.Fa name . 79This operation is valid only for those kstat types that have named data records: 80.Dv KSTAT_TYPE_NAMED 81and 82.Dv KSTAT_TYPE_TIMER . 83.Ss Lifetime 84The 85.Vt kstat_t 86structures and any associated data are owned by the library and the 87corresponding handle, 88.Fa kc . 89That is, two callers with same library handle will generally have the same 90memory returned to them, though this is not a guaranteed part of the interface. 91Callers should not modify or attempt to free the data associated with either. 92Calling the 93.Xr kstat_chain_update 3KSTAT 94or 95.Xr kstat_close 3KSTAT 96functions on the handle 97.Fa kc 98will cause the 99pointers returned from these functions with the same handle to be invalid. 100.Sh RETURN VALUES 101The 102.Fn kstat_lookup 103function returns a pointer to the requested kstat if it is found. 104Otherwise it returns 105.Dv NULL 106and sets 107.Va errno 108to indicate the error. 109.Pp 110The 111.Fn kstat_data_lookup 112function returns a pointer to the requested data record if it is found. 113Otherwise it returns 114.Dv NULL 115and sets 116.Va errno 117to indicate the error. 118.Sh FILES 119.Bl -tag -width Pa 120.It Pa /dev/kstat 121kernel statistics driver character device 122.El 123.Sh ERRORS 124The 125.Fn kstat_lookup 126and 127.Fn kstat_data_lookup 128functions will fail if: 129.Bl -tag -width Er 130.It Er EINVAL 131An attempt was made to look up data for a kstat that was not of type 132.Dv KSTAT_TYPE_NAMED 133or 134.Dv KSTAT_TYPE_TIMER . 135.It Er ENOENT 136The requested kstat could not be found. 137.El 138.Sh INTERFACE STABILITY 139.Sy Committed 140.Sh MT-LEVEL 141.Sy Unsafe 142.Sh SEE ALSO 143.Xr kstat 3KSTAT , 144.Xr kstat_chain_update 3KSTAT , 145.Xr kstat_open 3KSTAT , 146.Xr kstat_read 3KSTAT , 147.Xr attributes 7 148