lib/libprocstat/libprocstat.3

   1 .\" Copyright (c) 2011 Sergey Kandaurov <pluknet@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd April 1, 2012
  28 .Dt LIBPROCSTAT 3
  29 .Os
  30 .Sh NAME
  31 .Nm procstat_open_core ,
  32 .Nm procstat_open_kvm ,
  33 .Nm procstat_open_sysctl ,
  34 .Nm procstat_close ,
  35 .Nm procstat_getfiles ,
  36 .Nm procstat_getprocs ,
  37 .Nm procstat_freefiles ,
  38 .Nm procstat_freeprocs ,
  39 .Nm procstat_get_pipe_info ,
  40 .Nm procstat_get_pts_info ,
  41 .Nm procstat_get_shm_info ,
  42 .Nm procstat_get_socket_info ,
  43 .Nm procstat_get_vnode_info
  44 .Nd library interface for file and process information retrieval
  45 .Sh LIBRARY
  46 .Lb libprocstat
  47 .Sh SYNOPSIS
  48 .In sys/param.h
  49 .In sys/queue.h
  50 .In libprocstat.h
  51 .Ft void
  52 .Fn procstat_close "struct procstat *procstat"
  53 .Ft void
  54 .Fo procstat_freefiles
  55 .Fa "struct procstat *procstat"
  56 .Fa "struct filestat_list *head"
  57 .Fc
  58 .Ft void
  59 .Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
  60 .Ft int
  61 .Fo procstat_get_pipe_info
  62 .Fa "struct procstat *procstat"
  63 .Fa "struct filestat *fst"
  64 .Fa "struct pipestat *pipe"
  65 .Fa "char *errbuf"
  66 .Fc
  67 .Ft int
  68 .Fo procstat_get_pts_info
  69 .Fa "struct procstat *procstat"
  70 .Fa "struct filestat *fst"
  71 .Fa "struct ptsstat *pts"
  72 .Fa "char *errbuf"
  73 .Fc
  74 .Ft int
  75 .Fo procstat_get_shm_info
  76 .Fa "struct procstat *procstat"
  77 .Fa "struct filestat *fst"
  78 .Fa "struct shmstat *shm"
  79 .Fa "char *errbuf"
  80 .Fc
  81 .Ft int
  82 .Fo procstat_get_socket_info
  83 .Fa "struct procstat *procstat"
  84 .Fa "struct filestat *fst"
  85 .Fa "struct sockstat *sock"
  86 .Fa "char *errbuf"
  87 .Fc
  88 .Ft int
  89 .Fo procstat_get_vnode_info
  90 .Fa "struct procstat *procstat"
  91 .Fa "struct filestat *fst"
  92 .Fa "struct vnstat *vn"
  93 .Fa "char *errbuf"
  94 .Fc
  95 .Ft "struct filestat_list *"
  96 .Fo procstat_getfiles
  97 .Fa "struct procstat *procstat"
  98 .Fa "struct kinfo_proc *kp"
  99 .Fa "int mmapped"
 100 .Fc
 101 .Ft "struct kinfo_proc *"
 102 .Fo procstat_getprocs
 103 .Fa "struct procstat *procstat"
 104 .Fa "int what"
 105 .Fa "int arg"
 106 .Fa "unsigned int *count"
 107 .Fc
 108 .Ft "struct procstat *"
 109 .Fn procstat_open_core "const char *filename"
 110 .Ft "struct procstat *"
 111 .Fn procstat_open_kvm "const char *nlistf" "const char *memf"
 112 .Ft "struct procstat *"
 113 .Fn procstat_open_sysctl void
 114 .Sh DESCRIPTION
 115 The
 116 .Nm libprocstat
 117 library contains the API for runtime file and process information
 118 retrieval from the running kernel via the
 119 .Xr sysctl 3
 120 library backend, and for post-mortem analysis via the
 121 .Xr kvm 3
 122 library backend, or from the process
 123 .Xr core 5
 124 file, searching for statistics in special
 125 .Xr elf 3
 126 note sections.
 127 .Pp
 128 The
 129 .Fn procstat_open_kvm
 130 and
 131 .Fn procstat_open_sysctl
 132 functions use the
 133 .Xr kvm 3
 134 or
 135 .Xr sysctl 3
 136 library routines, respectively, to access kernel state information
 137 used to retrieve processes and files states.
 138 The
 139 .Fn procstat_open_core
 140 uses
 141 .Xr elf 3
 142 routines to access statistics stored as a set of notes in a process
 143 .Xr core 5
 144 file, written by the kernel at the moment of the process abnormal termination.
 145 The
 146 .Fa filename
 147 argument is the process core file name.
 148 The
 149 .Fa nlistf
 150 argument is the executable image of the kernel being examined.
 151 If this argument is
 152 .Dv NULL ,
 153 the currently running kernel is assumed.
 154 The
 155 .Fa memf
 156 argument is the kernel memory device file.
 157 If this argument is
 158 .Dv NULL ,
 159 then
 160 .Pa /dev/mem
 161 is assumed.
 162 See
 163 .Xr kvm_open 3
 164 for more details.
 165 The functions dynamically allocate and return a
 166 .Vt procstat
 167 structure pointer used in the rest of the
 168 .Nm libprocstat
 169 library routines until the corresponding
 170 .Fn procstat_close
 171 call that cleans up the resources allocated by the
 172 .Fn procstat_open_*
 173 functions.
 174 .Pp
 175 The
 176 .Fn procstat_getprocs
 177 function gets a pointer to the
 178 .Vt procstat
 179 structure from one of the
 180 .Fn procstat_open_*
 181 functions and returns a dynamically allocated (sub-)set of active processes
 182 in the kernel filled in to array of
 183 .Vt kinfo_proc
 184 structures.
 185 The
 186 .Fa what
 187 and
 188 .Fa arg
 189 arguments constitute a filtering predicate as described in the
 190 .Xr kvm_getprocs 3
 191 function.
 192 The number of processes found is returned in the reference parameter
 193 .Fa cnt .
 194 The caller is responsible to free the allocated memory with a subsequent
 195 .Fn procstat_freeprocs
 196 function call.
 197 .Pp
 198 The
 199 .Fn procstat_getfiles
 200 function gets a pointer to the
 201 .Vt procstat
 202 structure initialized with one of the
 203 .Fn procstat_open_*
 204 functions, a pointer to
 205 .Vt kinfo_proc
 206 structure from the array obtained from the
 207 .Fn kvm_getprocs
 208 function, and returns a dynamically allocated linked list of filled in
 209 .Vt filestat_list
 210 structures using the STAILQ macros defined in
 211 .Xr queue 3 .
 212 The caller is responsible to free the allocated memory with a subsequent
 213 .Fn procstat_freefiles
 214 function call.
 215 .Pp
 216 The
 217 .Fn procstat_get_pipe_info ,
 218 .Fn procstat_get_pts_info ,
 219 .Fn procstat_get_shm_info ,
 220 .Fn procstat_get_socket_info
 221 and
 222 .Fn procstat_get_vnode_info
 223 functions are used to retrieve information about pipes, pseudo-terminals,
 224 shared memory objects,
 225 sockets, and vnodes, respectively.
 226 Each of them have a similar interface API.
 227 The
 228 .Fa procstat
 229 argument is a pointer obtained from one of
 230 .Fn procstat_open_*
 231 functions.
 232 The
 233 .Ft filestat Fa fst
 234 argument is an element of STAILQ linked list as obtained from the
 235 .Fn procstat_getfiles
 236 function.
 237 The
 238 .Ft filestat
 239 structure contains a
 240 .Fa fs_type
 241 field that specifies a file type and a corresponding function to be
 242 called among the
 243 .Nm procstat_get_*_info
 244 function family.
 245 The actual object is returned in the 3rd reference parameter.
 246 The
 247 .Fa errbuf
 248 argument indicates an actual error message in case of failure.
 249 .Pp
 250 .Bl -tag -width 20n -compact -offset indent
 251 .It Li PS_FST_TYPE_FIFO
 252 .Nm procstat_get_vnode_info
 253 .It Li PS_FST_TYPE_VNODE
 254 .Nm procstat_get_vnode_info
 255 .It Li PS_FST_TYPE_SOCKET
 256 .Nm procstat_get_socket_info
 257 .It Li PS_FST_TYPE_PIPE
 258 .Nm procstat_get_pipe_info
 259 .It Li PS_FST_TYPE_PTS
 260 .Nm procstat_get_pts_info
 261 .It Li PS_FST_TYPE_SHM
 262 .Nm procstat_get_shm_info
 263 .El
 264 .Sh SEE ALSO
 265 .Xr fstat 1 ,
 266 .Xr fuser 1 ,
 267 .Xr pipe 2 ,
 268 .Xr shm_open 2 ,
 269 .Xr socket 2 ,
 270 .Xr elf 3 ,
 271 .Xr kvm 3 ,
 272 .Xr queue 3 ,
 273 .Xr sysctl 3 ,
 274 .Xr pts 4 ,
 275 .Xr core 5 ,
 276 .Xr vnode 9
 277 .Sh HISTORY
 278 The
 279 .Nm libprocstat
 280 library appeared in
 281 .Fx 9.0 .
 282 .Sh AUTHORS
 283 .An -nosplit
 284 The
 285 .Nm libprocstat
 286 library was written by
 287 .An Stanislav Sedov Aq stas@FreeBSD.org .
 288 .Pp
 289 This manual page was written by
 290 .An Sergey Kandaurov Aq pluknet@FreeBSD.org .