# procps

## NAME



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


## SYNOPSIS



           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



       **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



       **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



           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 <libproc2/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.
    


* * *