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_kvm ,
  32 .Nm procstat_open_sysctl ,
  33 .Nm procstat_close ,
  34 .Nm procstat_getfiles ,
  35 .Nm procstat_getprocs ,
  36 .Nm procstat_freefiles ,
  37 .Nm procstat_freeprocs ,
  38 .Nm procstat_get_pipe_info ,
  39 .Nm procstat_get_pts_info ,
  40 .Nm procstat_get_shm_info ,
  41 .Nm procstat_get_socket_info ,
  42 .Nm procstat_get_vnode_info
  43 .Nd library interface for file and process information retrieval
  44 .Sh LIBRARY
  45 .Lb libprocstat
  46 .Sh SYNOPSIS
  47 .In sys/param.h
  48 .In sys/queue.h
  49 .In libprocstat.h
  50 .Ft void
  51 .Fn procstat_close "struct procstat *procstat"
  52 .Ft void
  53 .Fo procstat_freefiles
  54 .Fa "struct procstat *procstat"
  55 .Fa "struct filestat_list *head"
  56 .Fc
  57 .Ft void
  58 .Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
  59 .Ft int
  60 .Fo procstat_get_pipe_info
  61 .Fa "struct procstat *procstat"
  62 .Fa "struct filestat *fst"
  63 .Fa "struct pipestat *pipe"
  64 .Fa "char *errbuf"
  65 .Fc
  66 .Ft int
  67 .Fo procstat_get_pts_info
  68 .Fa "struct procstat *procstat"
  69 .Fa "struct filestat *fst"
  70 .Fa "struct ptsstat *pts"
  71 .Fa "char *errbuf"
  72 .Fc
  73 .Ft int
  74 .Fo procstat_get_shm_info
  75 .Fa "struct procstat *procstat"
  76 .Fa "struct filestat *fst"
  77 .Fa "struct shmstat *shm"
  78 .Fa "char *errbuf"
  79 .Fc
  80 .Ft int
  81 .Fo procstat_get_socket_info
  82 .Fa "struct procstat *procstat"
  83 .Fa "struct filestat *fst"
  84 .Fa "struct sockstat *sock"
  85 .Fa "char *errbuf"
  86 .Fc
  87 .Ft int
  88 .Fo procstat_get_vnode_info
  89 .Fa "struct procstat *procstat"
  90 .Fa "struct filestat *fst"
  91 .Fa "struct vnstat *vn"
  92 .Fa "char *errbuf"
  93 .Fc
  94 .Ft "struct filestat_list *"
  95 .Fo procstat_getfiles
  96 .Fa "struct procstat *procstat"
  97 .Fa "struct kinfo_proc *kp"
  98 .Fa "int mmapped"
  99 .Fc
 100 .Ft "struct kinfo_proc *"
 101 .Fo procstat_getprocs
 102 .Fa "struct procstat *procstat"
 103 .Fa "int what"
 104 .Fa "int arg"
 105 .Fa "unsigned int *count"
 106 .Fc
 107 .Ft "struct procstat *"
 108 .Fn procstat_open_kvm "const char *nlistf" "const char *memf"
 109 .Ft "struct procstat *"
 110 .Fn procstat_open_sysctl void
 111 .Sh DESCRIPTION
 112 The
 113 .Nm libprocstat
 114 library contains the API for runtime file and process information
 115 retrieval from the running kernel via the
 116 .Xr sysctl 3
 117 library backend, and for post-mortem analysis via the
 118 .Xr kvm 3
 119 library backend.
 120 .Pp
 121 The
 122 .Fn procstat_open_kvm
 123 and
 124 .Fn procstat_open_sysctl
 125 functions use the
 126 .Xr kvm 3
 127 or
 128 .Xr sysctl 3
 129 library routines, respectively, to access kernel state information
 130 used to retrieve processes and files states.
 131 The
 132 .Fa nlistf
 133 argument is the executable image of the kernel being examined.
 134 If this argument is
 135 .Dv NULL ,
 136 the currently running kernel is assumed.
 137 The
 138 .Fa memf
 139 argument is the kernel memory device file.
 140 If this argument is
 141 .Dv NULL ,
 142 then
 143 .Pa /dev/mem
 144 is assumed.
 145 See
 146 .Xr kvm_open 3
 147 for more details.
 148 Both functions dynamically allocate and return a
 149 .Vt procstat
 150 structure pointer used in the rest of the
 151 .Nm libprocstat
 152 library routines until the corresponding
 153 .Fn procstat_close
 154 call that cleans up the resources allocated by the
 155 .Fn procstat_open_*
 156 functions.
 157 .Pp
 158 The
 159 .Fn procstat_getprocs
 160 function gets a pointer to the
 161 .Vt procstat
 162 structure from one of the
 163 .Fn procstat_open_*
 164 functions and returns a dynamically allocated (sub-)set of active processes
 165 in the kernel filled in to array of
 166 .Vt kinfo_proc
 167 structures.
 168 The
 169 .Fa what
 170 and
 171 .Fa arg
 172 arguments constitute a filtering predicate as described in the
 173 .Xr kvm_getprocs 3
 174 function.
 175 The number of processes found is returned in the reference parameter
 176 .Fa cnt .
 177 The caller is responsible to free the allocated memory with a subsequent
 178 .Fn procstat_freeprocs
 179 function call.
 180 .Pp
 181 The
 182 .Fn procstat_getfiles
 183 function gets a pointer to the
 184 .Vt procstat
 185 structure initialized with one of the
 186 .Fn procstat_open_*
 187 functions, a pointer to
 188 .Vt kinfo_proc
 189 structure from the array obtained from the
 190 .Fn kvm_getprocs
 191 function, and returns a dynamically allocated linked list of filled in
 192 .Vt filestat_list
 193 structures using the STAILQ macros defined in
 194 .Xr queue 3 .
 195 The caller is responsible to free the allocated memory with a subsequent
 196 .Fn procstat_freefiles
 197 function call.
 198 .Pp
 199 The
 200 .Fn procstat_get_pipe_info ,
 201 .Fn procstat_get_pts_info ,
 202 .Fn procstat_get_shm_info ,
 203 .Fn procstat_get_socket_info
 204 and
 205 .Fn procstat_get_vnode_info
 206 functions are used to retrieve information about pipes, pseudo-terminals,
 207 shared memory objects,
 208 sockets, and vnodes, respectively.
 209 Each of them have a similar interface API.
 210 The
 211 .Fa procstat
 212 argument is a pointer obtained from one of
 213 .Fn procstat_open_*
 214 functions.
 215 The
 216 .Ft filestat Fa fst
 217 argument is an element of STAILQ linked list as obtained from the
 218 .Fn procstat_getfiles
 219 function.
 220 The
 221 .Ft filestat
 222 structure contains a
 223 .Fa fs_type
 224 field that specifies a file type and a corresponding function to be
 225 called among the
 226 .Nm procstat_get_*_info
 227 function family.
 228 The actual object is returned in the 3rd reference parameter.
 229 The
 230 .Fa errbuf
 231 argument indicates an actual error message in case of failure.
 232 .Pp
 233 .Bl -tag -width 20n -compact -offset indent
 234 .It Li PS_FST_TYPE_FIFO
 235 .Nm procstat_get_vnode_info
 236 .It Li PS_FST_TYPE_VNODE
 237 .Nm procstat_get_vnode_info
 238 .It Li PS_FST_TYPE_SOCKET
 239 .Nm procstat_get_socket_info
 240 .It Li PS_FST_TYPE_PIPE
 241 .Nm procstat_get_pipe_info
 242 .It Li PS_FST_TYPE_PTS
 243 .Nm procstat_get_pts_info
 244 .It Li PS_FST_TYPE_SHM
 245 .Nm procstat_get_shm_info
 246 .El
 247 .Sh SEE ALSO
 248 .Xr fstat 1 ,
 249 .Xr fuser 1 ,
 250 .Xr pipe 2 ,
 251 .Xr shm_open 2 ,
 252 .Xr socket 2 ,
 253 .Xr kvm 3 ,
 254 .Xr queue 3 ,
 255 .Xr sysctl 3 ,
 256 .Xr pts 4 ,
 257 .Xr vnode 9
 258 .Sh HISTORY
 259 The
 260 .Nm libprocstat
 261 library appeared in
 262 .Fx 9.0 .
 263 .Sh AUTHORS
 264 .An -nosplit
 265 The
 266 .Nm libprocstat
 267 library was written by
 268 .An Stanislav Sedov Aq stas@FreeBSD.org .
 269 .Pp
 270 This manual page was written by
 271 .An Sergey Kandaurov Aq pluknet@FreeBSD.org .