1PROCPS(3) Library Functions Manual PROCPS(3)
2
6 procps - API to access system level information in the /proc filesystem
7
10 Five distinct interfaces are represented in this synopsis and named
11 after the files they access in the /proc pseudo filesystem: diskstats,
12 meminfo, slabinfo, stat and vmstat.
13 #include <libproc2/named_interface.h>
15 int procps_new (struct info **info);
17 int procps_ref (struct info *info);
18 int procps_unref (struct info **info);
19 struct result *procps_get (
21 struct info *info,
22 [ const char *name, ] diskstats api only
23 enum item item);
24 struct stack *procps_select (
26 struct info *info,
27 [ const char *name, ] diskstats api only
28 enum item *items,
29 int numitems);
30 struct reaped *procps_reap (
32 struct info *info,
33 [ enum reap_type what, ] stat api only
34 enum item *items,
35 int numitems);
36 struct stack **procps_sort (
38 struct info *info,
39 struct stack *stacks[],
40 int numstacked,
41 enum item sortitem,
42 enum sort_order order);
43 The above functions and structures are generic but the specific
46 named_interface would also be part of any identifiers. For
47 example, `procps_new' would actually be `procps_meminfo_new' and
48 `info' would really be `diskstats_info', etc.
49 The same named_interface is used in each header file name with an
51 appended `.h' suffix.
52 Link with -lproc2.
54
57 Overview
58 Central to these interfaces is a simple `result' structure reflecting
59 an `item' plus its value (in a union with standard C language types as
60 members). All `result' structures are automatically allocated and
61 provided by the library.
62 By specifying an array of `items', these structures can be organized as
64 a `stack', potentially yielding many results with a single function
65 call. Thus, a `stack' can be viewed as a variable length record whose
66 content and order is determined solely by the user.
67 As part of each interface there are two unique enumerators. The `noop'
69 and `extra' items exist to hold user values. They are never set by the
70 library, but the `extra' result will be zeroed with each library
71 interaction.
72 The named_interface header file will be an essential document during
74 user program development. There you will find available items, their
75 return type (the `result' struct member name) and the source for such
76 values. Additional enumerators and structures are also documented
77 there.
78 Usage
81 The following would be a typical sequence of calls to these interfaces.
82 1. procps_new()
84 2. procps_get(), procps_select() or procps_reap()
85 3. procps_unref()
86 The get function is used to retrieve a `result' structure for a single
88 `item'. Alternatively, a GET macro is available when only the return
89 value is of interest.
90 The select function can retrieve multiple `result' structures in a
92 single `stack'.
93 For unpredictable variable outcomes, the diskstats, slabinfo and stat
95 interfaces export a reap function. It is used to retrieve multiple
96 `stacks' each containing multiple `result' structures. Optionally, a
97 user may choose to sort those results.
98 To exploit any `stack', and access individual `result' structures, a
100 relative_enum is required as shown in the VAL macro defined in the
101 header file. Such values could be hard coded as: 0 through numitems-1.
102 However, this need is typically satisfied by creating your own
103 enumerators corresponding to the order of the `items' array.
104 Caveats
107 The new, ref, unref, get and select functions are available in all five
108 interfaces.
109 For the new and unref functions, the address of an info struct pointer
111 must be supplied. With new it must have been initialized to NULL.
112 With unref it will be reset to NULL if the reference count reaches
113 zero.
114 In the case of the diskstats interface, a name parameter on the get and
116 select functions identifies a disk or partition name
117 For the stat interface, a what parameter on the reap function
119 identifies whether data for just CPUs or both CPUs and NUMA nodes is to
120 be gathered.
121 When using the sort function, the parameters stacks and numstacked
123 would normally be those returned in the `reaped' structure.
124
127 Functions Returning an `int'
128 An error will be indicated by a negative number that is always the
129 inverse of some well known errno.h value.
130 Success is indicated by a zero return value. However, the ref and
132 unref functions return the current info structure reference count.
133 Functions Returning an `address'
136 An error will be indicated by a NULL return pointer with the reason
137 found in the formal errno value.
138 Success is indicated by a pointer to the named structure.
140
143 To aid in program development, there is a provision that can help
144 ensure `result' member references agree with library expectations. It
145 assumes that a supplied macro in the header file is used to access the
146 `result' value.
147 This feature can be activated through either of the following methods
149 and any discrepancies will be written to stderr.
150 1) Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure options
153 employed.
154 2) Add #include <procps/xtra-procps-debug.h> to any program after the
157 named interface includes.
158 This verification feature incurs substantial overhead. Therefore, it
161 is important that it not be activated for a production/release build.
162
165 procps_misc(3), procps_pids(3), proc(5).
166libproc2 August 2022 PROCPS(3)