# procps_pids - API to access process information in the /proc filesystem - man(3) - [phpMan] [_PROCPS_PIDS_(3)](https://www.chedong.com/phpMan.php/man/PROCPSPIDS/3/markdown) Library Functions Manual [_PROCPS_PIDS_(3)](https://www.chedong.com/phpMan.php/man/PROCPSPIDS/3/markdown) ## NAME procps_pids - API to access process information in the /proc filesystem ## SYNOPSIS #include 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 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. 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 to any program _after_ the #include . 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. ## SEE ALSO [**procps**(3)](https://www.chedong.com/phpMan.php/man/procps/3/markdown), [**procps_misc**(3)](https://www.chedong.com/phpMan.php/man/procpsmisc/3/markdown), [**proc**(5)](https://www.chedong.com/phpMan.php/man/proc/5/markdown). libproc2 August 2022 [_PROCPS_PIDS_(3)](https://www.chedong.com/phpMan.php/man/PROCPSPIDS/3/markdown)