1PROCPS_PIDS(3) Library Functions Manual PROCPS_PIDS(3)
2
6 procps_pids - API to access process information in the /proc filesystem
7
10 #include <libproc2/pids.h>
11 int procps_pids_new (struct pids_info **info, enum pids_item *items, int numitems);
13 int procps_pids_ref (struct pids_info *info);
14 int procps_pids_unref (struct pids_info **info);
15 struct pids_stack *procps_pids_get (
18 struct pids_info *info,
19 enum pids_fetch_type which);
20 struct pids_fetch *procps_pids_reap (
22 struct pids_info *info,
23 enum pids_fetch_type which);
24 struct pids_fetch *procps_pids_select (
26 struct pids_info *info,
27 unsigned *these,
28 int numthese,
29 enum pids_select_type which);
30 struct pids_stack **procps_pids_sort (
32 struct pids_info *info,
33 struct pids_stack *stacks[],
34 int numstacked,
35 enum pids_item sortitem,
36 enum pids_sort_order order);
37 int procps_pids_reset (
39 struct pids_info *info,
40 enum pids_item *newitems,
41 int newnumitems);
42 struct pids_stack *fatal_proc_unmounted (
44 struct pids_info *info,
45 int return_self);
46 Link with -lproc2.
49
52 Overview
53 Central to this interface is a simple `result' structure reflecting an
54 `item' plus its value (in a union with standard C language types as
55 members). All `result' structures are automatically allocated and
56 provided by the library.
57 By specifying an array of `items', these structures can be organized as
59 a `stack', potentially yielding many results with a single function
60 call. Thus, a `stack' can be viewed as a variable length record whose
61 content and order is determined solely by the user.
62 As part of this interface there are two unique enumerators. The `noop'
64 and `extra' items exist to hold user values. They are never set by the
65 library, but the `extra' result will be zeroed with each library
66 interaction.
67 The pids.h file will be an essential document during user program
69 development. There you will find available items, their return type
70 (the `result' struct member name) and the source for such values.
71 Additional enumerators and structures are also documented there.
72 Usage
75 The following would be a typical sequence of calls to this interface.
76 1. fatal_proc_unmounted()
78 2. procps_pids_new()
79 3. procps_pids_get(), procps_pids_reap() or procps_pids_select()
80 4. procps_pids_unref()
81 The get function is an iterator for successive PIDs/TIDs, returning
83 those `items' previously identified via new or reset.
84 Two functions support unpredictable variable outcomes. The reap
86 function gathers data for all processes while the select function deals
87 with specific PIDs or UIDs. Both can return multiple `stacks' each
88 containing multiple `result' structures. Optionally, a user may choose
89 to sort such results
90 To exploit any `stack', and access individual `result' structures, a
92 relative_enum is required as shown in the VAL macro defined in the
93 header file. Such values could be hard coded as: 0 through numitems-1.
94 However, this need is typically satisfied by creating your own
95 enumerators corresponding to the order of the `items' array.
96 Caveats
99 The <pids> API differs from others in that those items of interest must
100 be provided at new or reset time, the latter being unique to this API.
101 If either the items or numitems parameter is zero at new time, then
102 reset becomes mandatory before issuing any other call.
103 For the new and unref functions, the address of an info struct pointer
105 must be supplied. With new it must have been initialized to NULL.
106 With unref it will be reset to NULL if the reference count reaches
107 zero.
108 The get and reap functions use the which parameter to specify whether
110 just tasks or both tasks and threads are to be fetched.
111 The select function requires an array of PIDs or UIDs as these along
113 with numthese to identify which processes are to be fetched. This
114 function then operates as a subset of reap.
115 When using the sort function, the parameters stacks and numstacked
117 would normally be those returned in the `pids_fetch' structure.
118 Lastly, a fatal_proc_unmounted function may be called before any other
120 function to ensure that the /proc/ directory is mounted. As such, the
121 info parameter would be NULL and the return_self parameter zero. If,
122 however, some items are desired for the issuing program (a return_self
123 other than zero) then the new call must precede it to identify the
124 items and obtain the required info pointer.
125
128 Functions Returning an `int'
129 An error will be indicated by a negative number that is always the
130 inverse of some well known errno.h value.
131 Success is indicated by a zero return value. However, the ref and
133 unref functions return the current info structure reference count.
134 Functions Returning an `address'
137 An error will be indicated by a NULL return pointer with the reason
138 found in the formal errno value.
139 Success is indicated by a pointer to the named structure. However, if
141 one survives the fatal_proc_unmounted call, NULL is always returned
142 when return_self is zero.
143
146 To aid in program development, there are two procps-ng provisions that
147 can be exploited.
148 The first is a supplied file named `libproc.supp' which may be useful
150 when developing a multi-threaded application. When used with the
151 valgrind `--suppressions=' option, warnings associated with the procps
152 library itself are avoided.
153 Such warnings arise because the library handles heap based allocations
155 in a thread-safe manner. A single-threaded application will not
156 receive those warnings.
157 The second provision can help ensure `result' member references agree
159 with library expectations. It assumes that a supplied macro in the
160 header file is used to access the `result' value.
161 This feature can be activated through either of the following methods
163 and any discrepancies will be written to stderr.
164 1) Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure options
167 your project may employ.
168 2) Add #include <procps/xtra-procps-debug.h> to any program after the
171 #include <procps/pids.h>.
172 This verification feature incurs substantial overhead. Therefore, it
175 is important that it not be activated for a production/release build.
176
179 The value set for the following is unimportant, just its presence.
180 LIBPROC_HIDE_KERNEL
183 This will hide kernel threads which would otherwise be returned
184 with a procps_pids_get, procps_pids_select or procps_pids_reap
185 call.
186
189 procps(3), procps_misc(3), proc(5).
190libproc2 August 2022 PROCPS_PIDS(3)