1.\" $OpenBSD: kstat_create.9,v 1.2 2020/08/10 11:33:58 schwarze 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: August 10 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 kstat_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 56.Vt kstat 57structure and adds it to the list of statistics that userland can query. 58A kstat is uniquely identified by a tuple made up of the 59.Fa provider , 60.Fa instances , 61.Fa name , 62and 63.Fa unit 64arguments. 65The type of information provided by the kstat is identified by the 66.Fa type 67argument. 68The supported kstat types are 69.Bl -tag -width xxx -offset indent 70.It Dv KSTAT_T_RAW 71The kstat provides raw bytes. 72.It Dv KSTAT_T_KV 73The kstat provides a series of 74.Vt struct kstat_kv 75structures that represent key/value information. 76See 77.Xr kstat_kv_init 9 78for more detail. 79.El 80.Pp 81Once a 82.Vt kstat 83structure has been created, 84the caller is responsible for initialising the structure. 85.Pp 86After the structure has been initialised, 87.Fn kstat_install 88notifies the kstat subsystem that 89.Fa ks 90can be used to export information to userland. 91.Pp 92.Fn kstat_destroy 93removes 94.Fa ks 95from the list of exported statistics and frees it. 96.\" might want a kstat_remove... 97.Sh CONTEXT 98.Fn kstat_create , 99.Fn kstat_install , 100.\" .Fn kstat_set_wlock , 101.\" .Fn kstat_set_rlock , 102.\" .Fn kstat_set_mutex , 103and 104.Fn kstat_destroy 105can be called during autoconf, or from process context. 106.Sh RETURN VALUES 107.Fn kstat_create 108returns a pointer to a 109.Vt kstat 110structure on success, or 111.Dv NULL 112on failure. 113.Sh SEE ALSO 114.Xr kstat_kv_init 9 115.Sh HISTORY 116These functions first appeared in 117.Ox 6.8 . 118.Sh AUTHORS 119.An David Gwynne Aq Mt dlg@openbsd.org 120