docs: adding openproc(), readproc() and readproctab() man

proc/Makefile.am

@@ -21,6 +21,11 @@ libprocps_la_LDFLAGS = \
 	-no-undefined \
 	-Wl,--version-script=$(top_srcdir)/proc/libprocps.sym
 
+dist_man_MANS = \
+	openproc.3 \
+	readproc.3 \
+	readproctab.3
+
 EXTRA_DIST = libprocps.sym
 
 pkgconfigdir = $(libdir)/pkgconfig

proc/openproc.3

@@ -0,0 +1,160 @@
+.\" This file describes the readproc interface to the /proc filesystem
+.\"
+.\" Copyright 1996 Helmut Geyer <Helmut.Geyer@iwr.uni-heidelberg.de>
+.\" Copyright 2014 Jaromir Capik <jcapik@redhat.com>
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.TH OPENPROC 3 "14 July 2014" "Linux Manpage" "Linux Programmer's Manual"
+.SH NAME
+openproc, closeproc  \- initialize process information from /proc/
+.SH SYNOPSIS
+.B #include <proc/readproc.h>
+.sp
+.BI "PROCTAB* openproc (int " flags ", ... );"
+.br
+.BI "void closeproc (PROCTAB* " PT ");"
+
+.SH SYNOPSIS
+
+The
+.B openproc
+function initializes a PROCTAB structure which can be used by iterated
+readproc calls to get information on current processes. Depending on
+.IR flags ,
+openproc may need a second argument or a second and third argument
+(see below).
+
+.B closeproc
+closes all files opened by
+.B openproc
+and deallocates the memory allocated by
+.B openproc.
+ 
+The PROCTAB structure is defined in
+.I <proc/readproc.h>
+.RE
+
+.SH "RETURN VALUE"
+.B openproc
+returns a pointer to a PROCTAB structure, or NULL if an error
+occurs. This usually means that
+.I /proc
+cannot be read by the process.
+
+.SH "FLAGS"
+
+The behaviour of
+.B openproc
+is controlled by the following set of flags, which may be ORed
+together. There are three
+different kinds of flags. The first group of flags determins which
+information gets read from /proc/#pid for each process. The second
+group of flags (of which only one can be enacted for a opendir call)
+restricts which processes information is read for by providing a list
+of criteria. The third group of flags restricts this as well, but
+doesn't need arguments. These may be used together again.
+
+.TP 0.5i
+.B "PROC_FILLMEM"
+read information from
+.IR /proc/#pid/statm
+.TP 0.5i
+.B "PROC_FILLCOM"
+allocate
+.I cmdline
+part of
+.I proc_t
+and read information from
+.IR /proc/#pid/cmdline
+.TP 0.5i
+.B "PROC_FILLENV"
+allocate
+.I environ
+part of
+.I proc_t
+and read information from
+.IR /proc/#pid/environ
+.TP 0.5i
+.B "PROC_FILLUSR"
+resolve user ids to names via
+.IR /etc/passwd
+.TP 0.5i
+.B "PROC_FILLGRP"
+resolve group ids to names via
+.IR /etc/group
+.TP 0.5i
+.B "PROC_FILLSTATUS"
+read information from
+.IR  /proc/#pid/status
+.TP 0.5i
+.B "PROC_FILLSTAT"
+read information from
+.IR /proc/#pid/stat
+.TP 0.5i
+.B "PROC_FILLWCHAN"
+do WCHAN lookup
+.TP 0.5i
+.B "PROC_FILLARG"
+equivalent to PROC_FILLCOM
+.TP 0.5i
+.B "PROC_FILLCGROUP"
+alloc and fill in cgroup
+.TP 0.5i
+.B "PROC_FILLSUPGRP"
+resolve supplementary group id -> group name
+.TP 0.5i
+.B "PROC_FILLOOM"
+fill in proc_t oom_score and oom_adj
+.TP 0.5i
+.B "PROC_FILLNS"
+fill in proc_t namespace information
+.TP 0.5i
+.B "PROC_LOOSE_TASKS"
+threat threads as if they were processes
+.TP 0.5i
+.BR PROC_PID " (2nd argument "pid_t* " \fIpidlist\fR)
+lookup only processes whose pid is contained in
+.IR pidlist
+(the list is terminated with 0)
+.TP 0.5i
+.BR PROC_UID " (arguments "uid_t* " \fIuidlist\fB, int \fIn\fR)
+lookup only processes whose user id is contained in
+.IR uidlist
+(where
+.I n
+is the number of uids contained in the list)
+.TP 0.5i
+.B "PROC_EDITCGRPCVT"
+edit cgroup as single vector
+.TP 0.5i
+.B "PROC_EDITCMDLCVT"
+edit cmdline as single vector
+.TP 0.5i
+.B "PROC_EDITENVRCVT"
+edit environ as single vector
+
+.SH NOTE
+Only one of the flags needing additional arguments
+.RB ( "PROC_{PID,UID}" )
+may be used at a time.
+
+.SH "SEE ALSO"
+.BR readproc (3),
+.BR readproctab (3),
+.BR /proc/ ,
+.BR /usr/include/proc/readproc.h ,
+.SH "REPORTING BUGS"
+Please send bug reports to
+.UR procps@freelists.org
+.UE

proc/readproc.3

@@ -0,0 +1,77 @@
+.\" This file describes the readproc interface to the /proc filesystem
+.\"
+.\" Copyright 1996 Helmut Geyer <Helmut.Geyer@iwr.uni-heidelberg.de>
+.\" Copyright 2014 Jaromir Capik <jcapik@redhat.com>
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.TH READPROC 3 "14 July 2014" "Linux Manpage" "Linux Programmer's Manual"
+.SH NAME
+readproc, freeproc  \- read information from next /proc/## entry
+.SH SYNOPSIS
+.B #include <proc/readproc.h>
+.sp
+.BI "proc_t* readproc(PROCTAB *" PT ", proc_t *" return_buf ");"
+.br
+.BI "void freeproc(proc_t *" p ");"
+
+.SH DESCRIPTION
+
+.B readproc
+reads the information for the next process matching the criteria
+specified in
+.I PT
+and fills them into a
+.I proc_t
+structure. If
+.I return_buf
+is not NULL, it will use the struct pointed at by
+.IR return_buf .
+Otherwise it will allocate a new
+.I proc_t
+stucture and return a pointer to it.
+Note that (if so specified in
+.IR PT )
+readproc always allocates memory if it fills in the
+.IR environ " or " cmdline
+parts of
+.IR proc_t .
+
+.B freeproc
+frees all memory allocated for the
+.I proc_t
+struct
+.IR *p .
+
+The
+.I proc_t
+structure is defined in
+.IR <proc/readproc.h> ,
+please look there for a definition of all fields.
+
+.SH "RETURN VALUE"
+
+.B readproc
+returns a pointer to the next
+.I proc_t
+or NULL if there are no more processes left.
+
+.SH "SEE ALSO"
+.BR openproc (3),
+.BR readproctab (3),
+.BR /usr/include/proc/readproc.h ,
+.BR /proc/#pid/ ,
+.SH "REPORTING BUGS"
+Please send bug reports to
+.UR procps@freelists.org
+.UE

proc/readproctab.3

@@ -0,0 +1,57 @@
+.\" Copyright 1996 Helmut Geyer <Helmut.Geyer@iwr.uni-heidelberg.de>
+.\" Copyright 2014 Jaromir Capik <jcapik@redhat.com>
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.TH READPROCTAB 3 "14 July 2014" "Linux Manpage" "Linux Programmer's Manual"
+.SH NAME
+readproctab, freeproctab  \- read information for all current processes at once
+.SH SYNOPSIS
+.B #include <proc/readproc.h>
+.sp
+.BI "proc_t** readproctab(int " flags ", ... );"
+.br
+.BI "void freeproctab(proc_t **" p ");"
+
+.SH DESCRIPTION
+
+.B readproctab
+reads information on all processes matching the criteria from
+.IR flags ,
+allocating memory for everthing as needed. It returns a
+NULL-terminated list of
+.I proc_t
+pointers. For more information on the arguments of
+.BR readproctab ,
+see
+.BR openproc (3).
+
+.B freeproctab
+frees all memory allocated by
+.BR readproctab .
+
+The
+.I proc_t
+structure is defined in
+.IR <proc/readproc.h> ,
+please look there for a definition of all fields.
+
+.SH "SEE ALSO"
+.BR openproc (3),
+.BR readproc (3),
+.BR /proc/ ,
+.BR /usr/include/proc/readproc.h .
+.SH "REPORTING BUGS"
+Please send bug reports to
+.UR procps@freelists.org
+.UE