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

build-sys: Rearrange the manual pages

Browse Source 
All man pages are found in ./man
man-po -> po-man

References:
 https://www.freelists.org/post/procps/Next-for-newlib,3

Signed-off-by: Craig Small <csmall@dropbear.xyz>
This commit is contained in:
Craig Small
2022-08-29 18:07:43 +10:00
parent 5fcf104cba
commit 8e889ae682
38 changed files with 16944 additions and 16944 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
doc/procps.3
View File

@@ -1,193 +0,0 @@
.\" (C) Copyright 2020-2022 Jim Warner <james.warner@comcast.net>
.\"
.\" %%%LICENSE_START(LGPL_2.1+)
.\" This manual is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
.\" %%%LICENSE_END
.\"
.TH PROCPS 3 "July 2022" "libproc-2"
.\" Please adjust this date whenever revising the manpage.
.\"
.nh
.SH NAME
procps \- API to access system level information in the /proc filesystem
.SH SYNOPSIS
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 .
.nf
.RS +4
#include <procps/\fBnamed_interface\fR.h>
.RI "int\fB procps_new \fR (struct info **" info );
.RI "int\fB procps_ref \fR (struct info *" info );
.RI "int\fB procps_unref\fR (struct info **" info );
.RB "struct result *" procps_get " ("
.RI " struct info *" info ,
.RI "[ const char *" name ", ] \fBdiskstats\fR api only"
.RI " enum item " item );
.RB "struct stack *" procps_select " ("
.RI " struct info *" info ,
.RI "[ const char *" name ", ] \fBdiskstats\fR api only"
.RI " enum item *" items ,
.RI " int " numitems );
.RB "struct reaped *" procps_reap " ("
.RI " struct info *" info ,
.RI "[ enum reap_type " what ", ] \fBstat\fR api only"
.RI " enum item *" items ,
.RI " int " numitems );
.RB "struct stack **" procps_sort " ("
.RI " struct info *" info ,
.RI " struct stack *" stacks [],
.RI " int " numstacked ,
.RI " enum item " sortitem ,
.RI " enum sort_order " order );
.fi
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.
The same \fBnamed_interface\fR is used in each header file name with
an appended `.h' suffix.
Link with \fI\-lproc-2\fP.
.SH DESCRIPTION
.SS Overview
Central to these interfaces is a simple `result'
structure reflecting an `item' plus its value (in a union
with standard C language types as members).
All `result' structures are automatically allocated and
provided by the library.
By specifying an array of `items', these structures can be
organized as a `stack', potentially yielding many results
with a single function call.
Thus, a `stack' can be viewed as a variable length record
whose content and order is determined solely by the user.
As part of each interface there are two unique enumerators.
The `noop' and `extra' items exist to hold user values.
They are never set by the library, but the `extra'
result will be zeroed with each library interaction.
The \fBnamed_interface\fR header file will be an essential
document during user program development.
There you will find available items, their return type
(the `result' struct member name) and the source for such values.
Additional enumerators and structures are also documented there.
.SS Usage
The following would be a typical sequence of calls to
these interfaces.
.nf
.RB "1. " procps_new()
.RB "2. " procps_get() ", " procps_select() " or " procps_reap()
.RB "3. " procps_unref()
.fi
The \fBget\fR function is used to retrieve a `result' structure for
a single `item'.
Alternatively, a \fBGET\fR macro is available when only the return
value is of interest.
The \fBselect\fR function can retrieve multiple `result' structures
in a single `stack'.
For unpredictable variable outcomes, the \fBdiskstats\fR, \fBslabinfo\fR
and \fBstat\fR interfaces export a \fBreap\fR function.
It is used to retrieve multiple `stacks' each containing multiple
`result' structures.
Optionally, a user may choose to \fBsort\fR those results.
To exploit any `stack', and access individual `result' structures,
a \fIrelative_enum\fR is required as shown in the \fBVAL\fR macro
defined in the header file.
Such values could be hard coded as: 0 through numitems-1.
However, this need is typically satisfied by creating your own
enumerators corresponding to the order of the `items' array.
.SS Caveats
The \fBnew\fR, \fBref\fR, \fBunref\fR, \fBget\fR and \fBselect\fR
functions are available in all five interfaces.
For the \fBnew\fR and \fBunref\fR functions, the address of an \fIinfo\fR
struct pointer must be supplied.
With \fBnew\fR it must have been initialized to NULL.
With \fBunref\fR it will be reset to NULL if the reference count reaches zero.
In the case of the \fBdiskstats\fR interface, a \fIname\fR parameter
on the \fBget\fR and \fBselect\fR functions identifies a disk or
partition name
For the \fBstat\fR interface, a \fIwhat\fR parameter on the \fBreap\fR
function identifies whether data for just CPUs or both CPUs and NUMA
nodes is to be gathered.
When using the \fBsort\fR function, the parameters \fIstacks\fR and
\fInumstacked\fR would normally be those returned in the `reaped'
structure.
.SH RETURN VALUE
.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.
It assumes that a supplied macro in the header file is
used to access the `result' value.
This feature can be activated through either of the following
methods and any discrepancies will be written 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
This verification feature incurs substantial overhead.
Therefore, it is important that it \fInot\fR be activated
for a production/release build.
.SH SEE ALSO
.BR procps_misc (3),
.BR procps_pids (3),
.BR proc (5).

165
doc/procps_misc.3
View File

@@ -1,165 +0,0 @@
.\" (C) Copyright 2020 Craig Small <csmall@dropbear.xyz>
.\" (C) Copyright 2021-2022 Jim Warner <james.warner@comcast.net>
.\"
.\" %%%LICENSE_START(LGPL_2.1+)
.\" This manual is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
.\" %%%LICENSE_END
.\"
.TH PROCPS_MISC 3 "July 2022" "libproc-2"
.\" Please adjust this date whenever revising the manpage.
.\"
.nh
.SH NAME
procps_misc \- API for miscellaneous information in the /proc filesystem
.SH SYNOPSIS
.nf
.B #include <procps/misc.h>
.PP
Platform Particulars
.RS 4
.PP
.RB "long " procps_cpu_count " (void);
.RB "long " procps_hertz_get " (void);
.RB "unsigned int " procps_pid_length " (void);
.RB "int " procps_linux_version " (void);
.RE
.PP
Runtime Particulars
.PP
.RS 4
.RI "int \fB procps_loadavg\fR (double *" av1 ", double *" av5 ", double *" av15 ");"
.RI "int \fB procps_uptime\fR (double *" uptime_secs ", double *" idle_secs ");"
.RB "char *" procps_uptime_sprint " (void);"
.RB "char *" procps_uptime_sprint_short " (void);"
.RE
.PP
Namespace Particulars
.PP
.RS 4
.RI "int \fB procps_ns_get_id\fR (const char *" name ");"
.RI "const char\fB *procps_ns_get_name\fR (int " id ");"
.RI "int \fB procps_ns_read_pid\fR (int " pid ", struct procps_ns *" nsp ");"
.RE
Link with \fI\-lproc-2\fP.
.SH DESCRIPTION
.BR procps_cpu_count ()
returns the number of CPUs that are currently online as
.BI sysconf( _SC_NPROCESSORS_ONLY )
or an assumed \fI1\fR.
.BR procps_hertz_get ()
returns the number of clock ticks per second as
.BI sysconf( _SC_CLK_TCK )
or an assumed \fI100\fR.
Dividing tics by this value yields seconds.
.BR procps_pid_length ()
returns the maximum string length for a PID on the system. For example, if the largest
possible PID value on was 123, then the length would be 3. If the file
\fI/proc/sys/kernel/pid_max\fR is unreadable, the value is assumed to be \fI5\fR.
.BR procps_linux_version ()
returns the current Linux version as an encoded integer. On non-Linux systems that
have an emulated proc filesystem this function returns the version of the
Linux emulation instead.
The version consists of three positive integers representing the major,
minor and patch levels.
The following macros are provided for encoding a given Linux version or
separating out the components of the current version.
.RS 4
.PP
LINUX_VERSION(\ major\ ,\ minor\ ,\ patch\ )
.PP
LINUX_VERSION_MAJOR(\ ver\ )
.PP
LINUX_VERSION_MINOR(\ ver\ )
.PP
LINUX_VERSION_PATCH(\ ver\ )
.RE
.BR procps_loadavg ()
fetches the system load average and puts the 1, 5 and 15 minute averages into
location(s) specified by any pointer which is not \fINULL\fR.
.BR procps_uptime ()
returns uptime and/or idle seconds into location(s) specified by any pointer
which is not \fINULL\fR.
The \fBsprint\fR varieties return a human-readable string in one of two forms.
.RS 4
.PP
HH:MM:SS up HH:MM, # users, load average: 1, 5, 15 MM averages
.PP
up HH, MM
.RE
.BR procps_ns_get_id ()
returns the integer id (enum namespace_type) of the namespace for the given namespace \fIname\fR.
.BR procps_ns_get_name ()
returns the name of the namespace for the given \fIid\fR (enum namespace_type).
.BR procps_ns_read_pid ()
returns the inodes for the namespaces of the given process in the
procps_ns structure pointed to by \fInsp\fR.
Those inodes will appear in the order proscribed by enum namespace_type.
.PP
.RS 4
.nf
enum namespace_type {
PROCPS_NS_CGROUP,
PROCPS_NS_IPC,
PROCPS_NS_MNT,
PROCPS_NS_NET,
PROCPS_NS_PID,
PROCPS_NS_TIME,
PROCPS_NS_USER,
PROCPS_NS_UTS
};
.fi
.RE
.SH RETURN VALUE
.SS Functions Returning an `int' or `long'
An error will be indicated by a negative number that
is always the inverse of some well known errno.h value.
.SS Functions Returning an `address'
An error will be indicated by a NULL return pointer
with the reason found in the formal errno value.
.SH FILES
.TP
.I /proc/loadavg
The raw values for load average.
.TP
.I /proc/sys/kernel/osrelease
Contains the release version of the Linux kernel or proc filesystem.
.TP
.I /proc/sys/kernel/pid_max
Contains the value at which PIDs wrap around, one greater than the maximum PID value.
.TP
.I /proc/uptime
The raw values for uptime and idle time.
.TP
.IB /proc/<PID>/ns
contains the set of namespaces for a particular \fBPID\fR.
.SH SEE ALSO
.BR procps (3),
.BR procps_pids (3),
.BR proc (5).

218
doc/procps_pids.3
View File

@@ -1,218 +0,0 @@
.\" (C) Copyright 2020-2022 Jim Warner <james.warner@comcast.net>
.\"
.\" %%%LICENSE_START(LGPL_2.1+)
.\" This manual is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
.\" %%%LICENSE_END
.\"
.TH PROCPS_PIDS 3 "July 2022" "libproc-2"
.\" Please adjust this date whenever revising the manpage.
.\"
.nh
.SH NAME
procps_pids \- API to access process information in the /proc filesystem
.SH SYNOPSIS
.nf
#include <procps/pids.h>
.RI "int\fB procps_pids_new \fR (struct pids_info **" info ", enum pids_item *" items ", int " numitems );
.RI "int\fB procps_pids_ref \fR (struct pids_info *" info );
.RI "int\fB procps_pids_unref\fR (struct pids_info **" info );
.RB "struct pids_stack *" procps_pids_get " ("
.RI " struct pids_info *" info ,
.RI " enum pids_fetch_type " which );
.RB "struct pids_fetch *" procps_pids_reap " ("
.RI " struct pids_info *" info ,
.RI " enum pids_fetch_type " which );
.RB "struct pids_fetch *" procps_pids_select " ("
.RI " struct pids_info *" info ,
.RI " unsigned *" these ,
.RI " int " numthese ,
.RI " enum pids_select_type " which );
.RB "struct pids_stack **" procps_pids_sort " ("
.RI " struct pids_info *" info ,
.RI " struct pids_stack *" stacks [],
.RI " int " numstacked ,
.RI " enum pids_item " sortitem ,
.RI " enum pids_sort_order " order );
.RB "int " procps_pids_reset " ("
.RI " struct pids_info *" info ,
.RI " enum pids_item *" newitems ,
.RI " int " newnumitems );
.RB "struct pids_stack *" fatal_proc_unmounted " ("
.RI " struct pids_info *" info ,
.RI " int " return_self );
.fi
Link with \fI\-lproc-2\fP.
.SH DESCRIPTION
.SS Overview
Central to this interface is a simple `result'
structure reflecting an `item' plus its value (in a union
with standard C language types as members).
All `result' structures are automatically allocated and
provided by the library.
By specifying an array of `items', these structures can be
organized as a `stack', potentially yielding many results
with a single function call.
Thus, a `stack' can be viewed as a variable length record
whose content and order is determined solely by the user.
As part of this interface there are two unique enumerators.
The `noop' and `extra' items exist to hold user values.
They are never set by the library, but the `extra'
result will be zeroed with each library interaction.
The pids.h file will be an essential document during
user program development.
There you will find available items, their return type
(the `result' struct member name) and the source for such values.
Additional enumerators and structures are also documented there.
.SS Usage
The following would be a typical sequence of calls to
this interface.
.nf
.RB "1. " fatal_proc_unmounted()
.RB "2. " procps_pids_new()
.RB "3. " procps_pids_get() ", " procps_pids_reap() " or " procps_pids_select()
.RB "4. " procps_pids_unref()
.fi
The \fBget\fR function is an iterator for successive PIDs/TIDs,
returning those `items' previously identified via \fBnew\fR
or \fBreset\fR.
Two functions support unpredictable variable outcomes.
The \fBreap\fR function gathers data for all processes while
the \fBselect\fR function deals with specific PIDs or UIDs.
Both can return multiple `stacks' each containing multiple `result'
structures.
Optionally, a user may choose to \fBsort\fR such results
To exploit any `stack', and access individual `result' structures,
a \fIrelative_enum\fR is required as shown in the \fBVAL\fR macro
defined in the header file.
Such values could be hard coded as: 0 through numitems-1.
However, this need is typically satisfied by creating your own
enumerators corresponding to the order of the `items' array.
.SS Caveats
The <pids> API differs from others in that those items
of interest must be provided at \fBnew\fR or \fBreset\fR time,
the latter being unique to this API.
If either the \fIitems\fR or \fInumitems\fR parameter is zero at
\fBnew\fR time, then \fBreset\fR becomes mandatory before
issuing any other call.
For the \fBnew\fR and \fBunref\fR functions, the address of an \fIinfo\fR
struct pointer must be supplied.
With \fBnew\fR it must have been initialized to NULL.
With \fBunref\fR it will be reset to NULL if the reference count reaches zero.
The \fBget\fR and \fBreap\fR functions use the \fIwhich\fR parameter
to specify whether just tasks or both tasks and threads are to be fetched.
The \fBselect\fR function requires an array of PIDs or UIDs as
\fIthese\fR along with \fInumthese\fR to identify which processes
are to be fetched.
This function then operates as a subset of \fBreap\fR.
When using the \fBsort\fR function, the parameters \fIstacks\fR and
\fInumstacked\fR would normally be those returned in the `pids_fetch'
structure.
Lastly, a \fBfatal_proc_unmounted\fR function may be called before
any other function to ensure that the /proc/ directory is mounted.
As such, the \fIinfo\fR parameter would be NULL and the
\fIreturn_self\fR parameter zero.
If, however, some items are desired for the issuing program (a
\fIreturn_self\fR other than zero) then the \fBnew\fR call must precede
it to identify the \fIitems\fR and obtain the required \fIinfo\fR pointer.
.SH RETURN VALUE
.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.
However, if one survives the \fBfatal_proc_unmounted\fR call,
NULL is always returned when \fIreturn_self\fR is zero.
.SH DEBUGGING
To aid in program development, there are two procps-ng provisions
that can be exploited.
The first is a supplied file named `libproc.supp' which may be
useful when developing a \fImulti-threaded\fR application.
When used with the valgrind `--suppressions=' option, warnings
associated with the procps library itself are avoided.
Such warnings arise because the library handles heap based
allocations in a thread-safe manner.
A \fIsingle-threaded\fR application will not receive those warnings.
The second provision can help ensure `result' member references
agree with library expectations.
It assumes that a supplied macro in the header file is
used to access the `result' value.
This feature can be activated through either of the following
methods and any discrepancies will be written to \fBstderr\fR.
.IP 1) 3
Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure
options your project may employ.
.IP 2) 3
Add #include <procps/xtra-procps-debug.h> to any program
\fIafter\fR the #include <procps/pids.h>.
.PP
This verification feature incurs substantial overhead.
Therefore, it is important that it \fInot\fR be activated
for a production/release build.
.SH ENVIRONMENT VARIABLE(S)
The value set for the following is unimportant, just its presence.
.IP LIBPROC_HIDE_KERNEL
This will hide kernel threads which would otherwise be returned with a
.BR procps_pids_get ", " procps_pids_select " or " procps_pids_reap
call.
.SH SEE ALSO
.BR procps (3),
.BR procps_misc (3),
.BR proc (5).