docs: adapt procps_misc.3 for new 'misc.h' header file

This commit adapts our man page for a new consolidated
'misc.h' header file. Along the way, some descriptions
were shortened, others lengthened and whitespace added
in an effort to (hopefully) improve readability a bit.

[ the #include subdirectory was also corrected while ]
[ rearranging & grouping functions into 3 categories ]

Signed-off-by: Jim Warner <james.warner@comcast.net>

1 files changed, 84 insertions, 134 deletions

diff --git a/doc/procps_misc.3 b/doc/procps_misc.3
index 2ebc178..3c36863 100644
--- a/doc/procps_misc.3
+++ b/doc/procps_misc.3
@@ -1,4 +1,5 @@
 .\" (C) Copyright 2020 Craig Small <csmall@dropbear.xyz>
+.\" (C) Copyright 2021 Jim Warner <warnerjc@comcast.net>
 .\"
 .\" %%%LICENSE_START(LGPL_2.1+)
 .\" This manual is free software; you can redistribute it and/or
@@ -16,169 +17,128 @@
 .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 .\" %%%LICENSE_END
 .\"
-.TH PROCPS_MISC 3 2020-12-21 "libproc-2"
+.TH PROCPS_MISC 3 "January 2021" "libproc-2"
 .\" Please adjust this date whenever revising the manpage.
 .\"
+.nh
 .SH NAME
-procps_misc \- API to system information in the /proc filesystem
+procps_misc \- API for miscellaneous information in the /proc filesystem
 .SH SYNOPSIS
 .nf
-.B #include <proc/namespace.h>
+.B #include <procps/misc.h>
 .PP
-.BI "int procps_ns_get_id(const char * " name ");"
-.BI "const char *procps_ns_get_name(const int " id ");"
-.BI "int procps_ns_read_pid(const int " pid ", struct procps_namespaces * " nsp ");"
-.PP
-.B #include <proc/sysinfo.h>
+Platform Particulars
+.RS 4
 .PP
-.B long procps_cpu_count(void);
-.B long procps_hertz_get(void);
-.BI "int procps_loadavg(double * " av1 ", double * " av5 ", double * " av15 ");"
-.B unsigned int procps_pid_length(void);
+.B "long         procps_cpu_count (void);"
+.B "long         procps_hertz_get (void);"
+.B "unsigned int procps_pid_length (void);"
+.B "int          procps_linux_version (void);"
+.RE
 .PP
-.B #include <proc/uptime.h>
+Runtime Particulars
 .PP
-.BI "int procps_uptime(double * " uptime_secs ", double * " idle_secs ");"
-.B char *procps_uptime_sprint(void);
-.B char *procps_uptime_sprint_short(void);
+.RS 4
+.BI "int    procps_loadavg (double * " av1 ", double * " av5 ", double * " av15 ");"
+.BI "int    procps_uptime (double * " uptime_secs ", double * " idle_secs ");"
+.B  "char * procps_uptime_sprint (void);"
+.B  "char * procps_uptime_sprint_short (void);"
+.RE
 .PP
-.B #include <proc/version.h>
+Namespace Particulars
 .PP
-.B int procps_linux_version(void);
+.RS 4
+.BI "int          procps_ns_get_id (const char * " name ");"
+.BI "const char * procps_ns_get_name (int " id ");"
+.BI "int          procps_ns_read_pid (int " pid ", struct procps_ns * " nsp ");"
+.RE
 .sp
 Link with \fI\-lprocps\fP.
-.SH DESCRIPTION
-This manual page describes the miscellaneous API functions of the
-.B procps
-library.
 
+.SH DESCRIPTION
 .BR procps_cpu_count ()
-returns the number of CPUs that are currently online. On most systems returns
-the value of
+returns the number of CPUs that are currently online as
 .BI sysconf( _SC_NPROCESSORS_ONLY )
-or assumed to be \fI1\fR.
+or an assumed \fI1\fR.
 
 .BR procps_hertz_get ()
-returns the number of clock ticks per second. On most systems returns the
-value of
+returns the number of clock ticks per second as
 .BI sysconf( _SC_CLK_TCK )
-or assumed to be \fI100\fR. Divide certain values returned in the
-in the \fI/proc\fR filesystem by this value to convert from ticks to seconds.
-
-.BR procps_loadavg ()
-Fetches the system load average and puts the 1, 5 and 15 minute averages into
-the locations in the given pointers. If the relevant pointer is \fINULL\fR then
-.BR procps_loadavg ()
-will not set that value.
+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
+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.
+\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 integer. On non-Linux systems that
+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 Linux version consists of a triple of positive integers representing
-the major, minor and patch versions of the kernel.
-.PP
-The library provides 3 macros for separating out the components.
+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
-.TP 1.2i
-.BR LINUX_VERSION_MAJOR (ver)
-Extract the major component from the given version integer.
-.TP
-.BR LINUX_VERSION_MINOR (ver)
-Extract the minor component from the given version integer.
-.TP
-.BR LINUX_VERSION_PATCH (ver)
-Extract the patch component from the given version integer.
-.RE
 .PP
-To encode a given Linux version, such as using it to compare against the current
-version, use the following macro:
-.TP
-.BI LINUX_VERSION( major , minor , patch )
+LINUX_VERSION(\ major\ ,\ minor\ ,\ patch\ )
 .PP
-.BR procps_uptime ()
-returns the uptime and idle time of the system. Either the
-\fIuptime_secs\fR or \fIidle_secs\fR can be \fBNULL\fR in which case that
-variable will not be returned.
-
-The \fBsprint\fR variety of the functions return a human-readable
-string of the uptime and other statistics.
-
-.BR procps_ns_get_id ()
-finds the ID of the namespace for the given namespace name.
-
-.BR procps_ns_get_name ()
-finds the name of the namespace of the given integer ID.
-
-.BR procps_ns_read_pid ()
-puts the inodes for the namespaces of the given process into
-the array pointed to \fInsp\fR.
-
-.SH RETURN VALUE
-For
-.BR procps_cpu_count "() , " procps_hertz_get "() and " procps_pid_length ()
-see the \fBDESCRIPTION\fR section for return values.
+LINUX_VERSION_MAJOR(\ ver\ )
+.PP
+LINUX_VERSION_MINOR(\ ver\ )
+.PP
+LINUX_VERSION_PATCH(\ ver\ )
+.RE
 
 .BR procps_loadavg ()
-returns 0 on success. On failure, it
-returns a negative integer to one of the values defined below.
-.TP
-.B -ERANGE
-Unable to parse the loadavg file.
-.PP
+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_linux_version ()
-returns a positive integer encoding the Linux version if successful. Otherwise
-returns a negative integer to one of the values defined below.
-.TP
-.B -EIO
-The procps library was unable to read the osrelease file.
-.TP
-.B -ERANGE
-Unable to parse the osrelease file.
+.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
-.BR procps_linux_version ()
-may also return any (negated) value that \fBfopen\fR() may set errno to.
+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 an integer for the namespace ID for the given name or
-.B \-EINVAL
-for an invalid input or an unknown namespace name.
+returns the integer id (enum namespace_type) of the namespace for the given namespace \fIname\fR.
 
 .BR procps_ns_get_name ()
-returns a statically allocated string containing the name of the
-namespace for the given ID. If the name is not found the function
-returns
-.B NULL
+returns the name of the namespace for the given \fIid\fR (enum namespace_type).
 
 .BR procps_ns_read_pid ()
-Returns 0 on success and \fB\-EINVAL\fR on failure.
-
-.BR procps_uptime ()
-returns 0 on success. On failure, it
-returns a negative integer to one of the values defined below.
-.TP
-.B -ERANGE
-Unable to parse the uptime file.
+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
-.BR procps_uptime ()
-may also return any (negated) value that \fBfopen\fR() may set errno to.
+.RS 4
+.nf
+enum namespace_type {
+    PROCPS_NS_IPC,
+    PROCPS_NS_MNT,
+    PROCPS_NS_NET,
+    PROCPS_NS_PID,
+    PROCPS_NS_USER,
+    PROCPS_NS_UTS
+};
+.fi
+.RE
+
 
-.BR procps_uptime_sprint_short ()
-return a string from a statically allocated buffer which displays uptime.
+.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.
 
-.BR procps_uptime_sprint ()
-also displays users and load average in the buffer. The formats are the
-same as
-.BR uptime (1)
-with and without the
-.B \-p
-option.
+.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
@@ -194,20 +154,10 @@ Contains the value at which PIDs wrap around, one greater than the maximum PID v
 .I /proc/uptime
 The raw values for uptime and idle time.
 .TP
-.IB /proc/ PID /ns
+.IB /proc/<PID>/ns
 contains the set of namespaces for a particular \fBPID\fR.
 
-.SH BUGS
-Due to the way the three numbers are encoded into a single integer,
-.BR procps_linux_version ()
-and the associated macros assume 255 for the maximum value for the
-minor and patch level and 32767 (hex 0x7fff) for the maximum value
-for the major version. In other words, when Linux v 32768.0.0 comes
-out, this function will break.
-.\" Maj/6yr - In 7452 we'll think of something
-
 .SH SEE ALSO
-.BR uptime (1),
-.BR fopen (3),
-.BR sysconf (3),
+.BR procps (3).
+.BR procps_pids (3).
 .BR proc (5).