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.

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.