# procps - API to access system level information in the /proc fi... - man(3) - [phpMan] [_PROCPS_(3)](https://www.chedong.com/phpMan.php/man/PROCPS/3/markdown) Library Functions Manual [_PROCPS_(3)](https://www.chedong.com/phpMan.php/man/PROCPS/3/markdown) ## 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 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 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 [**procps_misc**(3)](https://www.chedong.com/phpMan.php/man/procpsmisc/3/markdown), [**procps_pids**(3)](https://www.chedong.com/phpMan.php/man/procpspids/3/markdown), [**proc**(5)](https://www.chedong.com/phpMan.php/man/proc/5/markdown). libproc2 August 2022 [_PROCPS_(3)](https://www.chedong.com/phpMan.php/man/PROCPS/3/markdown)