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