From 02e35c1fb1bd1faf4de5bf2590761be619263046 Mon Sep 17 00:00:00 2001 From: Craig Small Date: Sat, 24 Oct 2020 18:25:48 +1100 Subject: [PATCH] docs: Add procps_misc.3 manpage The last (I think) of the newlib man pages for the new API. --- Makefile.am | 1 + doc/procps_misc.3 | 82 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 doc/procps_misc.3 diff --git a/Makefile.am b/Makefile.am index 60072683..6b460ca4 100644 --- a/Makefile.am +++ b/Makefile.am @@ -83,6 +83,7 @@ dist_man_MANS = \ doc/procps_ns_get_name.3 \ doc/procps_ns_read_pid.3 \ doc/procps_pids.3 \ + doc/procps_misc.3 \ doc/procps_uptime.3 \ doc/procps_uptime_sprint.3 \ doc/procps_uptime_sprint_short.3 diff --git a/doc/procps_misc.3 b/doc/procps_misc.3 new file mode 100644 index 00000000..e0884fa6 --- /dev/null +++ b/doc/procps_misc.3 @@ -0,0 +1,82 @@ +.\" (C) Copyright 2020 Craig Small +.\" +.\" %%%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 2020-10-20 "libproc-2" +.\" Please adjust this date whenever revising the manpage. +.\" +.SH NAME +procps_misc \- API to system information in the /proc filesystem +.SH SYNOPSIS +.nf +.B #include +.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); +.sp +Link with \fI\-lprocps\fP. +.SH DESCRIPTION +.BR procps_cpu_count () +returns the number of CPUs that are currently online. On most systems returns +the value of +.BI sysconf( _SC_NPROCESSORS_ONLN ) +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. + +.SH RETURN VALUE +For +.BR procps_cpu_count "() , " procps_hertz_get "() and " procps_pid_length () +see the \fBDESCRIPTION\fR section for return values. + +.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 + +.SH FILES +.TP +.I /proc/loadavg +The raw values for load average. +.TP +.I /proc/sys/kernel/pid_max +Contains the value at which PIDs wrap around, one greater than the maximum PID value. + +.SH SEE ALSO +.BR sysconf (3), +.BR proc (5).