lib/libkinfo/kinfo.3

.\"
.\" Copyright (c) 2015
.\"	The DragonFly Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd February 5, 2021
.Dt KINFO 3
.Os
.Sh NAME
.Nm cputime_pcpu_statistics ,
.Nm kinfo_get_cpus ,
.Nm kinfo_get_files ,
.Nm kinfo_get_maxfiles ,
.Nm kinfo_get_net_rtstatistics ,
.Nm kinfo_get_openfiles ,
.Nm kinfo_get_sched_cputime ,
.Nm kinfo_get_sched_hz ,
.Nm kinfo_get_sched_profhz ,
.Nm kinfo_get_sched_stathz ,
.Nm kinfo_get_tty_tk_nin ,
.Nm kinfo_get_tty_tk_nout ,
.Nm kinfo_get_vfs_bufspace ,
.Nm route_pcpu_statistics
.Nd information about the running kernel
.Sh LIBRARY
.Lb libkinfo
.Sh SYNOPSIS
.In kinfo.h
.Ft int
.Fn kinfo_get_files "struct kinfo_file **file_buf" "size_t *len"
.Ft int
.Fn kinfo_get_maxfiles "int *maxfiles"
.Ft int
.Fn kinfo_get_openfiles "int *openfiles"
.Ft int
.Fn kinfo_get_net_rtstatistics "struct rtstatistics *rts"
.Ft int
.Fn kinfo_get_cpus "int *ncpus"
.Ft int
.Fn kinfo_get_sched_cputime "struct kinfo_cputime *cputime"
.Ft int
.Fn kinfo_get_sched_hz "int *hz"
.Ft int
.Fn kinfo_get_sched_profhz "int *profhz"
.Ft int
.Fn kinfo_get_sched_stathz "int *stathz"
.Ft int
.Fn kinfo_get_tty_tk_nin "uint64_t *tk_nin"
.Ft int
.Fn kinfo_get_tty_tk_nout "uint64_t *tk_nout"
.Ft int
.Fn kinfo_get_vfs_bufspace "long *bufspace"
.Ft void
.Fn cputime_pcpu_statistics "struct kinfo_cputime *percpu" "struct kinfo_cputime *total" "int ncpu"
.Ft void
.Fn route_pcpu_statistics "struct rtstatistics *percpu" "struct rtstatistics *total" "int ncpu"
.Sh DESCRIPTION
.Ss File Information
The
.Fn kinfo_get_files
function returns the kernel's file table as a pointer to an array of
.Vt kinfo_file
structures in the
.Fa file_buf
argument.
The number of elements in the array is returned in
.Fa len .
It is the caller's responsibility to
.Fn free
the array.
.Pp
The
.Fn kinfo_get_maxfiles
and
.Fn kinfo_get_openfiles
functions return the maximum number of files and the number of open files in the
.Fa maxfiles
and
.Fa openfiles
arguments, respectively.
.Ss Networking Information
The
.Fn kinfo_get_net_rtstatistics
function retrieves routing statistics from the kernel and fills out a
.Vt struct rtstatistics ,
a pointer to which has to be specified by the caller in
.Fa rts .
.Ss Scheduling/Time Information
The
.Fn kinfo_get_cpus
function returns the number of active CPUs in the
.Fa ncpus
argument.
.Pp
The
.Fn kinfo_get_sched_cputime
function retrieves CPU time statistics from the kernel and fills out a
.Vt struct kinfo_cputime ,
a pointer to which has to be specified by the caller in
.Fa cputime .
.Pp
The
.Fn kinfo_get_sched_hz ,
.Fn kinfo_get_sched_profhz ,
and
.Fn kinfo_get_sched_stathz
functions retrieve system clock information from the kernel and return the
.Fa ci_hz ,
.Fa ci_profhz ,
and
.Fa ci_stathz
fields of
.Vt struct kinfo_clockinfo
in the
.Fa hz ,
.Fa profhz ,
and
.Fa stathz
arguments, respectively.
.Ss TTY Information
The
.Fn kinfo_get_tty_tk_nin
and
.Fn kinfo_get_tty_tk_nout
functions return the total number of characters which were input and output
on the system's TTYs in the
.Fa tk_nin
and
.Fa tk_nout
arguments, respectively.
.Ss VFS Information
The
.Fn kinfo_get_vfs_bufspace
function returns the maximum amount of memory available for VFS buffers in the
.Fa bufspace
argument.
.Ss Per CPU Accumulators
The
.Fn cputime_pcpu_statistics
and
.Fn route_pcpu_statistics
functions provide per-CPU routing and CPU time statistics.
Each take two pointers, one for the per-CPU statistics and another for
the total.
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
The
.Fn kinfo_get_cpus ,
.Fn kinfo_get_maxfiles ,
.Fn kinfo_get_openfiles ,
.Fn kinfo_get_sched_hz ,
.Fn kinfo_get_sched_profhz ,
.Fn kinfo_get_sched_stathz ,
.Fn kinfo_get_tty_tk_nin ,
.Fn kinfo_get_tty_tk_nout ,
and
.Fn kinfo_get_vfs_bufspace
functions can fail with the errors documented in
.Xr sysctlbyname 3 .
.Pp
The
.Fn kinfo_get_files ,
.Fn kinfo_get_net_rtstatistics ,
and
.Fn kinfo_get_sched_cputime
functions will fail if:
.Bl -tag -width Er
.It Bq Er ENOMEM
Insufficient memory was available.
.El
.Sh SEE ALSO
.\".Xr kcore 3 ,
.Xr kvm 3
.Sh HISTORY
The
.Nm kinfo
library first appeared in
.Dx 1.2 .
.Sh AUTHORS
.An "Joerg Sonnenberger"