Provided by: libstatgrab-dev_0.92.1-1.2build1_amd64 bug

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_compare_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  currently  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_entire_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 permitted 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 categories.

       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_entire_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  recommendation  to  implement  the  required
       compare routines locally.

SEE ALSO

       statgrab(3)

WEBSITE

       ⟨https://libstatgrab.org/⟩