lib/libkinfo/kinfo.3

   1 .\"
   2 .\" Copyright (c) 2015
   3 .\"     The DragonFly Project.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\" 3. Neither the name of The DragonFly Project nor the names of its
  16 .\"    contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific, prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd January 22, 2015
  33 .Dt KINFO 3
  34 .Os
  35 .Sh NAME
  36 .\".Nm cputime_pcpu_statistics ,
  37 .Nm kinfo_get_cpus ,
  38 .Nm kinfo_get_files ,
  39 .Nm kinfo_get_maxfiles ,
  40 .Nm kinfo_get_net_rtstatistics ,
  41 .Nm kinfo_get_openfiles ,
  42 .Nm kinfo_get_sched_cputime ,
  43 .Nm kinfo_get_sched_hz ,
  44 .Nm kinfo_get_sched_profhz ,
  45 .Nm kinfo_get_sched_stathz ,
  46 .Nm kinfo_get_tty_tk_nin ,
  47 .Nm kinfo_get_tty_tk_nout ,
  48 .Nm kinfo_get_vfs_bufspace
  49 .\".Nm route_pcpu_statistics
  50 .Nd information about the running kernel
  51 .Sh LIBRARY
  52 .Lb libkinfo
  53 .Sh SYNOPSIS
  54 .In kinfo.h
  55 .Ft int
  56 .Fn kinfo_get_files "struct kinfo_file **file_buf" "size_t *len"
  57 .Ft int
  58 .Fn kinfo_get_maxfiles "int *maxfiles"
  59 .Ft int
  60 .Fn kinfo_get_openfiles "int *openfiles"
  61 .Ft int
  62 .Fn kinfo_get_net_rtstatistics "struct rtstatistics *rts"
  63 .Ft int
  64 .Fn kinfo_get_cpus "int *ncpus"
  65 .Ft int
  66 .Fn kinfo_get_sched_cputime "struct kinfo_cputime *cputime"
  67 .Ft int
  68 .Fn kinfo_get_sched_hz "int *hz"
  69 .Ft int
  70 .Fn kinfo_get_sched_profhz "int *profhz"
  71 .Ft int
  72 .Fn kinfo_get_sched_stathz "int *stathz"
  73 .Ft int
  74 .Fn kinfo_get_tty_tk_nin "uint64_t *tk_nin"
  75 .Ft int
  76 .Fn kinfo_get_tty_tk_nout "uint64_t *tk_nout"
  77 .Ft int
  78 .Fn kinfo_get_vfs_bufspace "long *bufspace"
  79 .\".Ft void
  80 .\".Fn cputime_pcpu_statistics "struct kinfo_cputime *percpu" "struct kinfo_cputime *total" "int ncpu"
  81 .\".Ft void
  82 .\".Fn route_pcpu_statistics "struct rtstatistics *percpu" "struct rtstatistics *total" "int ncpu"
  83 .Sh DESCRIPTION
  84 .Ss File Information
  85 The
  86 .Fn kinfo_get_files
  87 function returns the kernel's file table as a pointer to an array of
  88 .Vt kinfo_file
  89 structures in the
  90 .Fa file_buf
  91 argument.
  92 The number of elements in the array is returned in
  93 .Fa len .
  94 It is the caller's responsibility to
  95 .Fn free
  96 the array.
  97 .Pp
  98 The
  99 .Fn kinfo_get_maxfiles
 100 and
 101 .Fn kinfo_get_openfiles
 102 functions return the maximum number of files and the number of open files in the
 103 .Fa maxfiles
 104 and
 105 .Fa openfiles
 106 arguments, respectively.
 107 .Ss Networking Information
 108 The
 109 .Fn kinfo_get_net_rtstatistics
 110 function retrieves routing statistics from the kernel and fills out a
 111 .Vt struct rtstatistics ,
 112 a pointer to which has to be specified by the caller in
 113 .Fa rts .
 114 .Ss Scheduling/Time Information
 115 The
 116 .Fn kinfo_get_cpus
 117 function returns the number of active CPUs in the
 118 .Fa ncpus
 119 argument.
 120 .Pp
 121 The
 122 .Fn kinfo_get_sched_cputime
 123 function retrieves CPU time statistics from the kernel and fills out a
 124 .Vt struct kinfo_cputime ,
 125 a pointer to which has to be specified by the caller in
 126 .Fa cputime .
 127 .Pp
 128 The
 129 .Fn kinfo_get_sched_hz ,
 130 .Fn kinfo_get_sched_profhz ,
 131 and
 132 .Fn kinfo_get_sched_stathz
 133 functions retrieve system clock information from the kernel and return the
 134 .Fa ci_hz ,
 135 .Fa ci_profhz ,
 136 and
 137 .Fa ci_stathz
 138 fields of
 139 .Vt struct kinfo_clockinfo
 140 in the
 141 .Fa hz ,
 142 .Fa profhz ,
 143 and
 144 .Fa stathz
 145 arguments, respectively.
 146 .Ss TTY Information
 147 The
 148 .Fn kinfo_get_tty_tk_nin
 149 and
 150 .Fn kinfo_get_tty_tk_nout
 151 functions return the total number of characters which were input and output
 152 on the system's TTYs in the
 153 .Fa tk_nin
 154 and
 155 .Fa tk_nout
 156 arguments, respectively.
 157 .Ss VFS Information
 158 The
 159 .Fn kinfo_get_vfs_bufspace
 160 function returns the maximum amount of memory available for VFS buffers in the
 161 .Fa bufspace
 162 argument.
 163 .\".Ss Per CPU Accumulators
 164 .\".Fn cputime_pcpu_statistics
 165 .\".Fn route_pcpu_statistics
 166 .Sh RETURN VALUES
 167 .Rv -std
 168 .Sh ERRORS
 169 The
 170 .Fn kinfo_get_cpus ,
 171 .Fn kinfo_get_maxfiles ,
 172 .Fn kinfo_get_openfiles ,
 173 .Fn kinfo_get_sched_hz ,
 174 .Fn kinfo_get_sched_profhz ,
 175 .Fn kinfo_get_sched_stathz ,
 176 .Fn kinfo_get_tty_tk_nin ,
 177 .Fn kinfo_get_tty_tk_nout ,
 178 and
 179 .Fn kinfo_get_vfs_bufspace
 180 functions can fail with the errors documented in
 181 .Xr sysctlbyname 3 .
 182 .Pp
 183 The
 184 .Fn kinfo_get_files ,
 185 .Fn kinfo_get_net_rtstatistics ,
 186 and
 187 .Fn kinfo_get_sched_cputime
 188 functions will fail if:
 189 .Bl -tag -width Er
 190 .It Bq Er ENOMEM
 191 Insufficient memory was available.
 192 .El
 193 .Sh SEE ALSO
 194 .\".Xr kcore 3 ,
 195 .Xr kvm 3
 196 .Sh HISTORY
 197 The
 198 .Nm kinfo
 199 library first appeared in
 200 .Dx 1.2 .
 201 .Sh AUTHORS
 202 .An "Joerg Sonnenberger"