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