libgtop/doc/reference.texi

@node Reference Manual, , About, Top
@chapter LibGTop Reference Manual

@menu
* glibtop_cpu::                 CPU Usage.
* glibtop_mem::                 Memory Usage.
* glibtop_swap::                Swap Usage.
* glibtop_uptime::              System Uptime.
* glibtop_loadavg::             Load Average.
@end menu

@node glibtop_cpu, glibtop_mem, Reference Manual, Reference Manual
@section CPU Usage

Declaration of @code{glibtop_cpu} in @file{<glibtop/cpu.h}:

@example
@cartouche
typedef struct _glibtop_cpu     glibtop_cpu;

struct _glibtop_cpu
@{
    u_int64_t   flags,
        total,
        user,
        nice,
        sys,
        idle,
        frequency,
        xcpu_total [GLIBTOP_NCPU],
        xcpu_user [GLIBTOP_NCPU],
        xcpu_nice [GLIBTOP_NCPU],
        xcpu_sys  [GLIBTOP_NCPU],
        xcpu_idle [GLIBTOP_NCPU],
        xcpu_flags;
@};
@end cartouche
@end example

All CPU units are measured in @dfn{jiffies} which are normally 1/100th of a
second (in which case @code{frequency} equals 100), but can also be in any
other unit. To get seconds, divide them by @code{frequency}.

@table @code
@item total
Number of clock ticks since system boot.

@item user
Number of clock ticks the system spent in user mode.

@item nice
Number of clock ticks the system spent in user mode (nice).

@item sys
Number of clock ticks the system spent in system mode.

@item idle
Number of clock ticks the system spent in the idle task.

@item frequency
Tick frequency (default is 100).

@end table

The @samp{xcpu_} values are for SMP systems - they are the same than
@code{total}, @code{user}, @code{nice}, @code{sys} and @code{idle}
except that they are arrays of @code{GLIBTOP_NCPU} (defined in
@file{<glibtop/limits.h>}) elements and contain one value for each CPU
in the system.

@table @code
@item xcpu_flags
This is interpreted as a bit-field: on systems like Solaris, not all CPUs
need to be running all the time, so we set the corresponding bit for each
CPU that is currently running.
@end table

@node glibtop_mem, glibtop_swap, glibtop_cpu, Reference Manual
@section Memory Usage

Declaration of @code{glibtop_mem} in @file{<glibtop/mem.h}:

@example
@cartouche
typedef struct _glibtop_mem     glibtop_mem;

struct _glibtop_mem
@{
    u_int64_t   flags,
        total,
        used,
        free,
        shared,
        buffer,
        cached,
        user,
        locked;
@};
@end cartouche
@end example

Unless explicitly stated otherwise, all memory units are in bytes.

@table @code
@item total
Total physical memory.

@item used
Used memory size.

@item free
Free memory size.

@item shared
Shared memory size.

This are both segments that are @code{mmap()}ed with @code{MAP_SHARED} and
IPC Shared Memory segments.

@item buffer
Size of buffers.

@item cached
Size of cached memory.

@item user
Memory used from user processes.

This is normally @code{total - free - shared - buffer}.

@item locked
Memory in locked segments.

@end table

@node glibtop_swap, glibtop_uptime, glibtop_mem, Reference Manual
@section Swap Usage

Declaration of @code{glibtop_swap} in @file{<glibtop/swap.h}:

@example
@cartouche
typedef struct _glibtop_swap    glibtop_swap;

struct _glibtop_swap
@{
    u_int64_t   flags,
        total,
        used,
        free,
        pagein,
        pageout;
@};
@end cartouche
@end example

The following units are in bytes.

@table @code
@item total
Total swap space in the system.

@item used
Used swap space.

@item free
Free swap space.
@end table

You can use @code{pagein} and @code{pageout} to get some measure about how
much the system is swapping at the moment. They're increased each time a page
is swapped in or out, so you need to save this values, wait a little bit, get
them again and then compare the two results to find out how much the system
swapped in the meantime.

@table @code
@item pagein
Total number of swap pages that have been brought in since system boot

@item pageout
Total number of swap pages that have been brought out since system boot

@end table

@node glibtop_uptime, glibtop_loadavg, glibtop_swap, Reference Manual
@section Uptime

Declaration of @code{glibtop_uptime} in @file{<glibtop/uptime.h}:

@example
@cartouche
typedef struct _glibtop_uptime  glibtop_uptime;

struct _glibtop_uptime
{
    u_int64_t flags;
    double uptime,
        idletime;
    u_int64_t boot_time;
};
@end cartouche
@end example

When porting LibGTop to a new system, you only need to implement @code{uptime}
and @code{idletime} if there's a faster or better way to obtain them as using
@code{glibtop_cpu} for it. Look at @file{sysdeps/freebsd/uptime.c} for an
example on how to obtain them using @code{glibtop_cpu}.

@table @code
@item uptime
Time in seconds since system boot.

@item idletime
Time in seconds the system spent in the idle task since system boot.
@end table

The following one was from a request on the @samp{linux-kernel} mailing list;
on a laptop with advanced power management @code{glibtop_cpu.total} may not
reflect the correct boot time of the system if the power was turned off by
means of APM in the meantime.

@table @code
@item boot_time
Time of last system boot in seconds since the epoch.
@end table

@node glibtop_loadavg,  , glibtop_uptime, Reference Manual
@section Load Average

Declaration of @code{glibtop_loadavg} in @file{<glibtop/loadavg.h}:

@example
@cartouche
typedef struct _glibtop_loadavg glibtop_loadavg;

struct _glibtop_loadavg
{
    u_int64_t flags;
    double loadavg [3];
    u_int64_t nr_running,
        nr_tasks,
        last_pid;
};
@end cartouche
@end example

@table @code
@item loadavg

Number of jobs running simultaneously averaged over 1, 5 and 15 minutes.

@end table

The following fields are Linux specific and deprecated. You don't need to
implement them when porting LibGTop to a new system as they may be removed
in a future version.

@table @code
@item nr_running
Number of tasks currently running.

@item nr_tasks
Total number of tasks.

@item last_pid
Last PID.
@end table