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