sg_get_cpu_stats(3)

NAME
sg_get_cpu_stats, sg_get_cpu_stats_r, sg_get_cpu_stats_diff, sg_get_cpu_stats_diff_between, sg_get_cpu_percents, sg_get_cpu_percents_of, sg_get_cpu_percents_r, sg_free_cpu_stats - get cpu usage

SYNOPSIS
\FC#include <statgrab.h>\F[]

\FCsg_cpu_percents *sg_get_cpu_percents\F[]
\FC(size_t *entries);\F[]

\FCsg_cpu_percents *sg_get_cpu_percents_of\F[]
\FC(sg_cpu_percent_source cps, size_t *entries);\F[]

\FCsg_cpu_percents *sg_get_cpu_percents_r\F[]
\FC(const sg_cpu_stats *whereof, size_t *entries);\F[]

\FCvoid sg_free_cpu_percents\F[]
\FC(sg_cpu_percents *data);\F[]

\FCsg_cpu_stats *sg_get_cpu_stats\F[]
\FC(size_t *entries);\F[]

\FCsg_cpu_stats *sg_get_cpu_stats_diff\F[]
\FC(size_t *entries);\F[]

\FCsg_cpu_stats *sg_get_cpu_stats_r\F[]
\FC(size_t *entries);\F[]

\FCsg_cpu_stats *sg_get_cpu_stats_diff_between\F[]
\FC(const sg_cpu_stats *cpu_now, const sg_cpu_stats *cpu_last, size_t *entries);\F[]

\FCsg_error sg_free_cpu_stats\F[]
\FC(sg_cpu_stats *data);\F[]

DESCRIPTION
These are the categories of data delivered by the cpu stats module: \FCsg_get_cpu_stats\F[]() and \FCsg_get_cpu_stats_r\F[]() deliver native cpu counters since the machine has been started, \FCsg_get_cpu_stats_diff\F[]() and \FCsg_get_cpu_stats_diff_between\F[]() deliver native cpu counters between two \FCsg_get_cpu_stats\F[]() calls and \FCsg_get_cpu_percents_of\F[]() and \FCsg_get_cpu_percents_r\F[]() deliver correlated relative cpu counters (where total is 100%).

API Shortcut
function | returns | data owner
sg_get_cpu_stats | \FCsg_cpu_stats\F[] * | libstatgrab (thread local)
sg_get_cpu_stats_r | \FCsg_cpu_stats\F[] * | caller
sg_get_cpu_stats_diff | \FCsg_cpu_stats\F[] * | libstatgrab (thread local)
sg_get_cpu_stats_diff_between | \FCsg_cpu_stats\F[] * | caller
sg_get_cpu_percents_of | \FCsg_cpu_percents\F[] * | libstatgrab (thread local)
sg_get_cpu_percents_r | \FCsg_cpu_percents\F[] * | caller

The \FCsg_cpu_stats\F[] buffer received from \FCsg_get_cpu_stats_r\F[]() and the \FCsg_get_cpu_stats_diff_between\F[]() as well as the \FCsg_cpu_percents\F[] buffer received from \FCsg_get_cpu_percents_r\F[]() must be freed using \FCsg_free_cpu_stats\F[]() or the \FCsg_free_cpu_percents\F[](), respectively, when not needed any more. The caller is responsible for doing it.

The value stored (the "ticks") will vary between operating systems. For example Solaris has a total of 100 per second, while Linux has substantially more. Also, different operating systems store different information - you won't find nice cpu on Solaris for example.

Modern systems shall provide information about the clock tick resolution by invoking \FCsysconf(_SC_CLK_TCK)\F[].

RETURN VALUES
There are two structures returned by the CPU statistics functions.

\FC
typedef struct {
        unsigned long long user;
        unsigned long long kernel;
        unsigned long long idle;
        unsigned long long iowait;
        unsigned long long swap;
        unsigned long long nice;
        unsigned long long total;
        unsigned long long context_switches;
        unsigned long long voluntary_context_switches;
        unsigned long long involuntary_context_switches;
        unsigned long long syscalls;
        unsigned long long interrupts;
        unsigned long long soft_interrupts;
        time_t systime;
} sg_cpu_stats;
    \F[]

\FC
typedef struct {
        double user;
        double kernel;
        double idle;
        double iowait;
        double swap;
        double nice;
        time_t time_taken;
} sg_cpu_percents;
    \F[]

\FCuser\F[] \FCkernel\F[] \FCidle\F[] \FCiowait\F[] \FCswap\F[] \FCnice\F[] \FCtotal\F[]
    The different CPU states.

\FCcontext_switches\F[] \FCvoluntary_context_switches\F[] \FCinvoluntary_context_switches\F[] \FCsyscalls\F[] \FCinterrupts\F[] \FCsoft_interrupts\F[]
    The different program actions on CPU.

\FCsystime\F[] \FCtime_taken\F[]
    The time taken in seconds since the last call of the function, or the system time.

SEE ALSO
statgrab(3)

WEBSITE
⟨https://libstatgrab.org/⟩