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