PROCPS_MISC(3)

NAME
procps_misc - API to system information in the /proc filesystem

SYNOPSIS
#include <proc/namespace.h>

int procps_ns_get_id(const char * name);
const char *procps_ns_get_name(const int id);
int procps_ns_read_pid(const int pid, struct procps_namespaces * nsp);

#include <proc/sysinfo.h>

long procps_cpu_count(void);
long procps_hertz_get(void);
int procps_loadavg(double * av1, double * av5, double * av15);
unsigned int procps_pid_length(void);

#include <proc/uptime.h>

int procps_uptime(double * uptime_secs, double * idle_secs);
char *procps_uptime_sprint(void);
char *procps_uptime_sprint_short(void);

#include <proc/version.h>

int procps_linux_version(void);

Link with -lprocps.

DESCRIPTION
This manual page describes the miscellaneous API functions of the procps library. procps_cpu_count() returns the number of CPUs that are currently online. On most systems returns the value of sysconf(_SC_NPROCESSORS_ONLY) or assumed to be 1. procps_hertz_get() returns the number of clock ticks per second. On most systems returns the value of sysconf(_SC_CLK_TCK) or assumed to be 100. Divide certain values returned in the in the /proc filesystem by this value to convert from ticks to seconds. 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 NULL then procps_loadavg() will not set that value. 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 /proc/sys/kernel/pid_max is unreadable, the value is assumed to be 5. 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.

The library provides 3 macros for separating out the components.

    LINUX_VERSION_MAJOR(ver)
        Extract the major component from the given version integer.

    LINUX_VERSION_MINOR(ver)
        Extract the minor component from the given version integer.

    LINUX_VERSION_PATCH(ver)
        Extract the patch component from the given version integer.

To encode a given Linux version, such as using it to compare against the current version, use the following macro:

LINUX_VERSION(major,minor,patch)

procps_uptime() returns the uptime and idle time of the system. Either the uptime_secs or idle_secs can be NULL in which case that variable will not be returned. The sprint variety of the functions return a human-readable string of the uptime and other statistics. procps_ns_get_id() finds the ID of the namespace for the given namespace name. procps_ns_get_name() finds the name of the namespace of the given integer ID. procps_ns_read_pid() puts the inodes for the namespaces of the given process into the array pointed to nsp.

RETURN VALUE
For procps_cpu_count() , procps_hertz_get() and procps_pid_length() see the DESCRIPTION section for return values. procps_loadavg() returns 0 on success. On failure, it returns a negative integer to one of the values defined below.

-ERANGE
    Unable to parse the loadavg file.

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.

-EIO
    The procps library was unable to read the osrelease file.

-ERANGE
    Unable to parse the osrelease file.

procps_linux_version() may also return any (negated) value that fopen() may set errno to. procps_ns_get_id() returns an integer for the namespace ID for the given name or -EINVAL for an invalid input or an unknown namespace name. 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 NULL procps_ns_read_pid() Returns 0 on success and -EINVAL on failure. procps_uptime() returns 0 on success. On failure, it returns a negative integer to one of the values defined below.

-ERANGE
    Unable to parse the uptime file.

procps_uptime() may also return any (negated) value that fopen() may set errno to. procps_uptime_sprint_short() return a string from a statically allocated buffer which displays uptime. procps_uptime_sprint() also displays users and load average in the buffer. The formats are the same as uptime(1) with and without the -p option.

FILES

/proc/loadavg
    The raw values for load average.

/proc/sys/kernel/osrelease
    Contains the release version of the Linux kernel or proc filesystem.

/proc/sys/kernel/pid_max
    Contains the value at which PIDs wrap around, one greater than the maximum PID value.

/proc/uptime
    The raw values for uptime and idle time.

/proc/PID/ns
    contains the set of namespaces for a particular PID.

BUGS
Due to the way the three numbers are encoded into a single integer, 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.

SEE ALSO
uptime(1), fopen(3), sysconf(3), proc(5).