@node Reference Manual, , White Paper, Top

@chapter LibGTop Reference Manual

@menu

* System Dependent::            System Dependent Functions.

* Common Functions::            Common Functions.

* Library Functions::           Library Functions.

@end menu

@node System Dependent, Common Functions, Reference Manual, Reference Manual

@section System Dependent Functions

@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.

@end menu

@node glibtop_cpu, glibtop_mem, System Dependent, System Dependent

@subsection 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

@{

    guint64   flags,

        total,

        user,

        nice,

        sys,

        idle,

        iowait,

        irq,

        softirq,

        frequency,

        xcpu_total [GLIBTOP_NCPU],

        xcpu_user [GLIBTOP_NCPU],

        xcpu_nice [GLIBTOP_NCPU],

        xcpu_sys  [GLIBTOP_NCPU],

        xcpu_idle [GLIBTOP_NCPU],

        xcpu_iowait [GLIBTOP_NCPU],

        xcpu_irq [GLIBTOP_NCPU],

        xcpu_softirq [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 iowait

Number of clock ticks the system spent waiting for I/O to complete.

@item irq

Number of clock ticks the system spent servicing interrupts.

@item softirq

Number of clock ticks the system spent servicing softirqs.

@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}, @code{idle},

@code{iowait}, @code{irq} and @code{softirq}

except that they are arrays of @code{GLIBTOP_NCPU} (defined in

@file{<glibtop/cpu.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

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, System Dependent

@subsection 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

@{

    guint64   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 - cached}.

@item locked

Memory in locked segments.

@end table

@page

@node glibtop_swap, glibtop_uptime, glibtop_mem, System Dependent

@subsection 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

@{

    guint64   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, System Dependent

@subsection 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

@{

    guint64 flags;

    double uptime,

        idletime;

    guint64 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, System Dependent

@subsection 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

@{

    guint64 flags;

    double loadavg [3];

    guint64 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, System Dependent

@subsection Process List

Library function @code{glibtop_get_proclist}:

@example

@cartouche

unsigned *

glibtop_get_proclist (glibtop_proclist *buf,

                      gint64 which, gint64 arg);

unsigned *

glibtop_get_proclist_l (glibtop *server, glibtop_proclist *buf,

                        gint64 which, gint64 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

@{

    guint64   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{g_malloc} and must be freed

using @code{g_free} to avoid a memory leak.

@page

@node glibtop_proc_state, glibtop_proc_uid, glibtop_proclist, System Dependent

@subsection 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/procstate.h>}:

@example

@cartouche

typedef struct _glibtop_proc_state      glibtop_proc_state;

struct _glibtop_proc_state

@{

    guint64 flags;

    char cmd[40];

@ifset LIBGTOP-1-1

    unsigned state;

@end ifset

@ifclear LIBGTOP-1-1

    char state;

@end ifclear

    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

@ifset LIBGTOP-1-1

Process state (see the constants defined below).

@end ifset

@ifclear LIBGTOP-1-1

Process state ('R' = running, 'S' = sleeping, 'D' = uninterruptible,

'Z' = zombie, 'T' = stopped, 'I' = idle).

This was changed to an @code{unsigned} bitfield in LibGTop 1.1.x where there

are also some constants for it.

@end ifclear

@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

@ifset LIBGTOP-1-1

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

#define GLIBTOP_PROCESS_DEAD                    64

@end cartouche

@end example

@end ifset

@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, System Dependent

@subsection 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

@{

    guint64 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/procuid.h>}).

@end table

@page

@node glibtop_proc_mem, glibtop_proc_time, glibtop_proc_uid, System Dependent

@subsection 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

@{

    guint64   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{A word 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, System Dependent

@subsection Process Time information

Library function @code{glibtop_get_proc_time}:

@example

@cartouche

void

glibtop_get_proc_time (glibtop_proc_time *buf, pid_t pid);

void

glibtop_get_proc_time_l (glibtop *server, glibtop_proc_time *buf,

                         pid_t pid);

@end cartouche

@end example

Declaration of @code{glibtop_proc_time} in @file{<glibtop/proctime.h>}:

@example

@cartouche

typedef struct _glibtop_proc_time       glibtop_proc_time;

struct _glibtop_proc_time

@{

    guint64   flags,

        start_time,

        rtime,

        utime,

        stime,

        cutime,

        cstime,

        timeout,

        it_real_value,

        frequency,

        xcpu_utime [GLIBTOP_NCPU],

        xcpu_stime [GLIBTOP_NCPU],

        xcpu_flags;

@};

@end cartouche

@end example

@table @code

@item start_time

Start time of process in seconds since the epoch

@item rtime

Real time accumulated by process (should be @code{utime} + @code{stime})

@item utime

User-mode CPU time accumulated by process

@item stime

Kernel-mode CPU time accumulated by process

@item cutime

Cumulative utime of process and reaped children

@item cstime

Cumulative stime of process and reaped children

@item timeout

The time (in jiffies) of the process's next timeout

@item it_real_value

The time (in jiffies) before the next SIGALRM is sent to the process due

to an interval timer.

@item frequency

Tick frequency

@item xcpu_utime

SMP user-mode CPU time accumulated by process

@item xcpu_stime

SMP kernel-mode CPU time accumulated by process

@end table

Please note that under Linux, @code{start_time} value may be strange.

Linux kernel defines @code{INITIAL_JIFFIES} which implies a time

shift. Because @code{INITIAL_JIFFIES} is not user-space defined, we

cannot use it to compute accurate @code{start_time}. On Linux2.6,

@code{INITIAL_JIFFIES} is 300 so @code{start_time} is always 3s

different from real start time of the given process. You may also get

shift results if your system clock is not synchronised with your

hardware clock. See @samp{man hwclock}.