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 248The 249.Nm libprocstat 250library contains the API for runtime file and process information 251retrieval from the running kernel via the 252.Xr sysctl 3 253library backend, and for post-mortem analysis via the 254.Xr kvm 3 255library backend, or from the process 256.Xr core 5 257file, searching for statistics in special 258.Xr elf 3 259note sections. 260.Pp 261The 262.Fn procstat_open_kvm 263and 264.Fn procstat_open_sysctl 265functions use the 266.Xr kvm 3 267or 268.Xr sysctl 3 269library routines, respectively, to access kernel state information 270used to retrieve processes and files states. 271The 272.Fn procstat_open_core 273uses 274.Xr elf 3 275routines to access statistics stored as a set of notes in a process 276.Xr core 5 277file, written by the kernel at the moment of the process abnormal termination. 278The 279.Fa filename 280argument is the process core file name. 281The 282.Fa nlistf 283argument is the executable image of the kernel being examined. 284If this argument is 285.Dv NULL , 286the currently running kernel is assumed. 287The 288.Fa memf 289argument is the kernel memory device file. 290If this argument is 291.Dv NULL , 292then 293.Pa /dev/mem 294is assumed. 295See 296.Xr kvm_open 3 297for more details. 298The functions dynamically allocate and return a 299.Vt procstat 300structure pointer used in the rest of the 301.Nm libprocstat 302library routines until the corresponding 303.Fn procstat_close 304call that cleans up the resources allocated by the 305.Fn procstat_open_* 306functions. 307.Pp 308The 309.Fn procstat_getprocs 310function gets a pointer to the 311.Vt procstat 312structure from one of the 313.Fn procstat_open_* 314functions and returns a dynamically allocated (sub-)set of active processes 315in the kernel filled in to array of 316.Vt kinfo_proc 317structures. 318The 319.Fa what 320and 321.Fa arg 322arguments constitute a filtering predicate as described in the 323.Xr kvm_getprocs 3 324function. 325The number of processes found is returned in the reference parameter 326.Fa cnt . 327The caller is responsible to free the allocated memory with a subsequent 328.Fn procstat_freeprocs 329function call. 330.Pp 331The 332.Fn procstat_getptlwpinfo 333function gets a pointer to the 334.Vt procstat 335structure from the 336.Fn procstat_open_core 337function and returns a dynamically allocated set of signals intercepted by a 338process in the process's core file. 339The number of processes found is returned in the reference parameter 340.Fa cnt . 341The caller is responsible to free the allocated memory with a subsequent 342.Fn procstat_freeptlwpinfo 343function call. 344.Pp 345The 346.Fn procstat_getargv 347function gets a pointer to the 348.Vt procstat 349structure from one of the 350.Fn procstat_open_* 351functions, a pointer to 352.Vt kinfo_proc 353structure from the array obtained from the 354.Fn procstat_getprocs 355function, and returns a null-terminated argument vector that corresponds to 356the command line arguments passed to the process. 357The 358.Fa nchr 359argument indicates the maximum number of characters, including null bytes, 360to use in building the strings. 361If this amount is exceeded, the string causing the overflow is truncated and 362the partial result is returned. 363This is handy for programs that print only a one line summary of a 364command and should not copy out large amounts of text only to ignore it. 365If 366.Fa nchr 367is zero, no limit is imposed and all argument strings are returned. 368The values of the returned argument vector refer the strings stored 369in the 370.Vt procstat 371internal buffer. 372A subsequent call of the function with the same 373.Vt procstat 374argument will reuse the buffer. 375To free the allocated memory 376.Fn procstat_freeargv 377function call can be used, or it will be released on 378.Fn procstat_close . 379.Pp 380The 381.Fn procstat_getenvv 382function is similar to 383.Fn procstat_getargv 384but returns the vector of environment strings. 385The caller may free the allocated memory with a subsequent 386.Fn procstat_freeenvv 387function call. 388.Pp 389The 390.Fn procstat_getauxv 391function gets a pointer to the 392.Vt procstat 393structure, a pointer to 394.Vt kinfo_proc 395structure, and returns the auxiliary vector as a dynamically allocated array of 396.Vt Elf_Auxinfo 397elements. 398The caller is responsible to free the allocated memory with a subsequent 399.Fn procstat_freeauxv 400function call. 401.Pp 402The 403.Fn procstat_getfiles 404function gets a pointer to the 405.Vt procstat 406structure initialized with one of the 407.Fn procstat_open_* 408functions, a pointer to 409.Vt kinfo_proc 410structure from the array obtained from the 411.Fn procstat_getprocs 412function, and returns a dynamically allocated linked list of filled in 413.Vt filestat_list 414structures using the STAILQ macros defined in 415.Xr queue 3 . 416The caller is responsible to free the allocated memory with a subsequent 417.Fn procstat_freefiles 418function call. 419.Pp 420The 421.Fn procstat_getgroups 422function gets a pointer to the 423.Vt procstat 424structure, a pointer to 425.Vt kinfo_proc 426structure, and returns the process groups as a dynamically allocated array of 427.Vt gid_t 428elements. 429The caller is responsible to free the allocated memory with a subsequent 430.Fn procstat_freegroups 431function call. 432.Pp 433The 434.Fn procstat_getkstack 435function gets a pointer to the 436.Vt procstat 437structure initialized with one of the 438.Fn procstat_open_* 439functions, a pointer to 440.Vt kinfo_proc 441structure, and returns kernel stacks of the process as a dynamically allocated 442array of 443.Vt kinfo_kstack 444structures. 445The caller is responsible to free the allocated memory with a subsequent 446.Fn procstat_freekstack 447function call. 448.Pp 449The 450.Fn procstat_getosrel 451function gets a pointer to the 452.Vt procstat 453structure, a pointer to 454.Vt kinfo_proc 455structure, and returns osrel date in the 3rd reference parameter. 456.Pp 457The 458.Fn procstat_getpathname 459function gets a pointer to the 460.Vt procstat 461structure, a pointer to 462.Vt kinfo_proc 463structure, and copies the path of the process executable to 464.Fa pathname 465buffer, limiting to 466.Fa maxlen 467characters. 468.Pp 469The 470.Fn procstat_getrlimit 471function gets a pointer to the 472.Vt procstat 473structure, a pointer to 474.Vt kinfo_proc 475structure, resource index 476.Fa which , 477and returns the actual resource limit in the 4th reference parameter. 478.Pp 479The 480.Fn procstat_getumask 481function gets a pointer to the 482.Vt procstat 483structure, a pointer to 484.Vt kinfo_proc 485structure, and returns the process umask in the 3rd reference parameter. 486.Pp 487The 488.Fn procstat_getvmmap 489function gets a pointer to the 490.Vt procstat 491structure initialized with one of the 492.Fn procstat_open_* 493functions, a pointer to 494.Vt kinfo_proc 495structure, and returns VM layout of the process as a dynamically allocated 496array of 497.Vt kinfo_vmentry 498structures. 499The caller is responsible to free the allocated memory with a subsequent 500.Fn procstat_freevmmap 501function call. 502.Pp 503The 504.Fn procstat_getadvlock 505function returns a dynamically allocated list of 506.Va struct advlock 507structures, providing a snapshot of the currently 508acquired advisory locks in the system. 509Both locally acquired POSIX ( 510.Xr fcntl 2 ) 511and BSD-style ( 512.Xr flock 2 ) 513locks are reported, as well as locks established by remote file 514system protocols. 515For each lock, unique identifiers for the locked file and its mount point 516are guaranteed to be provided. 517If a path for the locked file can be reconstructed, it is provided as well. 518The returned list must be freed with the 519.Fn procstat_freeadvlock 520function. 521.Pp 522The 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 528and 529.Fn procstat_get_vnode_info 530functions are used to retrieve information about pipes, pseudo-terminals, 531semaphores, shared memory objects, 532sockets, and vnodes, respectively. 533Each of them have a similar interface API. 534The 535.Fa procstat 536argument is a pointer obtained from one of 537.Fn procstat_open_* 538functions. 539The 540.Ft filestat Fa fst 541argument is an element of STAILQ linked list as obtained from the 542.Fn procstat_getfiles 543function. 544The 545.Ft filestat 546structure contains a 547.Fa fs_type 548field that specifies a file type and a corresponding function to be 549called among the 550.Nm procstat_get_*_info 551function family. 552The actual object is returned in the 3rd reference parameter. 553The 554.Fa errbuf 555argument 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 588The 589.Nm libprocstat 590library appeared in 591.Fx 9.0 . 592.Sh AUTHORS 593.An -nosplit 594The 595.Nm libprocstat 596library was written by 597.An Stanislav Sedov Aq Mt stas@FreeBSD.org . 598.Pp 599This manual page was written by 600.An Sergey Kandaurov Aq Mt pluknet@FreeBSD.org . 601