Provide a simple manual page for libprocstat(3).

Reviewed by:	jilles, gjb

gnu/usr.bin/groff/tmac/mdoc.local

@@ -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)

lib/libprocstat/Makefile

@@ -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

lib/libprocstat/libprocstat.3

@@ -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