.\" Copyright (c) 2011 Sergey Kandaurov .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 1, 2012 .Dt LIBPROCSTAT 3 .Os .Sh NAME .Nm procstat_open_kvm , .Nm procstat_open_sysctl , .Nm procstat_close , .Nm procstat_getfiles , .Nm procstat_getprocs , .Nm procstat_freefiles , .Nm procstat_freeprocs , .Nm procstat_get_pipe_info , .Nm procstat_get_pts_info , .Nm procstat_get_shm_info , .Nm procstat_get_socket_info , .Nm procstat_get_vnode_info .Nd library interface for file and process information retrieval .Sh LIBRARY .Lb libprocstat .Sh SYNOPSIS .In sys/param.h .In sys/queue.h .In libprocstat.h .Ft void .Fn procstat_close "struct procstat *procstat" .Ft void .Fo procstat_freefiles .Fa "struct procstat *procstat" .Fa "struct filestat_list *head" .Fc .Ft void .Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p" .Ft int .Fo procstat_get_pipe_info .Fa "struct procstat *procstat" .Fa "struct filestat *fst" .Fa "struct pipestat *pipe" .Fa "char *errbuf" .Fc .Ft int .Fo procstat_get_pts_info .Fa "struct procstat *procstat" .Fa "struct filestat *fst" .Fa "struct ptsstat *pts" .Fa "char *errbuf" .Fc .Ft int .Fo procstat_get_shm_info .Fa "struct procstat *procstat" .Fa "struct filestat *fst" .Fa "struct shmstat *shm" .Fa "char *errbuf" .Fc .Ft int .Fo procstat_get_socket_info .Fa "struct procstat *procstat" .Fa "struct filestat *fst" .Fa "struct sockstat *sock" .Fa "char *errbuf" .Fc .Ft int .Fo procstat_get_vnode_info .Fa "struct procstat *procstat" .Fa "struct filestat *fst" .Fa "struct vnstat *vn" .Fa "char *errbuf" .Fc .Ft "struct filestat_list *" .Fo procstat_getfiles .Fa "struct procstat *procstat" .Fa "struct kinfo_proc *kp" .Fa "int mmapped" .Fc .Ft "struct kinfo_proc *" .Fo procstat_getprocs .Fa "struct procstat *procstat" .Fa "int what" .Fa "int arg" .Fa "unsigned int *count" .Fc .Ft "struct procstat *" .Fn procstat_open_kvm "const char *nlistf" "const char *memf" .Ft "struct procstat *" .Fn procstat_open_sysctl void .Sh DESCRIPTION The .Nm libprocstat library contains the API for runtime file and process information retrieval from the running kernel via the .Xr sysctl 3 library backend, and for post-mortem analysis via the .Xr kvm 3 library backend. .Pp The .Fn procstat_open_kvm and .Fn procstat_open_sysctl functions use the .Xr kvm 3 or .Xr sysctl 3 library routines, respectively, to access kernel state information used to retrieve processes and files states. The .Fa nlistf argument is the executable image of the kernel being examined. If this argument is .Dv NULL , the currently running kernel is assumed. The .Fa memf argument is the kernel memory device file. If this argument is .Dv NULL , then .Pa /dev/mem is assumed. See .Xr kvm_open 3 for more details. Both functions dynamically allocate and return a .Vt procstat structure pointer used in the rest of the .Nm libprocstat library routines until the corresponding .Fn procstat_close call that cleans up the resources allocated by the .Fn procstat_open_* functions. .Pp The .Fn procstat_getprocs function gets a pointer to the .Vt procstat structure from one of the .Fn procstat_open_* functions and returns a dynamically allocated (sub-)set of active processes in the kernel filled in to array of .Vt kinfo_proc structures. The .Fa what and .Fa arg arguments constitute a filtering predicate as described in the .Xr kvm_getprocs 3 function. The number of processes found is returned in the reference parameter .Fa cnt . The caller is responsible to free the allocated memory with a subsequent .Fn procstat_freeprocs function call. .Pp The .Fn procstat_getfiles function gets a pointer to the .Vt procstat structure initialized with one of the .Fn procstat_open_* functions, a pointer to .Vt kinfo_proc structure from the array obtained from the .Fn kvm_getprocs function, and returns a dynamically allocated linked list of filled in .Vt filestat_list structures using the STAILQ macros defined in .Xr queue 3 . The caller is responsible to free the allocated memory with a subsequent .Fn procstat_freefiles function call. .Pp The .Fn procstat_get_pipe_info , .Fn procstat_get_pts_info , .Fn procstat_get_shm_info , .Fn procstat_get_socket_info and .Fn procstat_get_vnode_info functions are used to retrieve information about pipes, pseudo-terminals, shared memory objects, sockets, and vnodes, respectively. Each of them have a similar interface API. The .Fa procstat argument is a pointer obtained from one of .Fn procstat_open_* functions. The .Ft filestat Fa fst argument is an element of STAILQ linked list as obtained from the .Fn procstat_getfiles function. The .Ft filestat structure contains a .Fa fs_type field that specifies a file type and a corresponding function to be called among the .Nm procstat_get_*_info function family. The actual object is returned in the 3rd reference parameter. The .Fa errbuf argument indicates an actual error message in case of failure. .Pp .Bl -tag -width 20n -compact -offset indent .It Li PS_FST_TYPE_FIFO .Nm procstat_get_vnode_info .It Li PS_FST_TYPE_VNODE .Nm procstat_get_vnode_info .It Li PS_FST_TYPE_SOCKET .Nm procstat_get_socket_info .It Li PS_FST_TYPE_PIPE .Nm procstat_get_pipe_info .It Li PS_FST_TYPE_PTS .Nm procstat_get_pts_info .It Li PS_FST_TYPE_SHM .Nm procstat_get_shm_info .El .Sh SEE ALSO .Xr fstat 1 , .Xr fuser 1 , .Xr pipe 2 , .Xr shm_open 2 , .Xr socket 2 , .Xr kvm 3 , .Xr queue 3 , .Xr sysctl 3 , .Xr pts 4 , .Xr vnode 9 .Sh HISTORY The .Nm libprocstat library appeared in .Fx 9.0 . .Sh AUTHORS .An -nosplit The .Nm libprocstat library was written by .An Stanislav Sedov Aq stas@FreeBSD.org . .Pp This manual page was written by .An Sergey Kandaurov Aq pluknet@FreeBSD.org .