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