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