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