build-sys: Rearrange the manual pages

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>

3 files changed, 0 insertions, 576 deletions

diff --git a/doc/procps.3 b/doc/procps.3
deleted file mode 100644
index 5be1517..0000000
--- a/doc/procps.3
+++ /dev/null
@@ -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).
diff --git a/doc/procps_misc.3 b/doc/procps_misc.3
deleted file mode 100644
index ae270d7..0000000
--- a/doc/procps_misc.3
+++ /dev/null
@@ -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).
diff --git a/doc/procps_pids.3 b/doc/procps_pids.3
deleted file mode 100644
index c7b874d..0000000
--- a/doc/procps_pids.3
+++ /dev/null
@@ -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).