sg_get_process_stats(3)sg_get_process_stats(3)NAME
sg_get_process_stats, sg_get_process_stats_r, sg_get_process_count,
sg_get_process_count_of, sg_get_process_count_r, sg_free_process_count,
sg_process_compare_name, sg_process_compare_pid, sg_process_com‐
pare_uid, sg_process_compare_gid, sg_process_compare_size,
sg_process_compare_res, sg_process_compare_cpu, sg_process_compare_time
- get process statistics
SYNOPSIS
#include <statgrab.h>
sg_process_stats *sg_get_process_stats (size_t *entries);
sg_process_stats *sg_get_process_stats_r (size_t *entries);
sg_error sg_free_process_stats (sg_process_stats *data);
sg_process_count *sg_get_process_count (void);
sg_process_count *sg_get_process_count_of (sg_process_count_source
pcs);
sg_process_count *sg_get_process_count_r (sg_process_stats const
*whereof);
sg_error sg_free_process_count (sg_process_count *data);
int sg_process_compare_name (const void *va, const void *vb);
int sg_process_compare_pid (const void *va, const void *vb);
int sg_process_compare_uid (const void *va, const void *vb);
int sg_process_compare_gid (const void *va, const void *vb);
int sg_process_compare_size (const void *va, const void *vb);
int sg_process_compare_res (const void *va, const void *vb);
int sg_process_compare_cpu (const void *va, const void *vb);
int sg_process_compare_time (const void *va, const void *vb);
DESCRIPTION
The sg_get_process_stats functions provide statistics about the cur‐
rently running processes. Both functions, sg_get_process_stats() and
sg_get_process_stats_r(), take an optional entries parameter, which
points (when given) to a size_t to take the number of returned vector
entries.
The functions sg_get_process_count_of() and sg_get_process_count_r()
provide an aggregated view of the process table - they deliver the
amount of processes per process state. The sg_get_process_count() is in
fact a preprocessor macro for backward compatibility and calls
sg_get_process_count_of() with the parameter pcs of sg_en‐
tire_process_count to emulate the behavior until 0.17.
API Shortcut
┌────────────────────────┬────────────────────┬─────────────────────┐
│function │ returns │ data owner │
├────────────────────────┼────────────────────┼─────────────────────┤
│sg_get_process_stats │ sg_process_stats * │ libstatgrab (thread │
│ │ │ local) │
├────────────────────────┼────────────────────┼─────────────────────┤
│sg_get_process_stats_r │ sg_process_stats * │ caller │
├────────────────────────┼────────────────────┼─────────────────────┤
│sg_get_process_count_of │ sg_process_count * │ libstatgrab (thread │
│ │ │ local) │
├────────────────────────┼────────────────────┼─────────────────────┤
│sg_get_process_count_r │ sg_process_count * │ caller │
└────────────────────────┴────────────────────┴─────────────────────┘
The sg_process_stats vectors received from sg_get_process_stats_r() or
the sg_process_count summaries received from sg_get_process_count_r
must be freed using sg_free_process_stats() or sg_free_process_count(),
respectively. The caller is responsible for doing it when the data
isn't needed any more.
sg_process_compare_name
sg_process_compare_pid
sg_process_compare_uid
sg_process_compare_gid
sg_process_compare_size
sg_process_compare_res
sg_process_compare_cpu
sg_process_compare_time
These functions compare two sg_process_stats entries, and return an int
to represent which one is greater. The main use of these functions is
to be passed to qsort to sort the sg_process_stats by the given type.
Example
size_t entries;
sg_process_stats *proc_stats = NULL;
while( NULL != ( proc_stats = sg_get_process_stats_r(&entries) ) ) {
/* order entries by comparing the process identifier */
qsort( proc_stats, entries, sizeof(proc_stats[0]), &sg_process_compare_pid );
show_proc_stats( proc_stats );
sg_free_process_stats( proc_stats );
}
RETURN VALUES
The structure returned by sg_get_process_stats is of type
sg_process_stats.
typedef struct {
char *process_name;
char *proctitle;
pid_t pid; /* process identifier */
pid_t parent; /* Parent pid */
pid_t pgid; /* process id of process group leader */
pid_t sessid; /* session id of the session the process belongs to */
uid_t uid;
uid_t euid;
gid_t gid;
gid_t egid;
unsigned long long context_switches;
unsigned long long voluntary_context_switches;
unsigned long long involuntary_context_switches;
unsigned long long proc_size; /* in bytes */
unsigned long long proc_resident; /* in bytes */
time_t start_time; /* When was the process started */
time_t time_spent; /* time running in seconds */
double cpu_percent;
int nice;
sg_process_state state;
time_t systime;
} sg_process_stats;
typedef enum {
SG_PROCESS_STATE_RUNNING,
SG_PROCESS_STATE_SLEEPING,
SG_PROCESS_STATE_STOPPED,
SG_PROCESS_STATE_ZOMBIE,
SG_PROCESS_STATE_UNKNOWN
} sg_process_state;
process_name
The name of the command that was run. The content of this field
heavily depends on the underlying operating system, some store
the basename the executable passes to the exec(2) system call,
some the entire path. Most OS restrict the size of this field -
some like the *BSD family to a very low value of 15 bytes.
This field is usually immutable for userland processes.
proctitle
The command line (the "title") of the process. Take note - this
can be modified by the process, so isn't guaranteed to be the
original command line.
pid The process ID.
parent The parent process ID.
pgid The process ID of the process group leader.
sessid Session id of the session the process belongs to.
uid The ID of the user the process is running as.
euid The ID of the effective user the process is running as.
gid The ID of the group the process is running as.
egid The ID of the effective group the process is running as.
context_switches
The number of context switches of this process (voluntary and
involuntary).
voluntary_context_switches
The number of voluntary context switches of this process (eg.
by calling sched_yield() or sleep()).
involuntary_context_switches
The number of involuntary context switches of this process (eg.
time slice exhausted or signal sent).
proc_size
The virtual memory size of the process in bytes.
proc_resident
The size of the process that's resident in memory.
start_time
The time when the process has been started in seconds since
epoch.
time_spent
The number of seconds the process has been running (user+system
time, without time spent by child processes).
cpu_percent
The current percentage of CPU the process is using.
nice The nice value of the process.
state The current state of the process. See sg_process_state for per‐
mitted values.
systime
The time in seconds since epoch of the moment where the present
statistic has been created. This might be (but doesn't have to
be) the same moment for all returned entries, regardless whether
they're fetched with one snapshot or puzzled from some kind of
procfs.
The structure returned by sg_get_process_count_of and
sg_get_process_count_r is of type sg_process_count.
typedef enum sg_process_count_source {
sg_entire_process_count,
sg_last_process_count
} sg_process_count_source;
typedef struct{
unsigned long long total;
unsigned long long running;
unsigned long long sleeping;
unsigned long long stopped;
unsigned long long zombie;
unsigned long long unknown;
time_t systime;
}sg_process_count;
total The total number of processes.
running
The number of running processes.
sleeping
The number of sleeping processes.
stopped
The number of stopped processes.
zombie The number of zombie processes.
unknown
The number of processes not matching any of above named cate‐
gories.
systime
The time in seconds since epoch of the moment where the present
statistic has been created.
BUGS
The very first call of sg_get_process_count_of(sg_last_process_count)
will return the same as sg_get_process_count_of(sg_en‐
tire_process_count).
The compare functions exist rather for backward compatibility than for
functionality enhancements. Limited flexibility (e.g. reverse order)
and lack of optimising opportunities for the compiler leads to the rec‐
ommendation to implement the required compare routines locally.
SEE ALSOstatgrab(3)WEBSITE
⟨http://www.i-scream.org/libstatgrab/⟩
i-scream 2013-06-07 sg_get_process_stats(3)
