d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Provide a simple manual page for libprocstat(3).

Browse Source 
Reviewed by:	jilles, gjb
This commit is contained in:
Sergey Kandaurov 2011-07-12 13:46:13 +00:00
parent a27d4bdc9f
commit c66ca7723b
3 changed files with 256 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
gnu/usr.bin/groff/tmac/mdoc.local
View File

@ -56,6 +56,7 @@
.ds doc-str-Lb-libnetgraph Netgraph User Library (libnetgraph, \-lnetgraph)
.ds doc-str-Lb-libpmc Performance Monitoring Counters Interface Library (libpmc, \-lpmc)
.ds doc-str-Lb-libproc Processor Monitoring and Analysis Library (libproc, \-lproc)
.ds doc-str-Lb-libprocstat Process and Files Information Retrieval (libprocstat, \-lprocstat)
.ds doc-str-Lb-librpcsec_gss RPC GSS-API Authentication Library (librpcsec_gss, \-lrpcsec_gss)
.ds doc-str-Lb-librpcsvc RPC Service Library (librpcsvc, \-lrpcsvc)
.ds doc-str-Lb-librtld_db Run-time Linker Debugging Library (librtld_db, \-lrtld_db)

6
lib/libprocstat/Makefile
View File

@ -15,13 +15,15 @@ SRCS= cd9660.c \
VERSION_DEF= ${.CURDIR}/Versions.def
SYMBOL_MAPS= ${.CURDIR}/Symbol.map
INCS= libprocstat.h
INCS= libprocstat.h
CFLAGS+= -I. -I${.CURDIR} -D_KVM_VNODE
SHLIB_MAJOR= 1
WITHOUT_MAN= yes
DPADD= ${LIBKVM} ${LIBUTIL}
LDADD= -lkvm -lutil
MAN= libprocstat.3
.if ${MK_NCP} != "no"
CFLAGS+= -DLIBPROCSTAT_NWFS
SRCS+= nwfs.c

251
lib/libprocstat/libprocstat.3 Normal file
View File

@ -0,0 +1,251 @@
.\" Copyright (c) 2011 Sergey Kandaurov <pluknet@FreeBSD.org>
.\" 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 July 12, 2011
.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_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_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_socket_info
and
.Fn procstat_get_vnode_info
functions are used to retrive information about pipes, pseudo-terminals,
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
.El
.Sh SEE ALSO
.Xr fstat 1 ,
.Xr fuser 1 ,
.Xr pipe 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 Stanislav Sedov Aq stas@FreeBSD.org