# procps_pids

## NAME



           procps_pids - API to access process information in the /proc
           filesystem
    


## SYNOPSIS



           #include <libproc2/pids.h>
    
           int **procps_pids_new**(struct pids_info **_info_ , enum pids_item *_items_ , int _numitems_);
           int **procps_pids_ref**(struct pids_info  *_info_);
           int **procps_pids_unref**(struct pids_info **_info_);
    
           struct pids_stack * **procps_pids_get**(
               struct pids_info *_info_ ,
               enum pids_fetch_type _which_);
    
           struct pids_fetch * **procps_pids_reap**(
               struct pids_info *_info_ ,
               enum pids_fetch_type _which_);
    
           struct pids_fetch * **procps_pids_select**(
               struct pids_info *_info_ ,
               unsigned *_these_ ,
               int _numthese_ ,
               enum pids_select_type _which_);
    
           struct pids_stack ** **procps_pids_sort**(
               struct pids_info *_info_ ,
               struct pids_stack *_stacks_[],
               int _numstacked_ ,
               enum pids_item _sortitem_ ,
               enum pids_sort_order _order_);
    
           int **procps_pids_reset**(
               struct pids_info *_info_ ,
               enum pids_item *_newitems_ ,
               int _newnumitems_);
    
           struct pids_stack * **fatal_proc_unmounted**(
               struct pids_info *_info_ ,
               int _return_self_);
    
           Link with _-lproc2_.
    


## DESCRIPTION



       **Overview**
           Central to this interface 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 this 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 pids.h 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 this
           interface.
    
           1. **fatal_proc_unmounted()**
           2. **procps_pids_new()**
           3. **procps_pids_get()** , **procps_pids_reap()** or **procps_pids_select()**
           4. **procps_pids_unref()**
    
           The **get** function is an iterator for successive PIDs/TIDs,
           returning those ‘items’ previously identified via **new** or **reset**.
    
           Two functions support unpredictable variable outcomes.  The **reap**
           function gathers data for all processes while the **select** function
           deals with specific PIDs or UIDs.  Both can return multiple
           ‘stacks’ each containing multiple ‘result’ structures.
           Optionally, a user may choose to **sort** such 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 <pids> API differs from others in that those items of interest
           must be provided at **new** or **reset** time, the latter being unique to
           this API.  If either the _items_ or _numitems_ parameter is zero at
           **new** time, then **reset** becomes mandatory before issuing any other
           call.  Otherwise, procps_pids_reset() should only be called when
           the order or number of items in your stacks is changed.
    
           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.
    
           The **get** and **reap** functions use the _which_ parameter to specify
           whether just tasks or both tasks and threads are to be fetched.
    
           The **select** function requires an array of PIDs or UIDs as _these_
           along with _numthese_ to identify which processes are to be fetched.
           This function then operates as a subset of **reap**.
    
           When using the **sort** function, the parameters _stacks_ and _numstacked_
           would normally be those returned in the ‘pids_fetch’ structure.
    
           Lastly, a **fatal_proc_unmounted** function may be called before any
           other function to ensure that the /proc/ directory is mounted.  As
           such, the _info_ parameter would be NULL and the _return_self_
           parameter zero.  If, however, some items are desired for the
           issuing program (a _return_self_ other than zero) then the **new** call
           must precede it to identify the _items_ and obtain the required _info_
           pointer.
    


## 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.
           However, if one survives the **fatal_proc_unmounted** call, NULL is
           always returned when _return_self_ is zero.
    


## DEBUGGING



           To aid in program development, there are two procps-ng provisions
           that can be exploited.
    
           The first is a supplied file named ‘libproc.supp’ which may be
           useful when developing a _multi-threaded_ application.  When used
           with the valgrind ‘--suppressions=’ option, warnings associated
           with the procps library itself are avoided.
    
           Such warnings arise because the library handles heap based
           allocations in a thread-safe manner.  A _single-threaded_
           application will not receive those warnings.
    
           The second provision 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 your project may employ.
    
           2) Add #include <libproc2/xtra-procps-debug.h> to any program
              _after_ the #include <libproc2/pids.h>.
    
           This verification feature incurs substantial overhead.  Therefore,
           it is important that it _not_ be activated for a production/release
           build.
    


## ENVIRONMENT VARIABLE(S)



           The value set for the following is unimportant, just its presence.
    
           LIBPROC_HIDE_KERNEL
                  This will hide kernel threads which would otherwise be
                  returned with a **procps_pids_get** , **procps_pids_select** or
                  **procps_pids_reap** call.
    


* * *