procps/doc/procps_misc.3

.\" (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 "January 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
.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
Runtime Particulars
.PP
.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
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

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_IPC,
    PROCPS_NS_MNT,
    PROCPS_NS_NET,
    PROCPS_NS_PID,
    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).