procps(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | DEBUGGING | SEE ALSO | COLOPHON

PROCPS(3)               Library Functions Manual               PROCPS(3)

NAME         top

       procps - API to access system level information in the /proc
       filesystem

SYNOPSIS         top

       Five distinct interfaces are represented in this synopsis and
       named after the files they access in the /proc pseudo filesystem:
       diskstats, meminfo, slabinfo, stat and vmstat.

           #include <libproc2/named_interface.h>

           int procps_new   (struct info **info);
           int procps_ref   (struct info  *info);
           int procps_unref (struct info **info);

           struct result *procps_get (
               struct info *info,
           [   const char *name,      ]   diskstats api only
               enum item item);

           struct stack *procps_select (
               struct info *info,
           [   const char *name,      ]   diskstats api only
               enum item *items,
               int numitems);

           struct reaped *procps_reap (
               struct info *info,
           [   enum reap_type what,   ]   stat api only
               enum item *items,
               int numitems);

           struct stack **procps_sort (
               struct info *info,
               struct stack *stacks[],
               int numstacked,
               enum item sortitem,
               enum sort_order order);

           The above functions and structures are generic but the
           specific named_interface would also be part of any
           identifiers.  For example, `procps_new' would actually be
           `procps_meminfo_new' and `info' would really be
           `diskstats_info', etc.

           The same named_interface is used in each header file name
           with an appended `.h' suffix.

           Link with -lproc2.

DESCRIPTION         top

   Overview
       Central to these interfaces is a simple `result' structure
       reflecting an `item' plus its value (in a union with standard C
       language types as members).  All `result' structures are
       automatically allocated and provided by the library.

       By specifying an array of `items', these structures can be
       organized as a `stack', potentially yielding many results with a
       single function call.  Thus, a `stack' can be viewed as a
       variable length record whose content and order is determined
       solely by the user.

       As part of each interface there are two unique enumerators.  The
       `noop' and `extra' items exist to hold user values.  They are
       never set by the library, but the `extra' result will be zeroed
       with each library interaction.

       The named_interface header file will be an essential document
       during user program development.  There you will find available
       items, their return type (the `result' struct member name) and
       the source for such values.  Additional enumerators and
       structures are also documented there.

   Usage
       The following would be a typical sequence of calls to these
       interfaces.

       1. procps_new()
       2. procps_get(), procps_select() or procps_reap()
       3. procps_unref()

       The get function is used to retrieve a `result' structure for a
       single `item'.  Alternatively, a GET macro is available when only
       the return value is of interest.

       The select function can retrieve multiple `result' structures in
       a single `stack'.

       For unpredictable variable outcomes, the diskstats, slabinfo and
       stat interfaces export a reap function.  It is used to retrieve
       multiple `stacks' each containing multiple `result' structures.
       Optionally, a user may choose to sort those results.

       To exploit any `stack', and access individual `result'
       structures, a relative_enum is required as shown in the VAL macro
       defined in the header file.  Such values could be hard coded as:
       0 through numitems-1.  However, this need is typically satisfied
       by creating your own enumerators corresponding to the order of
       the `items' array.

   Caveats
       The new, ref, unref, get and select functions are available in
       all five interfaces.

       For the new and unref functions, the address of an info struct
       pointer must be supplied.  With new it must have been initialized
       to NULL.  With unref it will be reset to NULL if the reference
       count reaches zero.

       In the case of the diskstats interface, a name parameter on the
       get and select functions identifies a disk or partition name

       For the stat interface, a what parameter on the reap function
       identifies whether data for just CPUs or both CPUs and NUMA nodes
       is to be gathered.

       When using the sort function, the parameters stacks and
       numstacked would normally be those returned in the `reaped'
       structure.

RETURN VALUE         top

   Functions Returning an `int'
       An error will be indicated by a negative number that is always
       the inverse of some well known errno.h value.

       Success is indicated by a zero return value.  However, the ref
       and unref functions return the current info structure reference
       count.

   Functions Returning an `address'
       An error will be indicated by a NULL return pointer with the
       reason found in the formal errno value.

       Success is indicated by a pointer to the named structure.

DEBUGGING         top

       To aid in program development, there is a provision that can help
       ensure `result' member references agree with library
       expectations.  It assumes that a supplied macro in the header
       file is used to access the `result' value.

       This feature can be activated through either of the following
       methods and any discrepancies will be written to stderr.

       1) Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure
          options employed.

       2) Add #include <procps/xtra-procps-debug.h> to any program after
          the named interface includes.

       This verification feature incurs substantial overhead.
       Therefore, it is important that it not be activated for a
       production/release build.

SEE ALSO         top

       procps_misc(3), procps_pids(3), proc(5).

COLOPHON         top

       This page is part of the procps-ng (/proc filesystem utilities)
       project.  Information about the project can be found at 
       ⟨https://gitlab.com/procps-ng/procps⟩.  If you have a bug report
       for this manual page, see
       ⟨https://gitlab.com/procps-ng/procps/blob/master/Documentation/bugs.md⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://gitlab.com/procps-ng/procps.git⟩ on 2023-12-22.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2023-10-16.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

libproc2                       August 2022                     PROCPS(3)

Pages that refer to this page: procps_misc(3)procps_pids(3)