1sg_get_process_stats(3) sg_get_process_stats(3)
2
6 sg_get_process_stats, sg_get_process_stats_r, sg_get_process_count,
7 sg_get_process_count_of, sg_get_process_count_r, sg_free_process_count,
8 sg_process_compare_name, sg_process_compare_pid, sg_process_com‐
9 pare_uid, sg_process_compare_gid, sg_process_compare_size,
10 sg_process_compare_res, sg_process_compare_cpu, sg_process_compare_time
11 - get process statistics
12
14 #include <statgrab.h>
15 sg_process_stats *sg_get_process_stats (size_t *entries);
18 sg_process_stats *sg_get_process_stats_r (size_t *entries);
20 sg_error sg_free_process_stats (sg_process_stats *data);
22 sg_process_count *sg_get_process_count (void);
24 sg_process_count *sg_get_process_count_of (sg_process_count_source
26 pcs);
27 sg_process_count *sg_get_process_count_r (sg_process_stats const
29 *whereof);
30 sg_error sg_free_process_count (sg_process_count *data);
32 int sg_process_compare_name (const void *va, const void *vb);
34 int sg_process_compare_pid (const void *va, const void *vb);
36 int sg_process_compare_uid (const void *va, const void *vb);
38 int sg_process_compare_gid (const void *va, const void *vb);
40 int sg_process_compare_size (const void *va, const void *vb);
42 int sg_process_compare_res (const void *va, const void *vb);
44 int sg_process_compare_cpu (const void *va, const void *vb);
46 int sg_process_compare_time (const void *va, const void *vb);
48
50 The sg_get_process_stats functions provide statistics about the cur‐
51 rently running processes. Both functions, sg_get_process_stats() and
52 sg_get_process_stats_r(), take an optional entries parameter, which
53 points (when given) to a size_t to take the number of returned vector
54 entries.
55 The functions sg_get_process_count_of() and sg_get_process_count_r()
57 provide an aggregated view of the process table - they deliver the
58 amount of processes per process state. The sg_get_process_count() is in
59 fact a preprocessor macro for backward compatibility and calls
60 sg_get_process_count_of() with the parameter pcs of sg_en‐
61 tire_process_count to emulate the behavior until 0.17.
62 API Shortcut
64 ┌────────────────────────┬────────────────────┬─────────────────────┐
66 │function │ returns │ data owner │
67 ├────────────────────────┼────────────────────┼─────────────────────┤
68 │sg_get_process_stats │ sg_process_stats * │ libstatgrab (thread │
69 │ │ │ local) │
70 ├────────────────────────┼────────────────────┼─────────────────────┤
71 │sg_get_process_stats_r │ sg_process_stats * │ caller │
72 ├────────────────────────┼────────────────────┼─────────────────────┤
73 │sg_get_process_count_of │ sg_process_count * │ libstatgrab (thread │
74 │ │ │ local) │
75 ├────────────────────────┼────────────────────┼─────────────────────┤
76 │sg_get_process_count_r │ sg_process_count * │ caller │
77 └────────────────────────┴────────────────────┴─────────────────────┘
78 The sg_process_stats vectors received from sg_get_process_stats_r() or
79 the sg_process_count summaries received from sg_get_process_count_r
80 must be freed using sg_free_process_stats() or sg_free_process_count(),
81 respectively. The caller is responsible for doing it when the data
82 isn't needed any more.
83 sg_process_compare_name
85 sg_process_compare_pid
86 sg_process_compare_uid
87 sg_process_compare_gid
88 sg_process_compare_size
89 sg_process_compare_res
90 sg_process_compare_cpu
91 sg_process_compare_time
92 These functions compare two sg_process_stats entries, and return an int
94 to represent which one is greater. The main use of these functions is
95 to be passed to qsort to sort the sg_process_stats by the given type.
96 Example
98 size_t entries;
100 sg_process_stats *proc_stats = NULL;
101 while( NULL != ( proc_stats = sg_get_process_stats_r(&entries) ) ) {
102 /* order entries by comparing the process identifier */
103 qsort( proc_stats, entries, sizeof(proc_stats[0]), &sg_process_compare_pid );
104 show_proc_stats( proc_stats );
105 sg_free_process_stats( proc_stats );
106 }
107
110 The structure returned by sg_get_process_stats is of type
111 sg_process_stats.
112 typedef struct {
114 char *process_name;
115 char *proctitle;
116 pid_t pid; /* process identifier */
118 pid_t parent; /* Parent pid */
119 pid_t pgid; /* process id of process group leader */
120 pid_t sessid; /* session id of the session the process belongs to */
121 uid_t uid;
123 uid_t euid;
124 gid_t gid;
125 gid_t egid;
126 unsigned long long context_switches;
128 unsigned long long voluntary_context_switches;
129 unsigned long long involuntary_context_switches;
130 unsigned long long proc_size; /* in bytes */
131 unsigned long long proc_resident; /* in bytes */
132 time_t start_time; /* When was the process started */
133 time_t time_spent; /* time running in seconds */
134 double cpu_percent;
135 int nice;
136 sg_process_state state;
137 time_t systime;
139 } sg_process_stats;
140 typedef enum {
143 SG_PROCESS_STATE_RUNNING,
144 SG_PROCESS_STATE_SLEEPING,
145 SG_PROCESS_STATE_STOPPED,
146 SG_PROCESS_STATE_ZOMBIE,
147 SG_PROCESS_STATE_UNKNOWN
148 } sg_process_state;
149 process_name
152 The name of the command that was run. The content of this field
153 heavily depends on the underlying operating system, some store
154 the basename the executable passes to the exec(2) system call,
155 some the entire path. Most OS restrict the size of this field -
156 some like the *BSD family to a very low value of 15 bytes.
157 This field is usually immutable for userland processes.
159 proctitle
161 The command line (the "title") of the process. Take note - this
162 can be modified by the process, so isn't guaranteed to be the
163 original command line.
164 pid The process ID.
166 parent The parent process ID.
168 pgid The process ID of the process group leader.
170 sessid Session id of the session the process belongs to.
172 uid The ID of the user the process is running as.
174 euid The ID of the effective user the process is running as.
176 gid The ID of the group the process is running as.
178 egid The ID of the effective group the process is running as.
180 context_switches
182 The number of context switches of this process (voluntary and
183 involuntary).
184 voluntary_context_switches
186 The number of voluntary context switches of this process (eg.
187 by calling sched_yield() or sleep()).
188 involuntary_context_switches
190 The number of involuntary context switches of this process (eg.
191 time slice exhausted or signal sent).
192 proc_size
194 The virtual memory size of the process in bytes.
195 proc_resident
197 The size of the process that's resident in memory.
198 start_time
200 The time when the process has been started in seconds since
201 epoch.
202 time_spent
204 The number of seconds the process has been running (user+system
205 time, without time spent by child processes).
206 cpu_percent
208 The current percentage of CPU the process is using.
209 nice The nice value of the process.
211 state The current state of the process. See sg_process_state for per‐
213 mitted values.
214 systime
216 The time in seconds since epoch of the moment where the present
217 statistic has been created. This might be (but doesn't have to
218 be) the same moment for all returned entries, regardless whether
219 they're fetched with one snapshot or puzzled from some kind of
220 procfs.
221 The structure returned by sg_get_process_count_of and
223 sg_get_process_count_r is of type sg_process_count.
224 typedef enum sg_process_count_source {
226 sg_entire_process_count,
227 sg_last_process_count
228 } sg_process_count_source;
229 typedef struct{
232 unsigned long long total;
233 unsigned long long running;
234 unsigned long long sleeping;
235 unsigned long long stopped;
236 unsigned long long zombie;
237 unsigned long long unknown;
238 time_t systime;
240 }sg_process_count;
241 total The total number of processes.
244 running
246 The number of running processes.
247 sleeping
249 The number of sleeping processes.
250 stopped
252 The number of stopped processes.
253 zombie The number of zombie processes.
255 unknown
257 The number of processes not matching any of above named cate‐
258 gories.
259 systime
261 The time in seconds since epoch of the moment where the present
262 statistic has been created.
263
265 The very first call of sg_get_process_count_of(sg_last_process_count)
266 will return the same as sg_get_process_count_of(sg_en‐
267 tire_process_count).
268 The compare functions exist rather for backward compatibility than for
270 functionality enhancements. Limited flexibility (e.g. reverse order)
271 and lack of optimising opportunities for the compiler leads to the rec‐
272 ommendation to implement the required compare routines locally.
273
275 statgrab(3)
276
278 ⟨https://libstatgrab.org/⟩
279libstatgrab 2019-03-08 sg_get_process_stats(3)