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 20, 2013
  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_getargv ,
  36 .Nm procstat_getauxv ,
  37 .Nm procstat_getenvv ,
  38 .Nm procstat_getfiles ,
  39 .Nm procstat_getgroups ,
  40 .Nm procstat_getkstack ,
  41 .Nm procstat_getosrel ,
  42 .Nm procstat_getpathname ,
  43 .Nm procstat_getprocs ,
  44 .Nm procstat_getumask ,
  45 .Nm procstat_getvmmap ,
  46 .Nm procstat_freeargv ,
  47 .Nm procstat_freeauxv ,
  48 .Nm procstat_freeenvv ,
  49 .Nm procstat_freefiles ,
  50 .Nm procstat_freegroups ,
  51 .Nm procstat_freekstack ,
  52 .Nm procstat_freeprocs ,
  53 .Nm procstat_freevmmap ,
  54 .Nm procstat_get_pipe_info ,
  55 .Nm procstat_get_pts_info ,
  56 .Nm procstat_get_shm_info ,
  57 .Nm procstat_get_socket_info ,
  58 .Nm procstat_get_vnode_info
  59 .Nd library interface for file and process information retrieval
  60 .Sh LIBRARY
  61 .Lb libprocstat
  62 .Sh SYNOPSIS
  63 .In sys/param.h
  64 .In sys/queue.h
  65 .In libprocstat.h
  66 .Ft void
  67 .Fn procstat_close "struct procstat *procstat"
  68 .Ft void
  69 .Fo procstat_freeargv
  70 .Fa "struct procstat *procstat"
  71 .Fc
  72 .Ft void
  73 .Fo procstat_freeauxv
  74 .Fa "struct procstat *procstat"
  75 .Fa "Elf_Auxinfo *auxv"
  76 .Fc
  77 .Ft void
  78 .Fo procstat_freeenvv
  79 .Fa "struct procstat *procstat"
  80 .Fc
  81 .Ft void
  82 .Fo procstat_freefiles
  83 .Fa "struct procstat *procstat"
  84 .Fa "struct filestat_list *head"
  85 .Fc
  86 .Ft void
  87 .Fo procstat_freegroups
  88 .Fa "struct procstat *procstat"
  89 .Fa "gid_t *groups"
  90 .Fc
  91 .Ft void
  92 .Fo procstat_freekstack
  93 .Fa "struct procstat *procstat"
  94 .Fa "struct kinfo_kstack *kkstp"
  95 .Fc
  96 .Ft void
  97 .Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
  98 .Ft void
  99 .Fo procstat_freevmmap
 100 .Fa "struct procstat *procstat"
 101 .Fa "struct kinfo_vmentry *vmmap"
 102 .Fc
 103 .Ft int
 104 .Fo procstat_get_pipe_info
 105 .Fa "struct procstat *procstat"
 106 .Fa "struct filestat *fst"
 107 .Fa "struct pipestat *pipe"
 108 .Fa "char *errbuf"
 109 .Fc
 110 .Ft int
 111 .Fo procstat_get_pts_info
 112 .Fa "struct procstat *procstat"
 113 .Fa "struct filestat *fst"
 114 .Fa "struct ptsstat *pts"
 115 .Fa "char *errbuf"
 116 .Fc
 117 .Ft int
 118 .Fo procstat_get_shm_info
 119 .Fa "struct procstat *procstat"
 120 .Fa "struct filestat *fst"
 121 .Fa "struct shmstat *shm"
 122 .Fa "char *errbuf"
 123 .Fc
 124 .Ft int
 125 .Fo procstat_get_socket_info
 126 .Fa "struct procstat *procstat"
 127 .Fa "struct filestat *fst"
 128 .Fa "struct sockstat *sock"
 129 .Fa "char *errbuf"
 130 .Fc
 131 .Ft int
 132 .Fo procstat_get_vnode_info
 133 .Fa "struct procstat *procstat"
 134 .Fa "struct filestat *fst"
 135 .Fa "struct vnstat *vn"
 136 .Fa "char *errbuf"
 137 .Fc
 138 .Ft "char **"
 139 .Fo procstat_getargv
 140 .Fa "struct procstat *procstat"
 141 .Fa "const struct kinfo_proc *kp"
 142 .Fa "size_t nchr"
 143 .Fa "char *errbuf"
 144 .Fc
 145 .Ft "Elf_Auxinfo *"
 146 .Fo procstat_getauxv
 147 .Fa "struct procstat *procstat"
 148 .Fa "struct kinfo_proc *kp"
 149 .Fa "unsigned int *count"
 150 .Fc
 151 .Ft "char **"
 152 .Fo procstat_getenvv
 153 .Fa "struct procstat *procstat"
 154 .Fa "const struct kinfo_proc *kp"
 155 .Fa "size_t nchr"
 156 .Fa "char *errbuf"
 157 .Fc
 158 .Ft "struct filestat_list *"
 159 .Fo procstat_getfiles
 160 .Fa "struct procstat *procstat"
 161 .Fa "struct kinfo_proc *kp"
 162 .Fa "int mmapped"
 163 .Fc
 164 .Ft "gid_t *"
 165 .Fo procstat_getgroups
 166 .Fa "struct procstat *procstat"
 167 .Fa "struct kinfo_proc *kp"
 168 .Fa "unsigned int *count"
 169 .Fc
 170 .Ft int
 171 .Fo procstat_getosrel
 172 .Fa "struct procstat *procstat"
 173 .Fa "struct kinfo_proc *kp"
 174 .Fa "int *osrelp"
 175 .Fc
 176 .Ft "struct kinfo_kstack *"
 177 .Fo procstat_getkstack
 178 .Fa "struct procstat *procstat"
 179 .Fa "struct kinfo_proc *kp"
 180 .Fa "unsigned int *count"
 181 .Fc
 182 .Ft "struct kinfo_proc *"
 183 .Fo procstat_getprocs
 184 .Fa "struct procstat *procstat"
 185 .Fa "int what"
 186 .Fa "int arg"
 187 .Fa "unsigned int *count"
 188 .Fc
 189 .Ft "int"
 190 .Fo procstat_getpathname
 191 .Fa "struct procstat *procstat"
 192 .Fa "struct kinfo_proc *kp"
 193 .Fa "char *pathname"
 194 .Fa "size_t maxlen"
 195 .Fc
 196 .Ft "int"
 197 .Fo procstat_getrlimit
 198 .Fa "struct procstat *procstat"
 199 .Fa "struct kinfo_proc *kp"
 200 .Fa "int which"
 201 .Fa "struct rlimit* rlimit"
 202 .Fc
 203 .Ft "int"
 204 .Fo procstat_getumask
 205 .Fa "struct procstat *procstat"
 206 .Fa "struct kinfo_proc *kp"
 207 .Fa "unsigned short *maskp"
 208 .Fc
 209 .Ft "struct kinfo_vmentry *"
 210 .Fo procstat_getvmmap
 211 .Fa "struct procstat *procstat"
 212 .Fa "struct kinfo_proc *kp"
 213 .Fa "unsigned int *count"
 214 .Fc
 215 .Ft "struct procstat *"
 216 .Fn procstat_open_core "const char *filename"
 217 .Ft "struct procstat *"
 218 .Fn procstat_open_kvm "const char *nlistf" "const char *memf"
 219 .Ft "struct procstat *"
 220 .Fn procstat_open_sysctl void
 221 .Sh DESCRIPTION
 222 The
 223 .Nm libprocstat
 224 library contains the API for runtime file and process information
 225 retrieval from the running kernel via the
 226 .Xr sysctl 3
 227 library backend, and for post-mortem analysis via the
 228 .Xr kvm 3
 229 library backend, or from the process
 230 .Xr core 5
 231 file, searching for statistics in special
 232 .Xr elf 3
 233 note sections.
 234 .Pp
 235 The
 236 .Fn procstat_open_kvm
 237 and
 238 .Fn procstat_open_sysctl
 239 functions use the
 240 .Xr kvm 3
 241 or
 242 .Xr sysctl 3
 243 library routines, respectively, to access kernel state information
 244 used to retrieve processes and files states.
 245 The
 246 .Fn procstat_open_core
 247 uses
 248 .Xr elf 3
 249 routines to access statistics stored as a set of notes in a process
 250 .Xr core 5
 251 file, written by the kernel at the moment of the process abnormal termination.
 252 The
 253 .Fa filename
 254 argument is the process core file name.
 255 The
 256 .Fa nlistf
 257 argument is the executable image of the kernel being examined.
 258 If this argument is
 259 .Dv NULL ,
 260 the currently running kernel is assumed.
 261 The
 262 .Fa memf
 263 argument is the kernel memory device file.
 264 If this argument is
 265 .Dv NULL ,
 266 then
 267 .Pa /dev/mem
 268 is assumed.
 269 See
 270 .Xr kvm_open 3
 271 for more details.
 272 The functions dynamically allocate and return a
 273 .Vt procstat
 274 structure pointer used in the rest of the
 275 .Nm libprocstat
 276 library routines until the corresponding
 277 .Fn procstat_close
 278 call that cleans up the resources allocated by the
 279 .Fn procstat_open_*
 280 functions.
 281 .Pp
 282 The
 283 .Fn procstat_getprocs
 284 function gets a pointer to the
 285 .Vt procstat
 286 structure from one of the
 287 .Fn procstat_open_*
 288 functions and returns a dynamically allocated (sub-)set of active processes
 289 in the kernel filled in to array of
 290 .Vt kinfo_proc
 291 structures.
 292 The
 293 .Fa what
 294 and
 295 .Fa arg
 296 arguments constitute a filtering predicate as described in the
 297 .Xr kvm_getprocs 3
 298 function.
 299 The number of processes found is returned in the reference parameter
 300 .Fa cnt .
 301 The caller is responsible to free the allocated memory with a subsequent
 302 .Fn procstat_freeprocs
 303 function call.
 304 .Pp
 305 The
 306 .Fn procstat_getargv
 307 function gets a pointer to the
 308 .Vt procstat
 309 structure from one of the
 310 .Fn procstat_open_*
 311 functions, a pointer to
 312 .Vt kinfo_proc
 313 structure from the array obtained from the
 314 .Fn kvm_getprocs
 315 function, and returns a null-terminated argument vector that corresponds to
 316 the command line arguments passed to the process.
 317 The
 318 .Fa nchr
 319 argument indicates the maximum number of characters, including null bytes,
 320 to use in building the strings.
 321 If this amount is exceeded, the string causing the overflow is truncated and
 322 the partial result is returned.
 323 This is handy for programs that print only a one line summary of a
 324 command and should not copy out large amounts of text only to ignore it.
 325 If
 326 .Fa nchr
 327 is zero, no limit is imposed and all argument strings are returned.
 328 The values of the returned argument vector refer the strings stored
 329 in the
 330 .Vt procstat
 331 internal buffer.
 332 A subsequent call of the function with the same
 333 .Vt procstat
 334 argument will reuse the buffer.
 335 To free the allocated memory
 336 .Fn procstat_freeargv
 337 function call can be used, or it will be released on
 338 .Fn procstat_close .
 339 .Pp
 340 The
 341 .Fn procstat_getenvv
 342 function is similar to
 343 .Fn procstat_getargv
 344 but returns the vector of environment strings.
 345 The caller may free the allocated memory with a subsequent
 346 .Fn procstat_freeenv
 347 function call.
 348 .Pp
 349 The
 350 .Fn procstat_getauxv
 351 function gets a pointer to the
 352 .Vt procstat
 353 structure, a pointer to
 354 .Vt kinfo_proc
 355 structure, and returns the auxiliary vector as a dynamically allocated array of
 356 .Vt Elf_Auxinfo
 357 elements.
 358 The caller is responsible to free the allocated memory with a subsequent
 359 .Fn procstat_freeauxv
 360 function call.
 361 .Pp
 362 The
 363 .Fn procstat_getfiles
 364 function gets a pointer to the
 365 .Vt procstat
 366 structure initialized with one of the
 367 .Fn procstat_open_*
 368 functions, a pointer to
 369 .Vt kinfo_proc
 370 structure from the array obtained from the
 371 .Fn kvm_getprocs
 372 function, and returns a dynamically allocated linked list of filled in
 373 .Vt filestat_list
 374 structures using the STAILQ macros defined in
 375 .Xr queue 3 .
 376 The caller is responsible to free the allocated memory with a subsequent
 377 .Fn procstat_freefiles
 378 function call.
 379 .Pp
 380 The
 381 .Fn procstat_getgroups
 382 function gets a pointer to the
 383 .Vt procstat
 384 structure, a pointer to
 385 .Vt kinfo_proc
 386 structure, and returns the process groups as a dynamically allocated array of
 387 .Vt gid_t
 388 elements.
 389 The caller is responsible to free the allocated memory with a subsequent
 390 .Fn procstat_freegroups
 391 function call.
 392 .Pp
 393 The
 394 .Fn procstat_getkstack
 395 function gets a pointer to the
 396 .Vt procstat
 397 structure initialized with one of the
 398 .Fn procstat_open_*
 399 functions, a pointer to
 400 .Vt kinfo_proc
 401 structure, and returns kernel stacks of the process as a dynamically allocated
 402 array of
 403 .Vt kinfo_kstack
 404 structures.
 405 The caller is responsible to free the allocated memory with a subsequent
 406 .Fn procstat_freekstack
 407 function call.
 408 .Pp
 409 The
 410 .Fn procstat_getosrel
 411 function gets a pointer to the
 412 .Vt procstat
 413 structure, a pointer to
 414 .Vt kinfo_proc
 415 structure, and returns osrel date in the 3rd reference parameter.
 416 .Pp
 417 The
 418 .Fn procstat_getpathname
 419 function gets a pointer to the
 420 .Vt procstat
 421 structure, a pointer to
 422 .Vt kinfo_proc
 423 structure, and copies the path of the process executable to
 424 .Fa pathname
 425 buffer, limiting to
 426 .Fa maxlen
 427 characters.
 428 .Pp
 429 The
 430 .Fn procstat_getrlimit
 431 function gets a pointer to the
 432 .Vt procstat
 433 structure, a pointer to
 434 .Vt kinfo_proc
 435 structure, resource index
 436 .Fa which ,
 437 and returns the actual resource limit in the 4th reference parameter.
 438 .Pp
 439 The
 440 .Fn procstat_getumask
 441 function gets a pointer to the
 442 .Vt procstat
 443 structure, a pointer to
 444 .Vt kinfo_proc
 445 structure, and returns the process umask in the 3rd reference parameter.
 446 .Pp
 447 The
 448 .Fn procstat_getvmmap
 449 function gets a pointer to the
 450 .Vt procstat
 451 structure initialized with one of the
 452 .Fn procstat_open_*
 453 functions, a pointer to
 454 .Vt kinfo_proc
 455 structure, and returns VM layout of the process as a dynamically allocated
 456 array of
 457 .Vt kinfo_vmentry
 458 structures.
 459 The caller is responsible to free the allocated memory with a subsequent
 460 .Fn procstat_freevmmap
 461 function call.
 462 .Pp
 463 The
 464 .Fn procstat_get_pipe_info ,
 465 .Fn procstat_get_pts_info ,
 466 .Fn procstat_get_shm_info ,
 467 .Fn procstat_get_socket_info
 468 and
 469 .Fn procstat_get_vnode_info
 470 functions are used to retrieve information about pipes, pseudo-terminals,
 471 shared memory objects,
 472 sockets, and vnodes, respectively.
 473 Each of them have a similar interface API.
 474 The
 475 .Fa procstat
 476 argument is a pointer obtained from one of
 477 .Fn procstat_open_*
 478 functions.
 479 The
 480 .Ft filestat Fa fst
 481 argument is an element of STAILQ linked list as obtained from the
 482 .Fn procstat_getfiles
 483 function.
 484 The
 485 .Ft filestat
 486 structure contains a
 487 .Fa fs_type
 488 field that specifies a file type and a corresponding function to be
 489 called among the
 490 .Nm procstat_get_*_info
 491 function family.
 492 The actual object is returned in the 3rd reference parameter.
 493 The
 494 .Fa errbuf
 495 argument indicates an actual error message in case of failure.
 496 .Pp
 497 .Bl -tag -width 20n -compact -offset indent
 498 .It Li PS_FST_TYPE_FIFO
 499 .Nm procstat_get_vnode_info
 500 .It Li PS_FST_TYPE_VNODE
 501 .Nm procstat_get_vnode_info
 502 .It Li PS_FST_TYPE_SOCKET
 503 .Nm procstat_get_socket_info
 504 .It Li PS_FST_TYPE_PIPE
 505 .Nm procstat_get_pipe_info
 506 .It Li PS_FST_TYPE_PTS
 507 .Nm procstat_get_pts_info
 508 .It Li PS_FST_TYPE_SHM
 509 .Nm procstat_get_shm_info
 510 .El
 511 .Sh SEE ALSO
 512 .Xr fstat 1 ,
 513 .Xr fuser 1 ,
 514 .Xr pipe 2 ,
 515 .Xr shm_open 2 ,
 516 .Xr socket 2 ,
 517 .Xr elf 3 ,
 518 .Xr kvm 3 ,
 519 .Xr queue 3 ,
 520 .Xr sysctl 3 ,
 521 .Xr pts 4 ,
 522 .Xr core 5 ,
 523 .Xr vnode 9
 524 .Sh HISTORY
 525 The
 526 .Nm libprocstat
 527 library appeared in
 528 .Fx 9.0 .
 529 .Sh AUTHORS
 530 .An -nosplit
 531 The
 532 .Nm libprocstat
 533 library was written by
 534 .An Stanislav Sedov Aq stas@FreeBSD.org .
 535 .Pp
 536 This manual page was written by
 537 .An Sergey Kandaurov Aq pluknet@FreeBSD.org .