System Statistics

Modules
	Overview

Data Structures
struct	SysMemInfo
	How much memory the machine has and how much of it is spoken for. More...
struct	SysCPUTimes
struct	SysUptime
	How long the machine has been running. More...
struct	SysLoadAvg
struct	ProcMemInfo
	How much memory one process is using. More...
struct	ProcCPUTimes
	Processor time one process has used since it started. More...
struct	ProcIOInfo
struct	SysCPUSampler
	Remembers the previous reading so repeated polling needs only one call each time. More...
struct	ProcCPUSampler

Macros
#define	sysCPUSamplerInit(s)   memset((s), 0, sizeof(SysCPUSampler))
#define	procCPUSamplerInit(s)   memset((s), 0, sizeof(ProcCPUSampler))

Typedefs
typedef struct SysMemInfo	SysMemInfo
	How much memory the machine has and how much of it is spoken for.
typedef struct SysCPUTimes	SysCPUTimes
typedef struct SysUptime	SysUptime
	How long the machine has been running.
typedef struct SysLoadAvg	SysLoadAvg
typedef struct ProcMemInfo	ProcMemInfo
	How much memory one process is using.
typedef struct ProcCPUTimes	ProcCPUTimes
	Processor time one process has used since it started.
typedef struct ProcIOInfo	ProcIOInfo
typedef struct SysCPUSampler	SysCPUSampler
	Remembers the previous reading so repeated polling needs only one call each time.
typedef struct ProcCPUSampler	ProcCPUSampler

Enumerations
enum	SysMemInfoValid { SYSMEM_Phys = 0x0001 , SYSMEM_Commit = 0x0002 , SYSMEM_Swap = 0x0004 , SYSMEM_PageSize = 0x0008 }
	Which fields of a SysMemInfo the operating system reported. More...
enum	SysCPUTimesValid {   SYSCPU_User = 0x0001 , SYSCPU_System = 0x0002 , SYSCPU_Idle = 0x0004 , SYSCPU_IOWait = 0x0008 ,   SYSCPU_IRQ = 0x0010 , SYSCPU_Steal = 0x0020 }
	Which breakdown fields of a SysCPUTimes the operating system reported. More...
enum	SysUptimeValid { SYSUP_Uptime = 0x0001 , SYSUP_BootTime = 0x0002 }
	Which fields of a SysUptime the operating system reported. More...
enum	SysLoadAvgValid { SYSLOAD_Load1 = 0x0001 , SYSLOAD_Load5 = 0x0002 , SYSLOAD_Load15 = 0x0004 }
	Which fields of a SysLoadAvg the operating system reported. More...
enum	ProcMemInfoValid {   PROCMEM_Resident = 0x0001 , PROCMEM_PeakResident = 0x0002 , PROCMEM_Virtual = 0x0004 , PROCMEM_PeakVirtual = 0x0008 ,   PROCMEM_Private = 0x0010 , PROCMEM_Swapped = 0x0020 }
	Which fields of a ProcMemInfo the operating system reported. More...
enum	ProcCPUTimesValid { PROCCPU_User = 0x0001 , PROCCPU_System = 0x0002 , PROCCPU_Started = 0x0004 }
	Which fields of a ProcCPUTimes the operating system reported. More...
enum	ProcIOInfoValid { PROCIO_Bytes = 0x0001 , PROCIO_Ops = 0x0002 , PROCIO_Other = 0x0004 }
	Which fields of a ProcIOInfo the operating system reported. More...

Functions
bool	sysMemInfo (SysMemInfo *out)
bool	sysCPUTimes (SysCPUTimes *out)
bool	sysUptime (SysUptime *out)
bool	sysLoadAvg (SysLoadAvg *out)
float64	sysCPUUsage (const SysCPUTimes *first, const SysCPUTimes *second)
bool	sysCPUSample (SysCPUSampler *s, float64 *pct)
bool	procMemInfo (ProcMemInfo *out, Process *proc)
bool	procMemInfoByID (ProcMemInfo *out, ProcessID pid)
bool	procCPUTimes (ProcCPUTimes *out, Process *proc)
bool	procCPUTimesByID (ProcCPUTimes *out, ProcessID pid)
bool	procIOInfo (ProcIOInfo *out, Process *proc)
bool	procIOInfoByID (ProcIOInfo *out, ProcessID pid)
float64	procCPUUsage (const ProcCPUTimes *first, const ProcCPUTimes *second)
bool	procCPUSample (ProcCPUSampler *s, Process *proc, float64 *pct)

Detailed Description

Macro Definition Documentation

procCPUSamplerInit

#define procCPUSamplerInit

(

s

)

memset((s), 0, sizeof(ProcCPUSampler))

void procCPUSamplerInit(ProcCPUSampler *s);

Prepares a sampler for use.

Parameters

s	Sampler to prepare

Example:

ProcCPUSampler sampler;
procCPUSamplerInit(&sampler);

Definition at line 523 of file sysinfo.h.

sysCPUSamplerInit

#define sysCPUSamplerInit

(

s

)

memset((s), 0, sizeof(SysCPUSampler))

void sysCPUSamplerInit(SysCPUSampler *s);

Prepares a sampler for use.

Parameters

s	Sampler to prepare

Example:

SysCPUSampler sampler;
sysCPUSamplerInit(&sampler);

Definition at line 385 of file sysinfo.h.

Typedef Documentation

ProcCPUSampler

typedef struct ProcCPUSampler ProcCPUSampler

Remembers the previous reading so repeated polling needs only one call each time

Does not hold the process itself; pass it to procCPUSample() on every call.

ProcIOInfo

typedef struct ProcIOInfo ProcIOInfo

How much reading and writing one process has done

The counts cover every kind of input and output, not just files – a network socket and a pipe are counted the same way a disk is.

SysCPUTimes

typedef struct SysCPUTimes SysCPUTimes

Processor time the machine has used since it started

Every time is in microseconds, added up across all processors, so a machine with eight processors accumulates eight seconds of time per second.

SysLoadAvg

typedef struct SysLoadAvg SysLoadAvg

How many processes have been waiting to run, averaged over time

A figure of 1.0 means one process was runnable on average. Compare it against the number of processors: on a four-processor machine a load of 4.0 is fully busy, and more than that means work is queueing up.

Enumeration Type Documentation

ProcCPUTimesValid

enum ProcCPUTimesValid

Which fields of a ProcCPUTimes the operating system reported.

Enumerator
PROCCPU_User	user
PROCCPU_System	system
PROCCPU_Started	started

Definition at line 254 of file sysinfo.h.

ProcIOInfoValid

enum ProcIOInfoValid

Which fields of a ProcIOInfo the operating system reported.

Enumerator
PROCIO_Bytes	readBytes and writeBytes
PROCIO_Ops	readOps and writeOps
PROCIO_Other	otherBytes and otherOps

Definition at line 275 of file sysinfo.h.

ProcMemInfoValid

enum ProcMemInfoValid

Which fields of a ProcMemInfo the operating system reported.

Enumerator
PROCMEM_Resident	resident
PROCMEM_PeakResident	peakResident
PROCMEM_Virtual	virtualSize
PROCMEM_PeakVirtual	peakVirtualSize
PROCMEM_Private	privateSize
PROCMEM_Swapped	swapped

Definition at line 217 of file sysinfo.h.

SysCPUTimesValid

enum SysCPUTimesValid

Which breakdown fields of a SysCPUTimes the operating system reported.

Enumerator
SYSCPU_User	user
SYSCPU_System	system
SYSCPU_Idle	idle
SYSCPU_IOWait	iowait
SYSCPU_IRQ	irq
SYSCPU_Steal	steal

Definition at line 151 of file sysinfo.h.

SysLoadAvgValid

enum SysLoadAvgValid

Which fields of a SysLoadAvg the operating system reported.

Enumerator
SYSLOAD_Load1	load1
SYSLOAD_Load5	load5
SYSLOAD_Load15	load15

Definition at line 198 of file sysinfo.h.

SysMemInfoValid

enum SysMemInfoValid

Which fields of a SysMemInfo the operating system reported.

Enumerator
SYSMEM_Phys	physTotal and physAvail
SYSMEM_Commit	commitTotal and commitAvail
SYSMEM_Swap	swapTotal and swapAvail
SYSMEM_PageSize	pageSize

Definition at line 118 of file sysinfo.h.

SysUptimeValid

enum SysUptimeValid

Which fields of a SysUptime the operating system reported.

Enumerator
SYSUP_Uptime	uptime
SYSUP_BootTime	boottime

Definition at line 185 of file sysinfo.h.

Function Documentation

procCPUSample()

bool procCPUSample	(	ProcCPUSampler *	s,
		Process *	proc,
		float64 *	pct
	)

Takes a reading and reports how busy a process has been since the last one.

Parameters

s	Sampler holding the previous reading
proc	Process to look at
pct	Receives the percentage of the machine's capacity used, from 0 to 100

Returns

true if a percentage could be worked out; false on the first call, which only establishes the starting point, and if the reading could not be taken

Example:

float64 busy;
if (procCPUSample(&sampler, proc, &busy)) {
    // the process was 'busy' percent of the machine since the last call
}

procCPUTimes()

bool procCPUTimes	(	ProcCPUTimes *	out,
		Process *	proc
	)

Reads how much processor time a process has used.

Take two readings and pass them to procCPUUsage() to find out how busy the process is.

Parameters

out	Receives the reading
proc	Process to look at

Returns

true if anything could be read

Example:

ProcCPUTimes cpu;
if (procCPUTimes(&cpu, proc)) {
    // the process has used cpu.total microseconds of processor time
}

procCPUTimesByID()

bool procCPUTimesByID	(	ProcCPUTimes *	out,
		ProcessID	pid
	)

Reads how much processor time a process has used, by process id.

Parameters

out	Receives the reading
pid	Process to look at

Returns

true if anything could be read

Example:

ProcCPUTimes cpu;
procCPUTimesByID(&cpu, procCurrentID());

procCPUUsage()

float64 procCPUUsage	(	const ProcCPUTimes *	first,
		const ProcCPUTimes *	second
	)

Works out how busy a process was between two readings.

Parameters

first	The earlier reading
second	The later reading

Returns

Percentage of the machine's capacity used, from 0 to 100; 0 if the two readings are the same

Example:

float64 busy = procCPUUsage(&before, &after);

procIOInfo()

bool procIOInfo	(	ProcIOInfo *	out,
		Process *	proc
	)

Reads how much reading and writing a process has done.

Parameters

out	Receives the reading
proc	Process to look at

Returns

true if anything could be read; false with cxerr set to CX_AccessDenied where the counters belong to another user

Example:

ProcIOInfo io;
if (procIOInfo(&io, proc)) {
    // the process has written io.writeBytes bytes
}

procIOInfoByID()

bool procIOInfoByID	(	ProcIOInfo *	out,
		ProcessID	pid
	)

Reads how much reading and writing a process has done, by process id.

Parameters

out	Receives the reading
pid	Process to look at

Returns

true if anything could be read; false with cxerr set to CX_AccessDenied where the counters belong to another user

Example:

ProcIOInfo io;
procIOInfoByID(&io, procCurrentID());

procMemInfo()

bool procMemInfo	(	ProcMemInfo *	out,
		Process *	proc
	)

Reads how much memory a process is using.

Parameters

out	Receives the reading
proc	Process to look at

Returns

true if anything could be read

Example:

ProcMemInfo mem;
if (procMemInfo(&mem, proc)) {
    // the process is holding mem.resident bytes in memory
}

procMemInfoByID()

bool procMemInfoByID	(	ProcMemInfo *	out,
		ProcessID	pid
	)

Reads how much memory a process is using, by process id.

Parameters

out	Receives the reading
pid	Process to look at

Returns

true if anything could be read

Example:

ProcMemInfo mem;
procMemInfoByID(&mem, procCurrentID());

sysCPUSample()

bool sysCPUSample	(	SysCPUSampler *	s,
		float64 *	pct
	)

Takes a reading and reports how busy the machine has been since the last one.

Parameters

s	Sampler holding the previous reading
pct	Receives the percentage of the machine's capacity used, from 0 to 100

Returns

true if a percentage could be worked out; false on the first call, which only establishes the starting point, and if the reading could not be taken

Example:

float64 busy;
if (sysCPUSample(&sampler, &busy)) {
    // the machine was 'busy' percent loaded since the last call
}

sysCPUTimes()

bool sysCPUTimes

(

SysCPUTimes *

out

)

Reads how much processor time the machine has used since it started.

Take two readings and pass them to sysCPUUsage() to find out how busy the machine is.

Parameters

out	Receives the reading

Returns

true if anything could be read

Example:

SysCPUTimes cpu;
if (sysCPUTimes(&cpu)) {
    // cpu.busy of cpu.total microseconds have been spent working
}

sysCPUUsage()

float64 sysCPUUsage	(	const SysCPUTimes *	first,
		const SysCPUTimes *	second
	)

Works out how busy the machine was between two readings.

Parameters

first	The earlier reading
second	The later reading

Returns

Percentage of the machine's capacity used, from 0 to 100; 0 if the two readings are the same

Example:

float64 busy = sysCPUUsage(&before, &after);

sysLoadAvg()

bool sysLoadAvg

(

SysLoadAvg *

out

)

Reads how many processes have been waiting to run.

Parameters

out	Receives the reading

Returns

true if anything could be read; false with cxerr set to CX_NotSupported on Windows, which keeps no such figure

Example:

SysLoadAvg load;
if (sysLoadAvg(&load)) {
    // load.load1 processes were runnable on average over the last minute
}

sysMemInfo()

bool sysMemInfo

(

SysMemInfo *

out

)

Reads how much memory the machine has and how much is free.

Parameters

out	Receives the reading

Returns

true if anything could be read

Example:

SysMemInfo mem;
if (sysMemInfo(&mem)) {
    // mem.physAvail bytes are free of mem.physTotal
}

sysUptime()

bool sysUptime

(

SysUptime *

out

)

Reads how long the machine has been running.

Parameters

out	Receives the reading

Returns

true if anything could be read

Example:

SysUptime up;
if (sysUptime(&up)) {
    // the machine has been up for timeToSeconds(up.uptime) seconds
}