.\"
.\" 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_LOOKUP 3KSTAT
.Os
.Sh NAME
.Nm kstat_lookup ,
.Nm kstat_data_lookup
.Nd find a kstat by name
.Sh LIBRARY
.Lb libkstat
.Sh SYNOPSIS
.In kstat.h
.Ft "kstat_t *"
.Fo kstat_lookup
.Fa "kstat_ctl_t *kc"
.Fa "const char *ks_module"
.Fa "int ks_instance"
.Fa "const char *ks_name"
.Fc
.Ft "void *"
.Fo kstat_data_lookup
.Fa "kstat_t *ksp"
.Fa "const char *name"
.Fc
.Sh DESCRIPTION
The
.Fn kstat_lookup
function traverses the kstat chain,
.Ql kc->kc_chain ,
searching for a kstat with the same
.Fa ks_module ,
.Fa ks_instance ,
and
.Fa ks_name
fields; this triplet uniquely identifies a kstat.
If
.Fa ks_module ,
is
.Dv NULL ,
.Fa ks_instance
is -1, or
.Fa ks_name
is
.Dv NULL ,
those fields will be ignored in the search.
For
example,
.Fo kstat_lookup
.Fa kc ,
.Fa NULL ,
.Fa -1 ,
.Fa "foo"
.Fc
will find the first kstat with name
.Dq foo .
.Pp
The
.Fn kstat_data_lookup
function searches the kstat's data section for the record with the specified
.Fa name .
This operation is valid only for those kstat types that have named data records:
.Dv KSTAT_TYPE_NAMED
and
.Dv KSTAT_TYPE_TIMER .
.Ss Lifetime
The
.Vt kstat_t
structures and any associated data are owned by the library and the
corresponding handle,
.Fa kc .
That is, two callers with same library handle will generally have the same
memory returned to them, though this is not a guaranteed part of the interface.
Callers should not modify or attempt to free the data associated with either.
Calling the
.Xr kstat_chain_update 3KSTAT
or
.Xr kstat_close 3KSTAT
functions on the handle
.Fa kc
will cause the
pointers returned from these functions with the same handle to be invalid.
.Sh RETURN VALUES
The
.Fn kstat_lookup
function returns a pointer to the requested kstat if it is found.
Otherwise it returns
.Dv NULL
and sets
.Va errno
to indicate the error.
.Pp
The
.Fn kstat_data_lookup
function returns a pointer to the requested data record if it is found.
Otherwise it returns
.Dv NULL
and sets
.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_lookup
and
.Fn kstat_data_lookup
functions will fail if:
.Bl -tag -width Er
.It Er EINVAL
An attempt was made to look up data for a kstat that was not of type
.Dv KSTAT_TYPE_NAMED
or
.Dv KSTAT_TYPE_TIMER .
.It Er ENOENT
The requested kstat could not be found.
.El
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy Unsafe
.Sh SEE ALSO
.Xr kstat 3KSTAT ,
.Xr kstat_chain_update 3KSTAT ,
.Xr kstat_open 3KSTAT ,
.Xr kstat_read 3KSTAT ,
.Xr attributes 7