1.\" $OpenBSD: kstat_create.9,v 1.1 2020/07/06 11:48:03 dlg Exp $ 2.\" 3.\" Copyright (c) 2020 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: July 6 2020 $ 18.Dt KSTAT_CREATE 9 19.Os 20.Sh NAME 21.Nm kstat_create , 22.\" .Nm kstat_set_wlock , 23.\" .Nm kstat_set_rlock , 24.\" .Nm kstat_set_mutex , 25.Nm kstat_install , 26.Nm kstat_destroy 27.Nd kernel statistics provider API 28.Sh SYNOPSIS 29.In sys/kstat.h 30.Ft struct kstat * 31.Fo kstatap_create 32.Fa "const char *provider" 33.Fa "unsigned int instance" 34.Fa "const char *name" 35.Fa "unsigned int unit" 36.Fa "unsigned int type" 37.Fa "unsigned int flags" 38.Fc 39.\" .Ft void 40.\" .Fn kstat_set_wlock "struct kstat *ks" "struct rwlock *rwl" 41.\" .Ft void 42.\" .Fn kstat_set_rlock "struct kstat *ks" "struct rwlock *rwl" 43.\" .Ft void 44.\" .Fn kstat_set_mutex "struct kstat *ks" "struct mutex *mtx" 45.Ft void 46.Fn kstat_install "struct kstat *ks" 47.Ft void 48.Fn kstat_destroy "struct kstat *ks" 49.Sh DESCRIPTION 50Kernel subsystems can export statistics to userland using the kernel 51statistics (kstat) API. 52.Pp 53The 54.Fn kstat_create 55function allocates a kstat structure and adds it to the list of statistics that userland can query. 56A kstat is uniquely identified by a tuple made up of the 57.Fa provider , 58.Fa instances , 59.Fa name , 60and 61.Fa unit 62arguments. 63The type of information provided by the kstat is identified by the 64.Fa type 65argument. 66The supported kstat types are 67.Bl -tag -width xxx -offset indent 68.It Dv KSTAT_T_RAW 69The kstat provides raw bytes. 70.It Dv KSTAT_T_KV 71The kstat provides a series of 72.Vt struct kstat_kv 73structures that represent key/value information. 74See 75.Xr kstat_kv_init 9 76for more detail. 77.El 78.Pp 79Once a kstat structure has been created, the caller is responsible for initialising the structure. 80.Pp 81After the structure has been initialised, 82.Fn kstat_install 83notifies the kstat subsystem that the kstat structure 84.Fa ks 85can be used to export information to userland. 86.Pp 87.Fn kstat_destroy 88removes the 89.Fa ks 90 kstat structure from the list of exported statistics and frees it. 91.\" might want a kstat_remove... 92.Sh CONTEXT 93.Fn kstat_create , 94.Fn kstat_install , 95.\" .Fn kstat_set_wlock , 96.\" .Fn kstat_set_rlock , 97.\" .Fn kstat_set_mutex , 98and 99.Fn kstat_destroy 100can be called during autoconf, or from process context. 101.Sh RETURN VALUES 102.Fn kstat_create 103returns a pointer to an kstat structure on success, of 104.Dv NULL 105on failure. 106.Sh SEE ALSO 107.Xr kstat_kv_init 9 108