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