reference.texi

linux 操作系统下对系统资源监控程序的编写

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/proc_state.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
@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/limits.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{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, 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

@page
@node glibtop_proc_signal, glibtop_proc_kernel, glibtop_proc_time, System Dependent
@subsection Process Signal information

Library function @code{glibtop_get_proc_signal}:

@example
@cartouche
void
glibtop_get_proc_signal (glibtop_proc_signal *buf, pid_t pid);

void
glibtop_get_proc_signal_l (glibtop *server, glibtop_proc_signal *buf,
                           pid_t pid);
@end cartouche
@end example

Declaration of @code{glibtop_proc_signal} in @file{<glibtop/procsignal.h>}:

@example
@cartouche
typedef struct _glibtop_proc_signal     glibtop_proc_signal;

struct _glibtop_proc_signal
@{
    guint64   flags,
        signal [2],
        blocked [2],
        sigignore [2],
        sigcatch [2];
@};
@end cartouche
@end example

@table @code
@item signal
Mask of pending signals
@item blocked
Mask of blocked signals
@item sigignore
Mask of ignored signals
@item sigcatch
Mask of caught signals
@end table

All signal masks are interpreted as bit mask; it is an array of two