From a74fb8fade82ad624703bb1bc7395cf0aacaeaa9 Mon Sep 17 00:00:00 2001 From: Jaromir Capik Date: Mon, 14 Jul 2014 16:07:23 +0200 Subject: [PATCH] docs: adding openproc(), readproc() and readproctab() man --- proc/Makefile.am | 5 ++ proc/openproc.3 | 160 +++++++++++++++++++++++++++++++++++++++++++++ proc/readproc.3 | 77 ++++++++++++++++++++++ proc/readproctab.3 | 57 ++++++++++++++++ 4 files changed, 299 insertions(+) create mode 100644 proc/openproc.3 create mode 100644 proc/readproc.3 create mode 100644 proc/readproctab.3 diff --git a/proc/Makefile.am b/proc/Makefile.am index 4f7d104b..45d8afcf 100644 --- a/proc/Makefile.am +++ b/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 diff --git a/proc/openproc.3 b/proc/openproc.3 new file mode 100644 index 00000000..6e371196 --- /dev/null +++ b/proc/openproc.3 @@ -0,0 +1,160 @@ +.\" This file describes the readproc interface to the /proc filesystem +.\" +.\" Copyright 1996 Helmut Geyer +.\" Copyright 2014 Jaromir Capik +.\" +.\" 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 +.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 +.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 diff --git a/proc/readproc.3 b/proc/readproc.3 new file mode 100644 index 00000000..fd548d1d --- /dev/null +++ b/proc/readproc.3 @@ -0,0 +1,77 @@ +.\" This file describes the readproc interface to the /proc filesystem +.\" +.\" Copyright 1996 Helmut Geyer +.\" Copyright 2014 Jaromir Capik +.\" +.\" 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 +.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 , +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 diff --git a/proc/readproctab.3 b/proc/readproctab.3 new file mode 100644 index 00000000..45712d81 --- /dev/null +++ b/proc/readproctab.3 @@ -0,0 +1,57 @@ +.\" Copyright 1996 Helmut Geyer +.\" Copyright 2014 Jaromir Capik +.\" +.\" 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 +.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 , +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 -- 2.40.0