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