Date: Tue, 12 Jul 2011 13:46:13 +0000 (UTC) From: Sergey Kandaurov <pluknet@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r223953 - in head: gnu/usr.bin/groff/tmac lib/libprocstat Message-ID: <201107121346.p6CDkDfp041322@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: pluknet Date: Tue Jul 12 13:46:13 2011 New Revision: 223953 URL: http://svn.freebsd.org/changeset/base/223953 Log: Provide a simple manual page for libprocstat(3). Reviewed by: jilles, gjb Added: head/lib/libprocstat/libprocstat.3 (contents, props changed) Modified: head/gnu/usr.bin/groff/tmac/mdoc.local head/lib/libprocstat/Makefile Modified: head/gnu/usr.bin/groff/tmac/mdoc.local ============================================================================== --- head/gnu/usr.bin/groff/tmac/mdoc.local Tue Jul 12 13:28:39 2011 (r223952) +++ head/gnu/usr.bin/groff/tmac/mdoc.local Tue Jul 12 13:46:13 2011 (r223953) @@ -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) Modified: head/lib/libprocstat/Makefile ============================================================================== --- head/lib/libprocstat/Makefile Tue Jul 12 13:28:39 2011 (r223952) +++ head/lib/libprocstat/Makefile Tue Jul 12 13:46:13 2011 (r223953) @@ -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 Added: head/lib/libprocstat/libprocstat.3 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/lib/libprocstat/libprocstat.3 Tue Jul 12 13:46:13 2011 (r223953) @@ -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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201107121346.p6CDkDfp041322>