442 lines
10 KiB
Plaintext
442 lines
10 KiB
Plaintext
@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.
|
|
* glibtop_proclist:: Process List.
|
|
@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],
|
|
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
|
|
|
|
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_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.
|