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