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

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

Browse Source 
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>
This commit is contained in:
Jim Warner 2021-01-20 00:00:00 -06:00 committed by Craig Small
parent 423297c9db
commit baa9dc93f9
1 changed files with 99 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

248
doc/procps_misc.3
View File

@ -1,4 +1,5 @@
.\" (C) Copyright 2020 Craig Small <csmall@dropbear.xyz> .\" (C) Copyright 2020 Craig Small <csmall@dropbear.xyz>
.\" (C) Copyright 2021 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,169 +17,128 @@
.\" 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_MISC 3 2020-12-21 "libproc-2" .TH PROCPS_MISC 3 "January 2021" "libproc-2"
.\" Please adjust this date whenever revising the manpage. .\" Please adjust this date whenever revising the manpage.
.\" .\"
.nh
.SH NAME .SH NAME
procps_misc \- API to system information in the /proc filesystem procps_misc \- API for miscellaneous information in the /proc filesystem
.SH SYNOPSIS .SH SYNOPSIS
.nf .nf
.B #include <proc/namespace.h> .B #include <procps/misc.h>
.PP .PP
.BI "int procps_ns_get_id(const char * " name ");" Platform Particulars
.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>
.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);
.PP
.B #include <proc/uptime.h>
.PP
.BI "int procps_uptime(double * " uptime_secs ", double * " idle_secs ");"
.B char *procps_uptime_sprint(void);
.B char *procps_uptime_sprint_short(void);
.PP
.B #include <proc/version.h>
.PP
.B int procps_linux_version(void);
.sp
Link with \fI\-lprocps\fP.
.SH DESCRIPTION
This manual page describes the miscellaneous API functions of the
.B procps
library.
.BR procps_cpu_count ()
returns the number of CPUs that are currently online. On most systems returns
the value of
.BI sysconf( _SC_NPROCESSORS_ONLY )
or assumed to be \fI1\fR.
.BR procps_hertz_get ()
returns the number of clock ticks per second. On most systems returns the
value of
.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.
.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 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.
.RS 4 .RS 4
.TP 1.2i .PP
.BR LINUX_VERSION_MAJOR (ver) .B "long procps_cpu_count (void);"
Extract the major component from the given version integer. .B "long procps_hertz_get (void);"
.TP .B "unsigned int procps_pid_length (void);"
.BR LINUX_VERSION_MINOR (ver) .B "int procps_linux_version (void);"
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 .RE
.PP .PP
To encode a given Linux version, such as using it to compare against the current Runtime Particulars
version, use the following macro:
.TP
.BI LINUX_VERSION( major , minor , patch )
.PP .PP
.BR procps_uptime () .RS 4
returns the uptime and idle time of the system. Either the .BI "int procps_loadavg (double * " av1 ", double * " av5 ", double * " av15 ");"
\fIuptime_secs\fR or \fIidle_secs\fR can be \fBNULL\fR in which case that .BI "int procps_uptime (double * " uptime_secs ", double * " idle_secs ");"
variable will not be returned. .B "char * procps_uptime_sprint (void);"
.B "char * procps_uptime_sprint_short (void);"
.RE
.PP
Namespace Particulars
.PP
.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.
The \fBsprint\fR variety of the functions return a human-readable .SH DESCRIPTION
string of the uptime and other statistics. .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_ns_get_id () .BR procps_hertz_get ()
finds the ID of the namespace for the given namespace name. 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_ns_get_name () .BR procps_pid_length ()
finds the name of the namespace of the given integer ID. 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_ns_read_pid () .BR procps_linux_version ()
puts the inodes for the namespaces of the given process into returns the current Linux version as an encoded integer. On non-Linux systems that
the array pointed to \fInsp\fR. have an emulated proc filesystem this function returns the version of the
Linux emulation instead.
.SH RETURN VALUE The version consists of three positive integers representing the major,
For minor and patch levels.
.BR procps_cpu_count "() , " procps_hertz_get "() and " procps_pid_length () The following macros are provided for encoding a given Linux version or
see the \fBDESCRIPTION\fR section for return values. 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 () .BR procps_loadavg ()
returns 0 on success. On failure, it fetches the system load average and puts the 1, 5 and 15 minute averages into
returns a negative integer to one of the values defined below. location(s) specified by any pointer which is not \fINULL\fR.
.TP
.B -ERANGE
Unable to parse the loadavg file.
.PP
.BR procps_linux_version () .BR procps_uptime ()
returns a positive integer encoding the Linux version if successful. Otherwise returns uptime and/or idle seconds into location(s) specified by any pointer
returns a negative integer to one of the values defined below. which is not \fINULL\fR.
.TP The \fBsprint\fR varieties return a human-readable string in one of two forms.
.B -EIO .RS 4
The procps library was unable to read the osrelease file.
.TP
.B -ERANGE
Unable to parse the osrelease file.
.PP .PP
.BR procps_linux_version () HH:MM:SS up HH:MM, # users, load average: 1, 5, 15 MM averages
may also return any (negated) value that \fBfopen\fR() may set errno to. .PP
up HH, MM
.RE
.BR procps_ns_get_id () .BR procps_ns_get_id ()
returns an integer for the namespace ID for the given name or returns the integer id (enum namespace_type) of the namespace for the given namespace \fIname\fR.
.B \-EINVAL
for an invalid input or an unknown namespace name.
.BR procps_ns_get_name () .BR procps_ns_get_name ()
returns a statically allocated string containing the name of the returns the name of the namespace for the given \fIid\fR (enum namespace_type).
namespace for the given ID. If the name is not found the function
returns
.B NULL
.BR procps_ns_read_pid () .BR procps_ns_read_pid ()
Returns 0 on success and \fB\-EINVAL\fR on failure. returns the inodes for the namespaces of the given process in the
procps_ns structure pointed to by \fInsp\fR.
.BR procps_uptime () Those inodes will appear in the order proscribed by enum namespace_type.
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.
.PP .PP
.BR procps_uptime () .RS 4
may also return any (negated) value that \fBfopen\fR() may set errno to. .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.
.BR procps_uptime_sprint () .SH RETURN VALUE
also displays users and load average in the buffer. The formats are the .SS Functions Returning an `int' or `long'
same as An error will be indicated by a negative number that
.BR uptime (1) is always the inverse of some well known errno.h value.
with and without the
.B \-p .SS Functions Returning an `address'
option. An error will be indicated by a NULL return pointer
with the reason found in the formal errno value.
.SH FILES .SH FILES
.TP .TP
@ -194,20 +154,10 @@ Contains the value at which PIDs wrap around, one greater than the maximum PID v
.I /proc/uptime .I /proc/uptime
The raw values for uptime and idle time. The raw values for uptime and idle time.
.TP .TP
.IB /proc/ PID /ns .IB /proc/<PID>/ns
contains the set of namespaces for a particular \fBPID\fR. 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 .SH SEE ALSO
.BR uptime (1), .BR procps (3).
.BR fopen (3), .BR procps_pids (3).
.BR sysconf (3),
.BR proc (5). .BR proc (5).