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