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 1, 2012 28.Dt LIBPROCSTAT 3 29.Os 30.Sh NAME 31.Nm procstat_open_kvm , 32.Nm procstat_open_sysctl , 33.Nm procstat_close , 34.Nm procstat_getfiles , 35.Nm procstat_getprocs , 36.Nm procstat_freefiles , 37.Nm procstat_freeprocs , 38.Nm procstat_get_pipe_info , 39.Nm procstat_get_pts_info , 40.Nm procstat_get_shm_info , 41.Nm procstat_get_socket_info , 42.Nm procstat_get_vnode_info 43.Nd library interface for file and process information retrieval 44.Sh LIBRARY 45.Lb libprocstat 46.Sh SYNOPSIS 47.In sys/param.h 48.In sys/queue.h 49.In libprocstat.h 50.Ft void 51.Fn procstat_close "struct procstat *procstat" 52.Ft void 53.Fo procstat_freefiles 54.Fa "struct procstat *procstat" 55.Fa "struct filestat_list *head" 56.Fc 57.Ft void 58.Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p" 59.Ft int 60.Fo procstat_get_pipe_info 61.Fa "struct procstat *procstat" 62.Fa "struct filestat *fst" 63.Fa "struct pipestat *pipe" 64.Fa "char *errbuf" 65.Fc 66.Ft int 67.Fo procstat_get_pts_info 68.Fa "struct procstat *procstat" 69.Fa "struct filestat *fst" 70.Fa "struct ptsstat *pts" 71.Fa "char *errbuf" 72.Fc 73.Ft int 74.Fo procstat_get_shm_info 75.Fa "struct procstat *procstat" 76.Fa "struct filestat *fst" 77.Fa "struct shmstat *shm" 78.Fa "char *errbuf" 79.Fc 80.Ft int 81.Fo procstat_get_socket_info 82.Fa "struct procstat *procstat" 83.Fa "struct filestat *fst" 84.Fa "struct sockstat *sock" 85.Fa "char *errbuf" 86.Fc 87.Ft int 88.Fo procstat_get_vnode_info 89.Fa "struct procstat *procstat" 90.Fa "struct filestat *fst" 91.Fa "struct vnstat *vn" 92.Fa "char *errbuf" 93.Fc 94.Ft "struct filestat_list *" 95.Fo procstat_getfiles 96.Fa "struct procstat *procstat" 97.Fa "struct kinfo_proc *kp" 98.Fa "int mmapped" 99.Fc 100.Ft "struct kinfo_proc *" 101.Fo procstat_getprocs 102.Fa "struct procstat *procstat" 103.Fa "int what" 104.Fa "int arg" 105.Fa "unsigned int *count" 106.Fc 107.Ft "struct procstat *" 108.Fn procstat_open_kvm "const char *nlistf" "const char *memf" 109.Ft "struct procstat *" 110.Fn procstat_open_sysctl void 111.Sh DESCRIPTION 112The 113.Nm libprocstat 114library contains the API for runtime file and process information 115retrieval from the running kernel via the 116.Xr sysctl 3 117library backend, and for post-mortem analysis via the 118.Xr kvm 3 119library backend. 120.Pp 121The 122.Fn procstat_open_kvm 123and 124.Fn procstat_open_sysctl 125functions use the 126.Xr kvm 3 127or 128.Xr sysctl 3 129library routines, respectively, to access kernel state information 130used to retrieve processes and files states. 131The 132.Fa nlistf 133argument is the executable image of the kernel being examined. 134If this argument is 135.Dv NULL , 136the currently running kernel is assumed. 137The 138.Fa memf 139argument is the kernel memory device file. 140If this argument is 141.Dv NULL , 142then 143.Pa /dev/mem 144is assumed. 145See 146.Xr kvm_open 3 147for more details. 148Both functions dynamically allocate and return a 149.Vt procstat 150structure pointer used in the rest of the 151.Nm libprocstat 152library routines until the corresponding 153.Fn procstat_close 154call that cleans up the resources allocated by the 155.Fn procstat_open_* 156functions. 157.Pp 158The 159.Fn procstat_getprocs 160function gets a pointer to the 161.Vt procstat 162structure from one of the 163.Fn procstat_open_* 164functions and returns a dynamically allocated (sub-)set of active processes 165in the kernel filled in to array of 166.Vt kinfo_proc 167structures. 168The 169.Fa what 170and 171.Fa arg 172arguments constitute a filtering predicate as described in the 173.Xr kvm_getprocs 3 174function. 175The number of processes found is returned in the reference parameter 176.Fa cnt . 177The caller is responsible to free the allocated memory with a subsequent 178.Fn procstat_freeprocs 179function call. 180.Pp 181The 182.Fn procstat_getfiles 183function gets a pointer to the 184.Vt procstat 185structure initialized with one of the 186.Fn procstat_open_* 187functions, a pointer to 188.Vt kinfo_proc 189structure from the array obtained from the 190.Fn kvm_getprocs 191function, and returns a dynamically allocated linked list of filled in 192.Vt filestat_list 193structures using the STAILQ macros defined in 194.Xr queue 3 . 195The caller is responsible to free the allocated memory with a subsequent 196.Fn procstat_freefiles 197function call. 198.Pp 199The 200.Fn procstat_get_pipe_info , 201.Fn procstat_get_pts_info , 202.Fn procstat_get_shm_info , 203.Fn procstat_get_socket_info 204and 205.Fn procstat_get_vnode_info 206functions are used to retrieve information about pipes, pseudo-terminals, 207shared memory objects, 208sockets, and vnodes, respectively. 209Each of them have a similar interface API. 210The 211.Fa procstat 212argument is a pointer obtained from one of 213.Fn procstat_open_* 214functions. 215The 216.Ft filestat Fa fst 217argument is an element of STAILQ linked list as obtained from the 218.Fn procstat_getfiles 219function. 220The 221.Ft filestat 222structure contains a 223.Fa fs_type 224field that specifies a file type and a corresponding function to be 225called among the 226.Nm procstat_get_*_info 227function family. 228The actual object is returned in the 3rd reference parameter. 229The 230.Fa errbuf 231argument indicates an actual error message in case of failure. 232.Pp 233.Bl -tag -width 20n -compact -offset indent 234.It Li PS_FST_TYPE_FIFO 235.Nm procstat_get_vnode_info 236.It Li PS_FST_TYPE_VNODE 237.Nm procstat_get_vnode_info 238.It Li PS_FST_TYPE_SOCKET 239.Nm procstat_get_socket_info 240.It Li PS_FST_TYPE_PIPE 241.Nm procstat_get_pipe_info 242.It Li PS_FST_TYPE_PTS 243.Nm procstat_get_pts_info 244.It Li PS_FST_TYPE_SHM 245.Nm procstat_get_shm_info 246.El 247.Sh SEE ALSO 248.Xr fstat 1 , 249.Xr fuser 1 , 250.Xr pipe 2 , 251.Xr shm_open 2 , 252.Xr socket 2 , 253.Xr kvm 3 , 254.Xr queue 3 , 255.Xr sysctl 3 , 256.Xr pts 4 , 257.Xr vnode 9 258.Sh HISTORY 259The 260.Nm libprocstat 261library appeared in 262.Fx 9.0 . 263.Sh AUTHORS 264.An -nosplit 265The 266.Nm libprocstat 267library was written by 268.An Stanislav Sedov Aq stas@FreeBSD.org . 269.Pp 270This manual page was written by 271.An Sergey Kandaurov Aq pluknet@FreeBSD.org . 272