gnome-hackers.shtml

Using Libgtop in the Gnome Project
Legal Notice:

This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

For more details see the file COPYING in the source distribution of libgtop.

Abstract

$Id: gnome-hackers.shtml,v 1.1.1.1 1999/01/24 23:00:00 martin Exp $

This is a short introduction in how to use libgtop in the GNOME project. It describes the additional options configure takes and the information stored in the automatically generated libgtopConf.sh configuration script.

NOTE:

Documentation about the new table () function can be found here:
Chapter 2. Function Reference List

glibtop_get_cpu() – CPU Usage

Automatically generated description:

CPU Usage
Automatically generated function synopsis:

#include
#include
void glibtop_get_cpu (glibtop_cpu *cpu)

void glibtop_get_cpu_l (glibtop *server, glibtop_cpu *cpu)

Automatically generated declaration of _glibtop_cpu:

typedef struct _glibtop_cpu glibtop_cpu;

struct _glibtop_cpu
{
u_int64_t flags;
u_int64_t total, /* GLIBTOP_CPU_TOTAL */
user, /* GLIBTOP_CPU_USER */
nice, /* GLIBTOP_CPU_NICE */
sys, /* GLIBTOP_CPU_SYS */
idle, /* GLIBTOP_CPU_IDLE */
frequency; /* GLIBTOP_CPU_FREQUENCY */
};
Automatically generated descriptions of _glibtop_cpu:

total
The number of jiffies (1/100ths of a second) since system boot

user
The number of jiffies (1/100ths of a second) that the system spent in user mode

nice
The number of jiffies (1/100ths of a second) that the system spent in user mode with low priority (nice)

sys
The number of jiffies (1/100ths of a second) that the system spent in system mode

idle
The number of jiffies (1/100ths of a second) that the system spend in the idle task

frequency
All of the above values are in jiffies (1/100ths of a second) unless otherwise stated in this field (i.e. ‘frequency != 100’)

glibtop_get_mem() – Memory Usage

Automatically generated description:

Memory Usage
Automatically generated function synopsis:

#include
#include
void glibtop_get_mem (glibtop_mem *mem)

void glibtop_get_mem_l (glibtop *server, glibtop_mem *mem)

Automatically generated declaration of _glibtop_mem:

typedef struct _glibtop_mem glibtop_mem;

struct _glibtop_mem
{
u_int64_t flags;
u_int64_t total, /* GLIBTOP_MEM_TOTAL */
used, /* GLIBTOP_MEM_USED */
free, /* GLIBTOP_MEM_FREE */
shared, /* GLIBTOP_MEM_SHARED */
buffer, /* GLIBTOP_MEM_BUFFER */
cached, /* GLIBTOP_MEM_CACHED */
user, /* GLIBTOP_MEM_USER */
locked; /* GLIBTOP_MEM_LOCKED */
};
Automatically generated descriptions of _glibtop_mem:

total
Total physical memory in kB

used
Used memory size in kB

free
Free memory size in kB

shared
Shared memory size in kB

buffer
Size of buffers kB

cached
Size of cached memory in kB

user
Memory used from user processes in kB

locked
Memory in locked pages in kB

glibtop_get_swap() – Swap Usage

Automatically generated description:

Swap Usage
Automatically generated function synopsis:

#include
#include
void glibtop_get_swap (glibtop_swap *swap)

void glibtop_get_swap_l (glibtop *server, glibtop_swap *swap)

Automatically generated declaration of _glibtop_swap:

typedef struct _glibtop_swap glibtop_swap;

struct _glibtop_swap
{
u_int64_t flags;
u_int64_t total, /* GLIBTOP_SWAP_TOTAL */
used, /* GLIBTOP_SWAP_USED */
free, /* GLIBTOP_SWAP_FREE */
pagein, /* GLIBTOP_SWAP_PAGEIN */
pageout; /* GLIBTOP_SWAP_PAGEOUT */
};
Automatically generated descriptions of _glibtop_swap:

total
Total Swap Space

used
Used Swap Space

free
Free Swap Space

pagein
Total number of swap pages that have been brought in since system boot

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

glibtop_get_uptime() – System Uptime

Automatically generated description:

System Uptime
Automatically generated function synopsis:

#include
#include
void glibtop_get_uptime (glibtop_uptime *uptime)

void glibtop_get_uptime_l (glibtop *server, glibtop_uptime *uptime)

Automatically generated declaration of _glibtop_uptime:

typedef struct _glibtop_uptime glibtop_uptime;

struct _glibtop_uptime
{
u_int64_t flags;
double uptime, /* GLIBTOP_UPTIME_UPTIME */
idletime; /* GLIBTOP_UPTIME_IDLETIME */
};
Automatically generated descriptions of _glibtop_uptime:

uptime
Time in seconds since system boot

idletime
Time in seconds the system spent in the idle task since system boot

NOTE:

You can calculate this from the CPU usage (this one is taken from the FreeBSD port):

#include
#include
#include

#include

#include

static const unsigned long _glibtop_sysdeps_uptime =
(1 << GLIBTOP_UPTIME_UPTIME) + (1 << GLIBTOP_UPTIME_IDLETIME); static const unsigned long _required_cpu_flags = (1 << GLIBTOP_CPU_TOTAL) + (1 << GLIBTOP_CPU_IDLE) + (1 << GLIBTOP_CPU_FREQUENCY); void glibtop_get_uptime_p (glibtop *server, glibtop_uptime *buf) { glibtop_cpu cpu; glibtop_init_p (server, GLIBTOP_SYSDEPS_UPTIME, 0); memset (buf, 0, sizeof (glibtop_uptime)); /* We simply calculate it from the CPU usage. */ glibtop_get_cpu_p (server, &cpu); /* Make sure all required fields are present. */ if ((cpu.flags & _required_cpu_flags) != _required_cpu_flags) return; /* Calculate values. */ buf->uptime = (double) cpu.total / (double) cpu.frequency;
buf->idletime = (double) cpu.idle / (double) cpu.frequency;

buf->flags = _glibtop_sysdeps_uptime;
}
glibtop_get_loadavg() – Load Averange

Automatically generated description:

Load Averange
Automatically generated function synopsis:

#include
#include
void glibtop_get_loadavg (glibtop_loadavg *loadavg)

void glibtop_get_loadavg_l (glibtop *server, glibtop_loadavg *loadavg)

Automatically generated declaration of _glibtop_loadavg:

typedef struct _glibtop_loadavg glibtop_loadavg;

struct _glibtop_loadavg
{
u_int64_t flags;
u_int64_t nr_running, /* GLIBTOP_LOADAVG_NR_RUNNING */
nr_tasks, /* GLIBTOP_LOADAVG_NR_TASKS */
last_pid; /* GLIBTOP_LOADAVG_LAST_PID */
double loadavg [3]; /* GLIBTOP_LOADAVG_LOADAVG [3] */
};
Automatically generated descriptions of _glibtop_loadavg:

loadavg [3]
Number of jobs running simultaneously averaged over 1, 5 and 15 minutes

nr_running
Number of tasks currently running

nr_tasks
Total number of tasks

last_pid
Last PID

glibtop_get_shm_limits() – Shared Memory Limits

Automatically generated description:

Shared Memory Limits
Automatically generated function synopsis:

#include
#include
void glibtop_get_shm_limits (glibtop_shm_limits *shm_limits)

void glibtop_get_shm_limits_l (glibtop *server, glibtop_shm_limits *shm_limits)

Automatically generated declaration of _glibtop_shm_limits:

typedef struct _glibtop_shm_limits glibtop_shm_limits;

struct _glibtop_shm_limits
{
u_int64_t flags;
u_int64_t shmmax, /* GLIBTOP_SHM_LIMITS_SHMMAX */
shmmin, /* GLIBTOP_SHM_LIMITS_SHMMIN */
shmmni, /* GLIBTOP_SHM_LIMITS_SHMMNI */
shmseg, /* GLIBTOP_SHM_LIMITS_SHMSEG */
shmall; /* GLIBTOP_SHM_LIMITS_SHMALL */
};
Automatically generated descriptions of _glibtop_shm_limits:

shmmax
Max segment size

shmmin
Min segment size

shmmni
Max number of segments

shmseg
Max shared segments per process

shmall
Max total shared memory

glibtop_get_msg_limits() – Message Queue Limits

Automatically generated description:

Message Queue Limits
Automatically generated function synopsis:

#include
#include
void glibtop_get_msg_limits (glibtop_msg_limits *msg_limits)

void glibtop_get_msg_limits_l (glibtop *server, glibtop_msg_limits *msg_limits)

Automatically generated declaration of _glibtop_msg_limits:

typedef struct _glibtop_msg_limits glibtop_msg_limits;

struct _glibtop_msg_limits
{
u_int64_t flags;
u_int64_t msgpool, /* GLIBTOP_MSG_LIMITS_MSGPOOL */
msgmap, /* GLIBTOP_MSG_LIMITS_MSGMAP */
msgmax, /* GLIBTOP_MSG_LIMITS_MSGMAX */
msgmnb, /* GLIBTOP_MSG_LIMITS_MSGMNB */
msgmni, /* GLIBTOP_MSG_LIMITS_MSGMNI */
msgssz, /* GLIBTOP_MSG_LIMITS_MSGSSZ */
msgtql; /* GLIBTOP_MSG_LIMITS_MSGTQL */
};
Automatically generated descriptions of _glibtop_msg_limits:

msgpool
Size in kilobytes of message pool

msgmap
Number of entries in message map

msgmax
Max size of message

msgmnb
Default max size of queue

msgmni
Max queues system wide

msgssz
Message segment size

msgtql
Number of system message headers

glibtop_get_sem_limits() – Semaphore Set Limits

Automatically generated description:

Semaphore Set Limits
Automatically generated function synopsis:

#include
#include
void glibtop_get_sem_limits (glibtop_sem_limits *sem_limits)

void glibtop_get_sem_limits_l (glibtop *server, glibtop_sem_limits *sem_limits)

Automatically generated declaration of _glibtop_sem_limits:

typedef struct _glibtop_sem_limits glibtop_sem_limits;

struct _glibtop_sem_limits
{
u_int64_t flags;
u_int64_t semmap, /* GLIBTOP_SEM_LIMITS_SEMMAP */
semmni, /* GLIBTOP_SEM_LIMITS_SEMMNI */
semmns, /* GLIBTOP_SEM_LIMITS_SEMMNS */
semmnu, /* GLIBTOP_SEM_LIMITS_SEMMNU */
semmsl, /* GLIBTOP_SEM_LIMITS_SEMMSL */
semopm, /* GLIBTOP_SEM_LIMITS_SEMOPM */
semume, /* GLIBTOP_SEM_LIMITS_SEMUME */
semusz, /* GLIBTOP_SEM_LIMITS_SEMUSZ */
semvmx, /* GLIBTOP_SEM_LIMITS_SEMVMX */
semaem; /* GLIBTOP_SEM_LIMITS_SEMAEM */
};
Automatically generated descriptions of _glibtop_sem_limits:

semmap
Number of entries in semaphore map

semmni
Max number of arrays

semmns
Max semaphores system wide

semmnu
Number of undo structures system wide

semmsl
Max semaphores per array

semopm
Max ops per semop call

semume
Max number of undo entries per process

semusz
sizeof struct sem_undo

semvmx
Semaphore max value

semaem
Adjust on exit max value

glibtop_get_proclist() – List of running Processes

Automatically generated description:

List of running Processes
Automatically generated function synopsis:

#include
#include
unsigned * glibtop_get_proclist (glibtop_proclist *proclist)

unsigned * glibtop_get_proclist_l (glibtop *server, glibtop_proclist *proclist, long which, long arg)

Automatically generated declaration of _glibtop_proclist:

typedef struct _glibtop_proclist glibtop_proclist;

struct _glibtop_proclist
{
u_int64_t flags;
u_int64_t number, /* GLIBTOP_PROCLIST_NUMBER */
total, /* GLIBTOP_PROCLIST_TOTAL */
size; /* GLIBTOP_PROCLIST_SIZE */
};
Automatically generated descriptions of _glibtop_proclist:

number
Number of list elements

total
Total size of list

size
Size of a single list element

This functions takes the following additional parameters:

which
You can use the following constants (defined in glibtop/proclist.h) to tell glibtop_get_proclist () which processes to fetch:

GLIBTOP_KERN_PROC_ALL
Fetch all processes.

GLIBTOP_KERN_PROC_PID
Fetch process with pid arg or nothing if no such process exists.

GLIBTOP_KERN_PROC_PGRP
Fetch only processes which are in process group arg.

GLIBTOP_KERN_PROC_SESSION
Fetch only processes with session id arg.

GLIBTOP_KERN_PROC_TTY
Fetch only processes with tty id arg.

GLIBTOP_KERN_PROC_UID
Fetch only processes with effective user id arg.

GLIBTOP_KERN_PROC_RUID
Fetch only processes with real user id arg.

You can use one or more of the following flags (with a logical or) to hide some processes:

GLIBTOP_EXCLUDE_IDLE
Don’t fetch idle processes.

GLIBTOP_EXCLUDE_SYSTEM
Don’t fetch system processes.

GLIBTOP_EXCLUDE_NOTTY
Don’t fetch processes that have no controlling tty.

arg
Additional argument depending upon the which argument.

This function returns a pointer (of type unsigned *) to the list of process ids.

You have to manually glibtop_free () this pointer once finished with it.

glibtop_get_proc_state() – Process Status information

Automatically generated description:

Process Status information
Automatically generated function synopsis:

#include
#include
void glibtop_get_proc_state (glibtop_proc_state *proc_state)

void glibtop_get_proc_state_l (glibtop *server, glibtop_proc_state *proc_state, pid_t pid)

Automatically generated declaration of _glibtop_proc_state:

typedef struct _glibtop_proc_state glibtop_proc_state;

struct _glibtop_proc_state
{
u_int64_t flags;
int uid, /* GLIBTOP_PROC_STATE_UID */
gid; /* GLIBTOP_PROC_STATE_GID */
char state; /* GLIBTOP_PROC_STATE_STATE */
const char * cmd; /* GLIBTOP_PROC_STATE_CMD */
};
Automatically generated descriptions of _glibtop_proc_state:

cmd
Basename of executable file in call to exec()

state
Single-Char code for process state (S=sleeping)

uid
UID of process

gid
GID of process

glibtop_get_proc_uid() – Process UID and TTY information

Automatically generated description:

Process UID and TTY information
Automatically generated function synopsis:

#include
#include
void glibtop_get_proc_uid (glibtop_proc_uid *proc_uid)

void glibtop_get_proc_uid_l (glibtop *server, glibtop_proc_uid *proc_uid, pid_t pid)

Automatically generated declaration of _glibtop_proc_uid:

typedef struct _glibtop_proc_uid glibtop_proc_uid;

struct _glibtop_proc_uid
{
u_int64_t flags;
int uid, /* GLIBTOP_PROC_UID_UID */
euid, /* GLIBTOP_PROC_UID_EUID */
gid, /* GLIBTOP_PROC_UID_GID */
egid, /* GLIBTOP_PROC_UID_EGID */
pid, /* GLIBTOP_PROC_UID_PID */
ppid, /* GLIBTOP_PROC_UID_PPID */
pgrp, /* GLIBTOP_PROC_UID_PGRP */
session, /* GLIBTOP_PROC_UID_SESSION */
tty, /* GLIBTOP_PROC_UID_TTY */
tpgid, /* GLIBTOP_PROC_UID_TPGID */
priority, /* GLIBTOP_PROC_UID_PRIORITY */
nice; /* GLIBTOP_PROC_UID_NICE */
};
Automatically generated descriptions of _glibtop_proc_uid:

uid
User ID

euid
Effective User ID

gid
Group ID

egid
Effective Group ID

pid
Process ID

ppid
PID of parent process

pgrp
Process group ID

session
Session ID

tty
Full device number of controlling terminal

tpgid
Terminal process group ID

priority
Kernel scheduling priority

nice
Standard unix nice level of process

glibtop_get_proc_mem() – Process Memory information

Automatically generated description:

Process Memory information
Automatically generated function synopsis:

#include
#include
void glibtop_get_proc_mem (glibtop_proc_mem *proc_mem)

void glibtop_get_proc_mem_l (glibtop *server, glibtop_proc_mem *proc_mem, pid_t pid)

Automatically generated declaration of _glibtop_proc_mem:

typedef struct _glibtop_proc_mem glibtop_proc_mem;

struct _glibtop_proc_mem
{
u_int64_t flags;
int64_t size, /* GLIBTOP_PROC_MEM_SIZE */
vsize, /* GLIBTOP_PROC_MEM_VSIZE */
resident, /* GLIBTOP_PROC_MEM_RESIDENT */
share, /* GLIBTOP_PROC_MEM_SHARE */
rss, /* GLIBTOP_PROC_MEM_RSS */
rss_rlim; /* GLIBTOP_PROC_MEM_RSS_RLIM */
};
Automatically generated descriptions of _glibtop_proc_mem:

size
Total # of pages of memory

vsize
Number of pages of virtual memory

resident
Number of residnet set (non-swapped) pages

share
Number of pages of shared (mmap’d) memory

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.

rss_rlim
Current limit in bytes on the rss of the process (usually 2,147,483,647).

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

NOTE:

Note for people porting libgtop to other systems

Well, every operating system has its own idea about the memory usage of a processes, and also system utilities like 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 glibtop_get_proc_mem () should work.

When you use mmap () with either MAP_SHARED or MAP_PRIVATE, this should only affect the procmem.vsize of the process and none of its procmem.size, procmem.resident, procmem.shared and procmem.rss sizes.

As soon as you read some of the mmap ()ed pages, they will be demand-loaded and thus count towards the procmem.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 procmem.resident and procmem.rss sizes of the process.

If the process has used MAP_SHARED and another process attaches the same file also MAP_SHARED some of the pages are shared with this process and thus increase the procmem.shared sizes of both processes.

If the process has used MAP_PRIVATE and writes to the 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.

If memory gets rare, clean pages are normally stolen which decreases the procmem.size, procmem.resident, procmem.shared and procmem.rss sizes of the process.

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

The procmem.vsize of a process can only be changed by the process itself when it requests or frees memory but never due to swapping activity of the system.

If the procmem.shared size changes, this only means that the number of pages that are currently shared with other processes has changed; if this happens, this will never affect any of the other sizes of the process.

The hints above describe how it works under Linux – and we should try to make glibtop_get_proc_mem () show the same behavior under every other system.

If you want to make any comments, flames, suggestions about this, please feel free to do so.

glibtop_get_proc_time() – Process Time information

Automatically generated description:

Process Time information
Automatically generated function synopsis:

#include
#include
void glibtop_get_proc_time (glibtop_proc_time *proc_time)

void glibtop_get_proc_time_l (glibtop *server, glibtop_proc_time *proc_time, pid_t pid)

Automatically generated declaration of _glibtop_proc_time:

typedef struct _glibtop_proc_time glibtop_proc_time;

struct _glibtop_proc_time
{
u_int64_t flags;
int64_t start_time, /* GLIBTOP_PROC_TIME_START_TIME */
rtime, /* GLIBTOP_PROC_TIME_RTIME */
utime, /* GLIBTOP_PROC_TIME_UTIME */
stime, /* GLIBTOP_PROC_TIME_STIME */
cutime, /* GLIBTOP_PROC_TIME_CUTIME */
cstime, /* GLIBTOP_PROC_TIME_CSTIME */
timeout, /* GLIBTOP_PROC_TIME_TIMEOUT */
it_real_value, /* GLIBTOP_PROC_TIME_IT_REAL_VALUE */
timeout; /* GLIBTOP_PROC_TIME_TIMEOUT */
};
Automatically generated descriptions of _glibtop_proc_time:

start_time
Start time of process in seconds since the epoch

rtime
Read time accumulated by process (should be utime + stime)

utime
user-mode CPU time accumulated by process

stime
kernel-mode CPU time accumulated by process

cutime
cumulative utime of process and reaped children

cstime
cumulative stime of process and reaped children

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

it_real_value
The time (in jiffies) before the next SIGALRM is sent to the process due to an interval timer.

timeout
Tick frequency

glibtop_get_proc_signal() – Process Signal information

Automatically generated description:

Process Signal information
Automatically generated function synopsis:

#include
#include
void glibtop_get_proc_signal (glibtop_proc_signal *proc_signal)

void glibtop_get_proc_signal_l (glibtop *server, glibtop_proc_signal *proc_signal, pid_t pid)

Automatically generated declaration of _glibtop_proc_signal:

typedef struct _glibtop_proc_signal glibtop_proc_signal;

struct _glibtop_proc_signal
{
u_int64_t flags;
int signal, /* GLIBTOP_PROC_SIGNAL_SIGNAL */
blocked, /* GLIBTOP_PROC_SIGNAL_BLOCKED */
sigignore, /* GLIBTOP_PROC_SIGNAL_SIGIGNORE */
sigcatch; /* GLIBTOP_PROC_SIGNAL_SIGCATCH */
};
Automatically generated descriptions of _glibtop_proc_signal:

signal
Mask of pending signals

blocked
Mask of blocked signals

sigignore
Mask of ignored signals

sigcatch
Mask of caught signals

glibtop_get_proc_kernel() – Process Kernel Data information

Automatically generated description:

Process Kernel Data information
Automatically generated function synopsis:

#include
#include
void glibtop_get_proc_kernel (glibtop_proc_kernel *proc_kernel)

void glibtop_get_proc_kernel_l (glibtop *server, glibtop_proc_kernel *proc_kernel, pid_t pid)

Automatically generated declaration of _glibtop_proc_kernel:

typedef struct _glibtop_proc_kernel glibtop_proc_kernel;

struct _glibtop_proc_kernel
{
u_int64_t flags;
const char * wchan; /* GLIBTOP_PROC_KERNEL_WCHAN */
u_int64_t k_flags, /* GLIBTOP_PROC_KERNEL_K_FLAGS */
min_flt, /* GLIBTOP_PROC_KERNEL_MIN_FLT */
maj_flt, /* GLIBTOP_PROC_KERNEL_MAJ_FLT */
cmin_flt, /* GLIBTOP_PROC_KERNEL_CMIN_FLT */
cmaj_flt, /* GLIBTOP_PROC_KERNEL_CMAJ_FLT */
kstk_esp, /* GLIBTOP_PROC_KERNEL_KSTK_ESP */
kstk_eip, /* GLIBTOP_PROC_KERNEL_KSTK_EIP */
nwchan; /* GLIBTOP_PROC_KERNEL_NWCHAN */
};
Automatically generated descriptions of _glibtop_proc_kernel:

k_flags
Kernel flags of the process. On Linux, currently every flag has the math bit set, because crt0.s checks for math emulation, so this is not included in the output. This is probably a bug, as not every process is a compiled C program. The math bit should be a decimal 4, and the traced bit is decimal 10.

min_flt
The number of minor faults the process has made, those which have not required loading a memory page from disk.

maj_flt
The number of major faults the process has made, those which have required loading a memory page from disk.

cmin_flt
The number of minor faults that the process and its children have made.

cmaj_flt
The number of major faults that the process and its children have made.

kstk_esp
The current value of esp (32-bit stack pointer), as found in the kernel stack page for the process.

kstk_eip
The current EIP (32-bit instruction pointer).

nwchan
This is the “channel” in which the process is waiting. This is the address of a system call, and can be looked up in a namelist if you need a textual name. (If you have an up-to-date /etc/psdatabase, then try ps -l to see the WCHAN field in action)

wchan
This is the textual name of the `nwchan’ field.

glibtop_get_proc_segment() – Process Segment information

Automatically generated description:

Process Segment information
Automatically generated function synopsis:

#include
#include
void glibtop_get_proc_segment (glibtop_proc_segment *proc_segment)

void glibtop_get_proc_segment_l (glibtop *server, glibtop_proc_segment *proc_segment, pid_t pid)

Automatically generated declaration of _glibtop_proc_segment:

typedef struct _glibtop_proc_segment glibtop_proc_segment;

struct _glibtop_proc_segment
{
u_int64_t flags;
u_int64_t text_rss, /* GLIBTOP_PROC_SEGMENT_TEXT_RSS */
shlib_rss, /* GLIBTOP_PROC_SEGMENT_SHLIB_RSS */
data_rss, /* GLIBTOP_PROC_SEGMENT_DATA_RSS */
stack_rss, /* GLIBTOP_PROC_SEGMENT_STACK_RSS */
dirty_size, /* GLIBTOP_PROC_SEGMENT_DIRTY_SIZE */
start_code, /* GLIBTOP_PROC_SEGMENT_START_CODE */
end_code, /* GLIBTOP_PROC_SEGMENT_END_CODE */
start_stack; /* GLIBTOP_PROC_SEGMENT_START_STACK */
};
Automatically generated descriptions of _glibtop_proc_segment:

text_rss
Text resident set size

shlib_rss
Shared-Lib resident set size

data_rss
Data resident set size

stack_rss
Stack resident set size

dirty_size
Total size of dirty pages

start_code
Address of beginning of code segment

end_code
Address of end of code segment

start_stack
Address of the bottom of stack segment

glibtop_get_proc_map() – Process Memory Map

Automatically generated description:

Process Memory Map
Automatically generated function synopsis:

#include
#include
glibtop_map_entry * glibtop_get_proc_map (glibtop_proc_map *proc_map)

glibtop_map_entry * glibtop_get_proc_map_l (glibtop *server, glibtop_proc_map *proc_map, pid_t pid)

Automatically generated declaration of _glibtop_proc_map:

typedef struct _glibtop_proc_map glibtop_proc_map;

struct _glibtop_proc_map
{
u_int64_t flags;
u_int64_t number, /* GLIBTOP_PROC_MAP_NUMBER */
total, /* GLIBTOP_PROC_MAP_TOTAL */
size; /* GLIBTOP_PROC_MAP_SIZE */
};
Automatically generated descriptions of _glibtop_proc_map:

number
Number of list elements

total
Total size of list

size
Size of a single list element

glibtop_get_mountlist() – Mount List

Automatically generated description:

List of currently mounted filesystems
Automatically generated function synopsis:

#include
#include
glibtop_mountentry * glibtop_get_mountlist (glibtop_mountlist *mountlist)

glibtop_mountentry * glibtop_get_mountlist_l (glibtop *server, glibtop_mountlist *mountlist, pid_t all_fs)

Automatically generated declaration of _glibtop_mountlist:

typedef struct _glibtop_mountlist glibtop_mountlist;

struct _glibtop_mountlist
{
u_int64_t flags;
u_int64_t number, /* GLIBTOP_MOUNTLIST_NUMBER */
total, /* GLIBTOP_MOUNTLIST_TOTAL */
size; /* GLIBTOP_MOUNTLIST_SIZE */
};
Automatically generated descriptions of _glibtop_mountlist:

number
Number of list elements

total
Total size of list

size
Size of a single list element

glibtop_get_fsusage() – File System Usage

Automatically generated description:

File System Usage
Automatically generated function synopsis:

#include
#include
void glibtop_get_fsusage (glibtop_fsusage *fsusage)

void glibtop_get_fsusage_l (glibtop *server, glibtop_fsusage *fsusage, string string)

Automatically generated declaration of _glibtop_fsusage:

typedef struct _glibtop_fsusage glibtop_fsusage;

struct _glibtop_fsusage
{
u_int64_t flags;
u_int64_t blocks, /* GLIBTOP_FSUSAGE_BLOCKS */
bfree, /* GLIBTOP_FSUSAGE_BFREE */
bavail, /* GLIBTOP_FSUSAGE_BAVAIL */
files, /* GLIBTOP_FSUSAGE_FILES */
ffree; /* GLIBTOP_FSUSAGE_FFREE */
};
Automatically generated descriptions of _glibtop_fsusage:

blocks
Total blocks

bfree
Free blocks available to the superuser

bavail
Free blocks available to non-superusers

files
Total file nodes

ffree
Free file nodes

Chapter 3. Porting libgtop to other systems

Here are some comments for people porting libgtop to other systems.

glibtop_get_proc_mem () – Process Memory information

This section is copied here from the description of glibtop_get_proc_mem ().

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

NOTE:

Note for people porting libgtop to other systems

Well, every operating system has its own idea about the memory usage of a processes, and also system utilities like 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 glibtop_get_proc_mem () should work.

When you use mmap () with either MAP_SHARED or MAP_PRIVATE, this should only affect the procmem.vsize of the process and none of its procmem.size, procmem.resident, procmem.shared and procmem.rss sizes.

As soon as you read some of the mmap ()ed pages, they will be demand-loaded and thus count towards the procmem.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 procmem.resident and procmem.rss sizes of the process.

If the process has used MAP_SHARED and another process attaches the same file also MAP_SHARED some of the pages are shared with this process and thus increase the procmem.shared sizes of both processes.

If the process has used MAP_PRIVATE and writes to the 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.

If memory gets rare, clean pages are normally stolen which decreases the procmem.size, procmem.resident, procmem.shared and procmem.rss sizes of the process.

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

The procmem.vsize of a process can only be changed by the process itself when it requests or frees memory but never due to swapping activity of the system.

If the procmem.shared size changes, this only means that the number of pages that are currently shared with other processes has changed; if this happens, this will never affect any of the other sizes of the process.

The hints above describe how it works under Linux – and we should try to make glibtop_get_proc_mem () show the same behavior under every other system.

If you want to make any comments, flames, suggestions about this, please feel free to do so.