path: root/doc/reference.texi

@node Reference Manual, , White Paper, 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.
* glibtop_proclist::            Process List.
* glibtop_proc_state::          Process State.
* glibtop_proc_uid::            Process UID and TTY Information.
* glibtop_proc_mem::            Process Memory Information.
* glibtop_proc_time::           Process Time Information.
* glibtop_proc_signal::         Process Signal Information.
* glibtop_proc_kernel::         Process Kernel Data Information.
* glibtop_proc_segment::        Process Segment Information.
* glibtop_proc_args::           Process Arguments.
* glibtop_proc_map::            Process Memory Maps.
* glibtop_netload::             Network Load.
* glibtop_ppp::                 PPP Usage.
* glibtop_mountlist::           Mount List.
* glibtop_fsusage::             File System Usage.
@end menu

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

Library function @code{glibtop_get_cpu}:

@example
@cartouche
void glibtop_get_cpu (glibtop_cpu *buf);
void glibtop_get_cpu_l (glibtop *server, glibtop_cpu *buf);
@end cartouche
@end example

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],
@ifset LIBGTOP-1-1
        xcpu_idle [GLIBTOP_NCPU],
        xcpu_flags;
@end ifset
@ifclear LIBGTOP-1-1
        xcpu_idle [GLIBTOP_NCPU];
@end ifclear
@};
@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.

@ifset LIBGTOP-1-1
@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
@end ifset

Please note that all of the cpu values are absolute values measured in
certain units (to get seconds, divide them by @code{frequency}) since system
boot. To get percentual values, you need to call @code{glibtop_cpu}, save the
result, wait some time and then call it again and divide the differences of
the two values by the time you have waited.

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

Library function @code{glibtop_get_mem}:

@example
@cartouche
void glibtop_get_mem (glibtop_mem *buf);
void glibtop_get_mem_l (glibtop *server, glibtop_mem *buf);
@end cartouche
@end example

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

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

Library function @code{glibtop_get_swap}:

@example
@cartouche
void glibtop_get_swap (glibtop_swap *buf);
void glibtop_get_swap_l (glibtop *server, glibtop_swap *buf);
@end cartouche
@end example

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

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

Library function @code{glibtop_get_uptime}:

@example
@cartouche
void glibtop_get_uptime (glibtop_uptime *buf);
void glibtop_get_uptime_l (glibtop *server, glibtop_uptime *buf);
@end cartouche
@end example

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

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

Library function @code{glibtop_get_loadavg}:

@example
@cartouche
void glibtop_get_loadavg (glibtop_loadavg *buf);
void glibtop_get_loadavg_l (glibtop *server, glibtop_loadavg *buf);
@end cartouche
@end example

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

@page
@node glibtop_proclist, glibtop_proc_state, glibtop_loadavg, Reference Manual
@section Process List

Library function @code{glibtop_get_proclist}:

@example
@cartouche
unsigned *
glibtop_get_proclist (glibtop_proclist *buf,
                      int64_t which, int64_t arg);

unsigned *
glibtop_get_proclist_l (glibtop *server, glibtop_proclist *buf,
                        int64_t which, int64_t arg);
@end cartouche
@end example

Constants for the @code{which} argument:

@example
@cartouche
#define GLIBTOP_KERN_PROC_ALL           0
#define GLIBTOP_KERN_PROC_PID           1
#define GLIBTOP_KERN_PROC_PGRP          2
#define GLIBTOP_KERN_PROC_SESSION       3
#define GLIBTOP_KERN_PROC_TTY           4
#define GLIBTOP_KERN_PROC_UID           5
#define GLIBTOP_KERN_PROC_RUID          6

#define GLIBTOP_KERN_PROC_MASK          15

#define GLIBTOP_EXCLUDE_IDLE            0x1000
#define GLIBTOP_EXCLUDE_SYSTEM          0x2000
#define GLIBTOP_EXCLUDE_NOTTY           0x4000
@end cartouche
@end example

Declaration of @code{glibtop_proclist} in @file{<glibtop/proclist.h>}:

@example
@cartouche
typedef struct _glibtop_proclist        glibtop_proclist;

struct _glibtop_proclist
@{
    u_int64_t   flags,
        number,
        total,
        size;
@};
@end cartouche
@end example

This function returns a list of all or a selected subset of all running
processes. You can use the @code{which} and @code{arg} arguments to
specify which processes should be returned.

You can use the following values for the @code{which} argument:

@table @code
@item GLIBTOP_KERN_PROC_ALL
Return information about all processes (the @code{arg} argument is ignored).

@item GLIBTOP_KERN_PROC_PID
Return information about all process with the pid @var{PID} which is passed
in @code{arg}. You can use this to find out whether some process still exists.

@item GLIBTOP_KERN_PROC_PGRP
Return all processes in process group @var{PGRP} which is passed in
@code{arg}.

@item GLIBTOP_KERN_PROC_SESSION
Return all processes in session @var{SESSION} which is passed in @code{arg}.

@item GLIBTOP_KERN_PROC_TTY
Return all processes which have the controlling tty @var{TTY} which is passed
in @code{arg} (@var{TTY} is interpreted as device number).

@item GLIBTOP_KERN_PROC_UID
Return all processes with effective uid @var{UID} which is passed in @code{arg}.

@item GLIBTOP_KERN_PROC_RUID
Return all processes with real uid @var{RUID} which is passed in @code{arg}.

@end table

You can alter the list of returned processes by using a binary OR of
@code{which} and the following constants:

@table @code
@item GLIBTOP_EXCLUDE_IDLE
Exclude idle processes.
@item GLIBTOP_EXCLUDE_SYSTEM
Exclude system processes.
@item GLIBTOP_EXCLUDE_NOTTY
Exclude processes without a controlling terminal.
@end table

The return value of @code{glibtop_get_proclist} is either @code{NULL} on
error or a @code{unsigned *} list of pids. Additionally, the following fields
of @code{glibtop_proclist} are set:

@table @code
@item number
Number of entries in the returned list.

@item total
Total size of the returned list (this equals @code{number * size}).

@item size
Size of a single entry in the returned list
(this equals @code{sizeof (unsigned)}).
@end table

The returned list is allocated using @code{glibtop_malloc} and must be freed
using @code{glibtop_free} to avoid a memory leak.

@page
@node glibtop_proc_state, glibtop_proc_uid, glibtop_proclist, Reference Manual
@section Process State

Library function @code{glibtop_get_proc_state}:

@example
@cartouche
void
glibtop_get_proc_state (glibtop_proc_state *buf, pid_t pid);

void
glibtop_get_proc_state_l (glibtop *server, glibtop_proc_state *buf,
                          pid_t pid);
@end cartouche
@end example

Declaration of @code{glibtop_proc_state} in @file{<glibtop/proc_state.h>}:

@example
@cartouche
typedef struct _glibtop_proc_state      glibtop_proc_state;

struct _glibtop_proc_state
@{
    u_int64_t flags;
    char cmd[40];
    unsigned state;
    int uid,
        gid,
        ruid,
        rgid;
    int has_cpu,
        processor,
        last_processor;

@};
@end cartouche
@end example

@table @code
@item cmd
Basename of the executable file in the call to @code{exec}.
@item state
Process state (see the constants defined below).
@end table

When porting LibGTop, please @emph{try hard} to implement the following
fields. For security reasons, it is @strong{very important} that you
@strong{only} set the @code{flags} bits for those fields if their
@strong{values are correct}.

@table @code
@item uid
Effective UID of the process.
@item gid
Effective GID of the process.
@item ruid
Real UID of the process.
@item rgid
Read GID of the process.
@end table

The following fields are for SMP systems:

@table @code
@item has_cpu
This is either 0 or 1 depending on whether the process currently has a CPU
or not.

@item processor
This is the processor id of the CPU this process is currently running on
(which can be used as index in the @samp{xcpu_} fields of @code{glibtop_cpu}
for instance; since zero is a valid processor id, you must check @code{has_cpu}
in this case to find out whether the process really has a CPU).

@item last_processor
The is the processor id of the CPU the process was last running on.
@end table

There are some constants for the @code{state} field:

@example
@cartouche
#define GLIBTOP_PROCESS_RUNNING                 1
#define GLIBTOP_PROCESS_INTERRUPTIBLE           2
#define GLIBTOP_PROCESS_UNINTERRUPTIBLE         4
#define GLIBTOP_PROCESS_ZOMBIE                  8
#define GLIBTOP_PROCESS_STOPPED                 16
#define GLIBTOP_PROCESS_SWAPPING                32
@end cartouche
@end example

@table @code
@item GLIBTOP_PROCESS_RUNNING
The process is currently running.
@item GLIBTOP_PROCESS_INTERRUPTIBLE
The process is currently in an interruptible sleep.
@item GLIBTOP_PROCESS_UNINTERRUPTIBLE
The process is currently in uninterruptible sleep
(the so-called @dfn{disk sleep}).
@item GLIBTOP_PROCESS_ZOMBIE
The process is a zombie.
@item GLIBTOP_PROCESS_STOPPED
The process is currently stopped (received @code{SIGSTOP}
or attached to a debugger).
@item GLIBTOP_PROCESS_SWAPPING
The process is currently swapping.
@end table

@page
@node glibtop_proc_uid, glibtop_proc_mem, glibtop_proc_state, Reference Manual
@section Process UID and TTY information

Library function @code{glibtop_get_proc_uid}:

@example
@cartouche
void
glibtop_get_proc_uid (glibtop_proc_uid *buf, pid_t pid);

void
glibtop_get_proc_uid_l (glibtop *server, glibtop_proc_uid *buf,
                        pid_t pid);
@end cartouche
@end example

Declaration of @code{glibtop_proc_uid} in @file{<glibtop/procuid.h>}:

@example
@cartouche
typedef struct _glibtop_proc_uid        glibtop_proc_uid;

struct _glibtop_proc_uid
@{
    u_int64_t flags;
    int uid,
        euid,
        gid,
        egid,
        suid,
        sgid,
        fsuid,
        fsgid,
        pid,
        ppid,
        pgrp,
        session,
        tty,
        tpgid,
        priority,
        nice,
        ngroups,
        groups [GLIBTOP_MAX_GROUPS];
@};
@end cartouche
@end example

@table @code
@item uid
User ID
@item euid
Effective User ID
@item gid
Group ID
@item egid
Effective Group ID
@item pid
Process ID
@item ppid
PID of parent process
@item pgrp
Process group ID
@item session
Session ID
@item tty
Full device number of controlling terminal
@item tpgid
Terminal process group ID
@item priority
Kernel scheduling priority.
@item nice
Standard unix nice level of process.
@item ngroups
Number of additional process groups.
@item groups
Array of additional process groups@*
(@code{GLIBTOP_MAX_GROUPS} is defined in @file{<glibtop/limits.h>}).
@end table

@page
@node glibtop_proc_mem, glibtop_proc_time, glibtop_proc_uid, Reference Manual
@section Process Memory information

Library function @code{glibtop_get_proc_mem}:

@example
@cartouche
void
glibtop_get_proc_mem (glibtop_proc_mem *buf, pid_t pid);

void
glibtop_get_proc_mem_l (glibtop *server, glibtop_proc_mem *buf,
                        pid_t pid);
@end cartouche
@end example

Declaration of @code{glibtop_proc_mem} in @file{<glibtop/procmem.h>}:

@example
@cartouche
typedef struct _glibtop_proc_mem        glibtop_proc_mem;

struct _glibtop_proc_mem
@{
    u_int64_t   flags,
        size,
        vsize,
        resident,
        share,
        rss,
        rss_rlim;
@};
@end cartouche
@end example

@table @code
@item size
Total number of pages of memory.
@item vsize
Number of pages of virtual memory.
@item resident
Number of residnet set (non-swapped) pages.
@item share
Number of pages of shared (mmap'd) memory.
@item rss
Number of pages the process has in real memory, minus 3 for administrative
purposes.

This is just the pages which count towards text, data, or stack space.
This does not include pages which have not been demand-loaded in, or which
are swapped out.
@item rss_rlim
Current limit in bytes on the rss of the process (usually 2,147,483,647).
@end table

The description above is taken from the manual page of the @file{/proc}
filesystem under Linux and is a little bit confusing, so I make this clear
here. 

@strong{Note for people porting LibGTop to other systems:}
Every operating system has its own idea about the memory usage of a process
and also system utilities like @code{ps} show different things on different
systems.

Nevertheless, we should try to make LibGTop as system independent as possible,
so I give you some hints here how @code{glibtop_get_proc_mem} should work. 

@itemize @bullet
@item
When you use @code{mmap} with either @code{MAP_SHARED} or @code{MAP_PRIVATE},
this should only affect the @code{vsize} of the process and none of its
@code{size}, @code{resident}, @code{shared} and @code{rss} sizes.

@item
As soon as you read some of the @code{mmap()}ed pages, they will be demand-
oaded and thus count towards the @code{size} of the process.

Also - we assume there is enough free memory - they are resident in memory
until they get stolen or swapped out and thus increase the @code{resident} and
@code{rss} sizes of the process.

@item
If the process has used @code{MAP_SHARED} and another process attaches the
same file also @code{MAP_SHARED}, some of the pages are shared with this
process and thus increase the @code{shared} sizes of both processes.

@item
If the process has used @code{MAP_PRIVATE} and writes to the @code{mmap()}ed
pages, the only difference to reading from them is that they get dirty and
cannot be stolen any longer but will get swapped out.

@item
When memory gets rare, clean pages are normally stolen, which decreases the
@code{size}, @code{resident}, @code{shared} and @code{rss} sizes of the process.

@item
When dirty pages are swapped out, this will not decrease the @code{size} of the
process but only its @code{resident} and @code{rss} sizes (dirty pages cannot
be shared).

@item
The @code{vsize} of a process can @emph{only} be changed by the process
itself when it requests or frees memory but @emph{never} due to swapping
activity of the system.

@item
If the @code{shared} size changes, this @emph{only} means that the number of
pages that are currently shared with other processes has changed; if this
happens, this will @emph{never} affect any of the other sizes of the process.
@end itemize

The hints above describe how it works under Linux - but we should try to make
@code{glibtop_get_proc_mem} show the same behavior under every other system.

@page
@node glibtop_proc_time, glibtop_proc_signal, glibtop_proc_mem, Reference Manual
@section Process Time information

[Not yet written.]

@page
@node glibtop_proc_signal, glibtop_proc_kernel, glibtop_proc_time, Reference Manual
@section Process Signal information

[Not yet written.]

@page
@node glibtop_proc_kernel, glibtop_proc_segment, glibtop_proc_signal, Reference Manual
@section Process Kernel Data information

[Not yet written.]

@page
@node glibtop_proc_segment, glibtop_proc_args, glibtop_proc_kernel, Reference Manual
@section Process Segment information

[Not yet written.]

@page
@node glibtop_proc_args, glibtop_proc_map, glibtop_proc_segment, Reference Manual
@section Process Arguments

[Not yet written.]

@page
@node glibtop_proc_map, glibtop_netload, glibtop_proc_args, Reference Manual
@section Process Memory Maps

[Not yet written.]

@page
@node glibtop_netload, glibtop_ppp, glibtop_proc_map, Reference Manual
@section Network Load

[Not yet written.]

@page
@node glibtop_ppp, glibtop_mountlist, glibtop_netload, Reference Manual
@section PPP Statistics

[Not yet written.]

@page
@node glibtop_mountlist, glibtop_fsusage, glibtop_ppp, Reference Manual
@section Mount List

[Not yet written.]

@page
@node glibtop_fsusage,  , glibtop_mountlist, Reference Manual
@section File System Usage

[Not yet written.]