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