procps_pids(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | DEBUGGING | ENVIRONMENT VARIABLE(S) | SEE ALSO | COLOPHON

PROCPS_PIDS(3)          Library Functions Manual          PROCPS_PIDS(3)

NAME         top

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

SYNOPSIS         top

       #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         top

   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.

       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         top

   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         top

       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)         top

       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         top

       procps(3), procps_misc(3), proc(5).

COLOPHON         top

       This page is part of the procps-ng (/proc filesystem utilities)
       project.  Information about the project can be found at 
       ⟨https://gitlab.com/procps-ng/procps⟩.  If you have a bug report
       for this manual page, see
       ⟨https://gitlab.com/procps-ng/procps/blob/master/Documentation/bugs.md⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://gitlab.com/procps-ng/procps.git⟩ on 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-06-04.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

libproc2                      January 2024                PROCPS_PIDS(3)

Pages that refer to this page: procps(3)procps_misc(3)