'\" t -*- coding: UTF-8 -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH sg_get_cpu_stats 3 2019-03-08 libstatgrab ""
.SH 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
.SH SYNOPSIS
'nh
.nf
\*(T<#include <statgrab.h>\*(T>
.fi
.sp 1
.PP
.fi
.ad l
\*(T<sg_cpu_percents *\fBsg_get_cpu_percents\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_cpu_percents *\fBsg_get_cpu_percents_of\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(sg_cpu_percent_source \fIcps\fR, size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_cpu_percents *\fBsg_get_cpu_percents_r\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(const sg_cpu_stats *\fIwhereof\fR, size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<void \fBsg_free_cpu_percents\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(sg_cpu_percents *\fIdata\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_cpu_stats *\fBsg_get_cpu_stats\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_cpu_stats *\fBsg_get_cpu_stats_diff\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_cpu_stats *\fBsg_get_cpu_stats_r\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_cpu_stats *\fBsg_get_cpu_stats_diff_between\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(const sg_cpu_stats *\fIcpu_now\fR, const sg_cpu_stats *\fIcpu_last\fR, size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_error \fBsg_free_cpu_stats\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(sg_cpu_stats *\fIdata\fR);\*(T>
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
These are the categories of data delivered by the cpu stats module:
\*(T<\fBsg_get_cpu_stats\fR\*(T>() and
\*(T<\fBsg_get_cpu_stats_r\fR\*(T>() deliver native cpu
counters since the machine has been started,
\*(T<\fBsg_get_cpu_stats_diff\fR\*(T>() and
\*(T<\fBsg_get_cpu_stats_diff_between\fR\*(T>() deliver native
cpu counters between two \*(T<\fBsg_get_cpu_stats\fR\*(T>()
calls and \*(T<\fBsg_get_cpu_percents_of\fR\*(T>() and
\*(T<\fBsg_get_cpu_percents_r\fR\*(T>() deliver correlated relative
cpu counters (where total is 100%).
.PP
\fBAPI Shortcut\fR
.TS
allbox ;
l | l | l.
T{
function
T}	T{
returns
T}	T{
data owner
T}
.T&
l | l | l.
T{
sg_get_cpu_stats
T}	T{
\*(T<sg_cpu_stats\*(T> *
T}	T{
libstatgrab (thread local)
T}
T{
sg_get_cpu_stats_r
T}	T{
\*(T<sg_cpu_stats\*(T> *
T}	T{
caller
T}
T{
sg_get_cpu_stats_diff
T}	T{
\*(T<sg_cpu_stats\*(T> *
T}	T{
libstatgrab (thread local)
T}
T{
sg_get_cpu_stats_diff_between
T}	T{
\*(T<sg_cpu_stats\*(T> *
T}	T{
caller
T}
T{
sg_get_cpu_percents_of
T}	T{
\*(T<sg_cpu_percents\*(T> *
T}	T{
libstatgrab (thread local)
T}
T{
sg_get_cpu_percents_r
T}	T{
\*(T<sg_cpu_percents\*(T> *
T}	T{
caller
T}
.TE
.PP
The \*(T<sg_cpu_stats\*(T> buffer received from
\*(T<\fBsg_get_cpu_stats_r\fR\*(T>() and the
\*(T<\fBsg_get_cpu_stats_diff_between\fR\*(T>() as well as the
\*(T<sg_cpu_percents\*(T> buffer received from
\*(T<\fBsg_get_cpu_percents_r\fR\*(T>() must be freed using
\*(T<\fBsg_free_cpu_stats\fR\*(T>() or the
\*(T<\fBsg_free_cpu_percents\fR\*(T>(), respectively, when not
needed any more. The caller is responsible for doing it.
.PP
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.
.PP
Modern systems shall provide information about the clock tick
resolution by invoking \*(T<sysconf(_SC_CLK_TCK)\*(T>.
.SH "RETURN VALUES"
There are two structures returned by the CPU statistics
functions.
.PP
.nf
\*(T<
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;
    \*(T>
.fi
.PP
.nf
\*(T<
typedef struct {
        double user;
        double kernel;
        double idle;
        double iowait;
        double swap;
        double nice;
        time_t time_taken;
} sg_cpu_percents;
    \*(T>
.fi
.TP 
\*(T<user\*(T> \*(T<kernel\*(T> \*(T<idle\*(T> \*(T<iowait\*(T> \*(T<swap\*(T> \*(T<nice\*(T> \*(T<total\*(T> 
The different CPU states.
.TP 
\*(T<context_switches\*(T> \*(T<voluntary_context_switches\*(T> \*(T<involuntary_context_switches\*(T> \*(T<syscalls\*(T> \*(T<interrupts\*(T> \*(T<soft_interrupts\*(T> 
The different program actions on CPU.
.TP 
\*(T<systime\*(T> \*(T<time_taken\*(T> 
The time taken in seconds since the last call of the
function, or the system time.
.SH "SEE ALSO"
\fBstatgrab\fR(3)
.SH WEBSITE
\(lahttps://libstatgrab.org/\(ra