emo/procps
1
0
Fork 0
Code Issues Pull Requests Packages Releases Activity

docs: update 'first cut' procps.3 with revised version

Browse Source 
This represents the 'second cut' at providing a shared
man page that supports more than one newlib interface.

In this approach, the following assumptions were made:

1) It is the kernel folks' job to document /proc files
not to mention fields within those files. And since we
don't yet know what some of those fields represent, we
shouldn't attempt to document any of those we do know.

2) Our header files serve as an essential reference in
successful exploitation of the new library interfaces.

3) The description represents functions as they appear
in the header itself making them immediately familiar.

4) Some inconsistencies among the interfaces have been
handled more visually rather than in a narrative form.

5) Armed with our header file users can easily see the
self-documenting enumerators & structures. There isn't
a need to explain them yet again in this man document.

6) Contrary to man guidelines, we shouldn't list error
codes. Simple generic guidance serves everyone better.

Reference(s):
. 05/19/20, procps.3 man page introduced
commit fc69028d37

Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit is contained in:
Jim Warner 2020-06-20 00:00:00 -05:00 committed by Craig Small
parent c934a3ab7a
commit eadb9db58f
1 changed files with 135 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

276
doc/procps.3
View File

@ -1,4 +1,4 @@
.\" (C) Copyright 2020 Craig Small <csmall@dropbear.xyz> .\" (C) Copyright 2020 Jim Warner <warnerjc@comcast.net>
.\" .\"
.\" %%%LICENSE_START(LGPL_2.1+) .\" %%%LICENSE_START(LGPL_2.1+)
.\" This manual is free software; you can redistribute it and/or .\" This manual is free software; you can redistribute it and/or
@ -16,164 +16,158 @@
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
.\" %%%LICENSE_END .\" %%%LICENSE_END
.\" .\"
.TH PROCPS_LINUX_VERSION 3 2020-0519 "libproc-2" .TH PROCPS_LINUX_VERSION 3 "June 2020" "libproc-2"
.\" Please adjust this date whenever revising the manpage. .\" Please adjust this date whenever revising the manpage.
.\" .\"
.nh
.SH NAME .SH NAME
procps \- API to the procps librayr procps \- API to access system level information in the /proc filesystem
.SH SYNOPSIS .SH SYNOPSIS
See XXXXX for what file to include Five distinct interfaces are represented in this synopsis and named after
the files they access in the /proc pseudo filesystem:
.BR diskstats ", " meminfo ", " slabinfo ", " stat " and " vmstat .
.BI "int PROCITEM_new(struct PROCITEM_info **" info ");" .nf
.RS +4
#include <procps/\fBnamed_interface\fR.h>
.BI "int PROCITEM_ref(struct PROCITEM_info *" info ");" .BI "int procps_new (struct info **" info );
.BI "int procps_ref (struct info *" info );
.BI "int procps_unref (struct info **" info );
.BI "int PROCITEM_unref(struct PROCITEM_info *" info ");" .BI "struct result *procps_get ("
.BI " struct info *" info ,
.RI "[ const char *" name ", ] \fBdiskstats\fR api only"
.BI " enum item " item );
.BI "struct diststats_result *procps_diststats_get(struct diststats_info *" info ", const char *" name ", enum diststats_item " item ");" .BI "struct stack *procps_select ("
.BI " struct info *" info ,
.RI "[ const char *" name ", ] \fBdiskstats\fR api only"
.BI " enum item *" items ,
.BI " int " numitems );
.BI "struct PROCITEM_result *procps_PROCITEM_get(struct PROCITEM_info *" info ", enum PROCITEM_item " item ");" .BI "struct reaped *procps_reap ("
(for all other PROCITEMs except diskstats) .BI " struct info *" info ,
.RI "[ enum reap_type " what ", ] \fBstat\fR api only"
.BI " enum item *" items ,
.BI " int " numitems );
.BI "struct PROCITEM_reap *procps_PROCITEM_reap(struct PROCITEM_info * " info ", enum PROCITEM_item *" items ", int " numitems ");" .BI "struct stack **procps_sort ("
(for PROCITEMs diskstats and slabinfo) .BI " struct info *" info ,
.BI " struct stack *" stacks[] ,
.BI " int " numstacked ,
.BI " enum item " sortitem ,
.BI " enum sort_order " order );
.RE
.fi
.BI "struct stat_reap *procps_stat_reap(struct stat_info * " info ", enum stat_item *" items ", int " numitems ");" The above functions and structures are generic but the specific
\fBnamed_interface\fR would also be part of any identifiers.
For example, `procps_new' would actually be `procps_\fBmeminfo\fR_new'
and `info' would really be `\fBdiskstats\fR_info', etc.
.BI "struct diststats_stack *procps_diststats_select(struct diststats_info *" info ", const char *" name ", enum diststats_item *" items ", int " numitems ");" The same \fBnamed_interface\fR is used in each header file name with
an appended `.h' suffix.
.BI "struct PROCITEM_stack *procps_PROCITEM_select(struct PROCITEM_info *" info ", enum PROCITEM_item *" items ", int " numitems ");"
(for all other PROCITEMs except diskstats)
.BI "struct PROCITEM_stack **procps_PROCITEM_sort(struct PROCITEM_info *" info ", struct PROCITEM_stack *" stacks "[], int " numstacked ", enum PROCITEM_item " sortitem ", enum PROCITEM_sort_order " order ");"
Link with \fI\-lprocps\fP. Link with \fI\-lprocps\fP.
.SH DESCRIPTION .SH DESCRIPTION
This manual page describes the common functions for obtaining information .SS Overview
about the following information types out of the Central to these interfaces is a simple `result'
.BR proc (5) structure reflecting an `item' plus its value (in a union
filesystem: with standard C language types as members).
.TP All `result' structures are automatically allocated and
.B diskstats provided by the library.
I/O statistics of the system disks.
.TP By specifying an array of `items', these structures can be
.B meminfo organized as a `stack', potentially yielding many results
Statistics on the usage of the memory system such as what is seen in with a single function call.
.BR free (1). Thus, a `stack' can be viewed as a variable length record
Does not have \fB_reap\fR or \fB_sort\fR functions. whose content and order is determined solely by the user.
.TP
.B slabinfo As part of each interface there are two unique items.
Statistics on the memory caches called slabs. The `noop' and `extra' items exist to hold user values.
.TP They are never set by the library, but the `extra'
.B stat result will be zeroed with each library interaction.
Generic system statistics such as CPU times and interrupts.
.TP The \fBnamed_interface\fR header file will be an essential
.B vmstat document during user program development.
Virtual memory statistics. There you will find available items, their return type
Does not have \fB_reap\fR or \fB_sort\fR functions. (the `result' struct member name) and the source for such values.
.PP Additional enumerators and structures are also documented there.
.BR procps_pids
man page describes similar functions for obtaining information about the .SS Usage
running processes on a system. The following would be a typical sequence of calls to
.PP these interfaces.
For each statistics type, substitute the name for \fBPROCITEM\fR as
seen in the \fBSYNOPSIS\fR. For example, to obtain a new \fBmeminfo\fR .nf
structure, you would call .RB "1. " procps_new()
.BI procps_meminfo_new( &info_ptr ); .RB "2. " procps_get() ", " procps_select() " or " procps_reap()
where \fIinfo_ptr\fR is a pointer to \fIstruct meminfo_info\fR. .RB "3. " procps_unref()
.SS Procps functions .fi
.TP
.B _new() Optionally, a user may choose to sort results returned from
The first call to the library should always be the relevant \fB_new\fR() function to obtain a \fIinfo\fR a \fBreap\fR function call.
structure that can be used for subsequent calls on the library. The function just allocates memory to the
structure and does not fetch any data. .SS Caveats
.TP The \fBnew\fR, \fBref\fR, \fBunref\fR, \fBget\fR and \fBselect\fR
.B _ref() functions are available in all five interfaces.
Increments an internal reference count within the given \fIinfo\fR structure.
.TP For the \fBnew\fR and \fBunref\fR functions, the address of an \fIinfo\fR
.B _unref() struct pointer must be supplied.
Decrements an internal reference count within the given \fIinfo\fR structure. With \fBnew\fR it must have been initialized to NULL.
If the count reaches zero then the structure is de-allocated. With \fBunref\fR it will be reset to NULL if the reference count reaches zero.
.TP
.B _get() In the case of the \fBdiskstats\fR interface, a \fIname\fR parameter
Get one piece of data as described by the enum. For diskstats the device also on the \fBget\fR and \fBselect\fR functions identifies a disk or
needs to be specified. For subsequent calls to this function, the data is only partition name
refeshed after one second from the previous call.
.TP The \fBdiskstats\fR, \fBslabinfo\fR and \fBstat\fR interfaces support
.B _reap() unpredictable variable outcomes.
Get multiple pieces of data as described in the array of enums. As such, they export a \fBreap\fR function to retrieve multiple `stacks'
.TP with a single invocation.
.B select()
ok reap versus select... Those same interfaces also offer a \fBsort\fR function whose
.TP parameters \fIstacks\fR and \fInumstacked\fR would normally be those
.B sort() returned in the `reaped' structure.
Sorts the already-fetched data in the given stacks based upon the given
item and sort order.
.SS Procps structures
The procps library uses a variety of structures to hold the extracted,
filtered or sorted information about the various aspects of the proc
filesystem.
.TP
.B info structure
The main structure used for the library. All information calls for a particular
information type will need this structure. For example, all functions for
vmstat will have a requirement for \fBstruct vmstat_info\fR.
.TP
.B item enum
The item enum is used to select a particular statistic from the information
type. This determines if you get the value for free memory versus used, or
system CPU time versus user CPU time.
.TP
.B result struct
Holds a single value for a particular statistic, including the \fBitem enum\fR
to tell what the value is for. As results can be of various types, the structure
uses a union.
.TP
.B stack structure
A stack is simply an array of \fBresult struct\fR. This is used to contain
multiple values in one place.
.TP
.B reap struct
Structure holding multiple \fBstack struct\fRs.
.SH RETURN VALUE .SH RETURN VALUE
The \fBprocps_PROCITEM_new\fR() functions return 0 on success and 1 on any failure. .SS Functions Returning an `int'
An error will be indicated by a negative number that
is always the inverse of some well known errno.h value.
Success is indicated by a zero return value.
However, the \fBref\fR and \fBunref\fR functions return
the current \fIinfo\fR structure reference count.
.SS Functions Returning an `address'
An error will be indicated by a NULL return pointer
with the reason found in the formal errno value.
Success is indicated by a pointer to the named structure.
.SH DEBUGGING
To aid in program development, there is a provision that can
help ensure `result' member references agree with library
expectations.
This feature can be activated through either of the following
methods and any discrepancies will be wrtten to \fBstderr\fR.
.IP 1) 3
Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure
options employed.
.IP 2) 3
Add #include <procps/xtra-procps-debug.h> to any program
\fIafter\fR the named interface includes.
.PP .PP
The \fBprocps_PROCITEM_ref\fR() and \fBprocps_PROCITEM_unref\fR() functions This verification feature incurs substantial overhead.
return the updated reference count on success and \fB-EINVAL\fR if given Therefore, it is important that it \fInot\fR be activated
invalid parameters. for a production/release build.
.PP
The \fBprocps_PROCITEM_result\fR() functions return a pointer to
.B struct PROCITEM_result
structure on success and \fBNULL\fR on failure.
.PP
The \fBprocps_PROCITEM_reap\fR() functions return a pointer to
.B struct PROCITEM_reap
structure on success and \fBNULL\fR on failure.
.PP
The \fBprocps_PROCITEM_select\fR() and \fBprocps_PROCITEM_sort\fR
functions return a pointer to
.B struct PROCITEM_stack
structure on success and \fBNULL\fR on failure.
.SH FILES
.TP
.I /proc/diskstats
I/O statistics for disks
.TP
.I /proc/meminfo
Memory useage statistics
.TP
.I /proc/slabinfo
Source of the statistics of slabinfo
.TP
.I /proc/vmstat
Source of the statistics for virtual memory.
.SH VERSIONS
All of the new API functions
first appeared in libproc-2 version 0.0.
.SH SEE ALSO .SH SEE ALSO
.BR procps_pids (3), .BR procps_misc (3)
.BR proc (5), .BR procps_pids (3)
.BR slabinfo (5). .BR proc (5).