sg_get_cpu_stats(3)

okay so bestie, welcome to sg_get_cpu_stats(3) — the libstatgrab page about getting cpu usage 💖✨. It's giving “I know my counters” energy, and we're keeping every single detail.

🌸 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. That's the whole squad, and yes, they're all here. 👑

✨ SYNOPSIS ✨

#include <statgrab.h>

sg_cpu_percents *sg_get_cpu_percents (size_t *entries);

sg_cpu_percents *sg_get_cpu_percents_of (sg_cpu_percent_source cps,
                size_t *entries);

sg_cpu_percents *sg_get_cpu_percents_r (const sg_cpu_stats *whereof,
                                       size_t *entries);

void sg_free_cpu_percents (sg_cpu_percents *data);

sg_cpu_stats *sg_get_cpu_stats (size_t *entries);

sg_cpu_stats *sg_get_cpu_stats_diff (size_t *entries);

sg_cpu_stats *sg_get_cpu_stats_r (size_t *entries);

sg_cpu_stats *sg_get_cpu_stats_diff_between (const sg_cpu_stats
                *cpu_now, const sg_cpu_stats *cpu_last, size_t
                *entries);

sg_error sg_free_cpu_stats (sg_cpu_stats *data);

that's the lowkey blueprint — code stays exactly as written, no remixing. 🎀

💖 DESCRIPTION 💖

okay so the cpu stats module hands you these categories of data, and the names are the whole map: 🗺️

• sg_get_cpu_stats() and sg_get_cpu_stats_r() — deliver native cpu counters since the machine has been started.
• sg_get_cpu_stats_diff() and sg_get_cpu_stats_diff_between() — deliver native cpu counters between two sg_get_cpu_stats() calls.
• sg_get_cpu_percents_of() and sg_get_cpu_percents_r() — deliver correlated relative cpu counters (where total is 100%).

🎀 API Shortcut 🎀

here's who returns what and who owns the data — no cap, this matters:

• sg_get_cpu_stats — returns sg_cpu_stats *, data owner: libstatgrab (thread local).
• sg_get_cpu_stats_r — returns sg_cpu_stats *, data owner: caller.
• sg_get_cpu_stats_diff — returns sg_cpu_stats *, data owner: libstatgrab (thread local).
• sg_get_cpu_stats_diff_between — returns sg_cpu_stats *, data owner: caller.
• sg_get_cpu_percents_of — returns sg_cpu_percents *, data owner: libstatgrab (thread local).
• sg_get_cpu_percents_r — returns sg_cpu_percents *, data owner: caller.

memory tea ☕: the sg_cpu_stats buffer you get from sg_get_cpu_stats_r() and from sg_get_cpu_stats_diff_between(), plus the sg_cpu_percents buffer from sg_get_cpu_percents_r(), must be freed using sg_free_cpu_stats() or sg_free_cpu_percents(), respectively, when you don't need it anymore. The caller is responsible for doing it. 💅

tick check ⏱️: 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 sysconf(_SC_CLK_TCK). 🧚

💀 RETURN VALUES 💀

There are two structures returned by the CPU statistics functions — here's the exact shape of them:

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;

typedef struct {
        double user;
        double kernel;
        double idle;
        double iowait;
        double swap;
        double nice;
        time_t time_taken;
} sg_cpu_percents;

the field tea 🍵:

• user, kernel, idle, iowait, swap, nice, total — the different CPU states.
• context_switches, voluntary_context_switches, involuntary_context_switches, syscalls, interrupts, soft_interrupts — the different program actions on CPU.
• systime, time_taken — the time taken in seconds since the last call of the function, or the system time.

🔥 SEE ALSO 🔥

statgrab(3) — go read that one too, bestie. 🫶

🌈 WEBSITE 🌈

⟨https://libstatgrab.org/⟩ — that's the site, exactly as the page gives it. ✨

xoxo bestie 💖 — this page is from libstatgrab, dated 2019-03-08. periodt. 👑