reference.texi

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

@end example

@table @code
@item GLIBTOP_PPP_STATE_UNKNOWN
LibGTop was unable to determine the current ppp state.
@item GLIBTOP_PPP_STATE_HANGUP
We're currently offline.
@item GLIBTOP_PPP_STATE_ONLINE
We're currently online.
@end table

@page
@node Common Functions, Library Functions, System Dependent, Reference Manual
@section Common Functions

This are functions which a common implementation for all systems; we never
use the server for them.

The file system code is taken from GNU Fileutils.

@menu
* glibtop_mountlist::           Mount List.
* glibtop_fsusage::             File System Usage.
@end menu

@node glibtop_mountlist, glibtop_fsusage, Common Functions, Common Functions
@subsection Mount List

Library function @code{glibtop_get_mountlist}:

@example
@cartouche
glibtop_mountentry *
glibtop_get_mountlist_l (glibtop *server, glibtop_mountlist *buf,
                         int all_fs);

glibtop_mountentry *
glibtop_get_mountlist (glibtop_mountlist *buf, int all_fs);
@end cartouche
@end example

The @code{all_fs} parameter specifies whether information about all
filesystems should be returned; this will include filesystem types like
@code{autofs} and @code{procfs}. You should not use this in disk usage
programs, but it can be useful to get a list of all currently mounted
filesystems.

Declaration of @code{glibtop_proc_map} in @file{<glibtop/procmap.h>}:

@example
@cartouche
typedef struct _glibtop_mountlist       glibtop_mountlist;

struct _glibtop_mountlist
@{
    guint64   flags,
        number,
        total,
        size;
@};
@end cartouche
@end example

Returns a @code{glibtop_mountentry *} list (which needs to be freed with
@code{g_free}) of mounted filesystems.

@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 (glibtop_mountentry)}).
@end table

@example
@cartouche
typedef struct _glibtop_mountentry      glibtop_mountentry;

struct _glibtop_mountentry
@{
    guint64 dev;
    char devname [GLIBTOP_MOUNTENTRY_LEN+1];
    char mountdir [GLIBTOP_MOUNTENTRY_LEN+1];
    char type [GLIBTOP_MOUNTENTRY_LEN+1];
@};
@end cartouche
@end example

@ifset LIBGTOP-1-1
@code{GLIBTOP_MOUNTENTRY_LEN} is defined in @file{<glibtop/limits.h>}.
@end ifset
@ifclear LIBGTOP-1-1
@code{GLIBTOP_MOUNTENTRY_LEN} is defined in @file{<glibtop.h>}
(this was moved to @file{<glibtop/limits.h>} in LibGTop 1.1.0).
@end ifclear

@table @code
@item devname
Full pathname (such as @samp{/dev/sdb1} for instance) to the mounted device.
@item mountdir
Full pathname of the mountpoint (such as @samp{/usr/local} for instance).
@item type
Filesystem type as a textual string (such as @samp{ext2fs}).
@end table

@page
@node glibtop_fsusage,  , glibtop_mountlist, Common Functions
@subsection File System Usage

Library function @code{glibtop_get_fsusage}:

@example
@cartouche
void
glibtop_get_fsusage_l (glibtop *server, glibtop_fsusage *buf,
                       const char *mount_dir);

void
glibtop_get_fsusage (glibtop_fsusage *buf, const char *mount_dir);
@end cartouche
@end example

Declaration of @code{glibtop_fsusage} in @file{<glibtop/fsusage.h>}:

@example
@cartouche
typedef struct _glibtop_fsusage         glibtop_fsusage;

struct _glibtop_fsusage
@{
    guint64   flags,
        blocks,
        bfree,
        bavail,
        files,
        ffree;
@};
@end cartouche
@end example

@table @code
@item blocks
Total blocks in the filesystem.
@item bfree
Free blocks available to the superuser.
@item bavail
Free blocks available to ordinary users.
@item files
Total file nodes.
@item ffree
Free file nodes.
@end table

Blocks are usually 512 bytes.

@page
@node Library Functions,  , Common Functions, Reference Manual
@section Library Functions

This are general library functions which can be used to get information
about the library and to control its behavior.

@menu
* glibtop_init::                Server Initialization.
* glibtop_sysdeps::             Server Sysdeps.
* Library Parameters::          Library Parameters.
@end menu

@node glibtop_init, glibtop_sysdeps, Library Functions, Library Functions
@subsection Server Initialization

You do not need to worry about the @code{glibtop *} server structure if
you don't need - the library exports a @code{glibtop_global_server}
which you can use everywhere a @code{glibtop *} is expected.

Most of the library and all of the sysdeps function also have an alias
(which is the function name without the @samp{_l}, @samp{_s} or @samp{_r}
suffix) which don't take a @code{glibtop *} as argument but uses the
@code{glibtop_global_server} instead.

@example
@cartouche
extern glibtop *glibtop_global_server;
@end cartouche
@end example

Library function @code{glibtop_init}:

@example
@cartouche
glibtop *
glibtop_init_r (glibtop **server_ptr, unsigned long features,
                unsigned flags);

void
glibtop_init (void);
@end cartouche
@end example

This function initializes a LibGTop server. It is automatically called
when you use any of the LibGTop functions and will use the global server
in this case.

However, it's appreciated to call @code{glibtop_init} during the
initialization of your application.

You can for instance use

@example
glibtop_init ();
@end example

@noindent
which is equivalent to

@example
glibtop_init_r (&glibtop_global_server, 0, 0);
@end example

Please note that the @code{server_ptr} argument is a pointer to a pointer
(and thus is of type @code{glibtop **}).

To control what @code{glibtop_init} should actually do, you can use the
@code{features} and @code{flags} arguments.

The @code{features} argument is a bit-mask (interpreted in the same way
than @samp{sysdeps.features}) and tells the library which features you're
interested in. The library will only start the server if this is required
for any of those features.

You can use the following constants for the @code{flags} parameter to
control the behavior of the library:

@table @code
@item GLIBTOP_INIT_NO_INIT
Tells the library to do nothing. If the value pointed to by the
@code{server_ptr} argument is @code{NULL}, it will set it to the
@code{glibtop_global_server} and then return.
@item GLIBTOP_INIT_NO_OPEN
Do the initialization, but do not start the server.
@end table

To modify the way the @code{features} are interpretet, you can use the
following constants for @code{flags} (as a bit mask):

@table @code
@item GLIBTOP_FEATURES_NO_SERVER
Never use the server, always call the sysdeps code directly.
If you require any privileges to get them and you don't have those
privileges, the this will obviously not work and the library will
fail to return some or all of the requested values.
@item GLIBTOP_FEATURES_EXCEPT
Inverts the matching of the @code{features} parameter, i.e. if you use
this flag this means that @code{features} are all the features you are
@emph{not} interested in.
Might be useful to say something like "I want everything but ppp".
@end table

@node glibtop_sysdeps, Library Parameters, glibtop_init, Library Functions
@subsection Server Sysdeps

Library function @code{glibtop_get_sysdeps}:

@example
@cartouche
void
glibtop_get_sysdeps_r (glibtop *server, glibtop_sysdeps *buf);

void
glibtop_get_sysdeps (glibtop_sysdeps *buf);
@end cartouche
@end example

Declaration of @code{glibtop_sysdeps} in @file{<glibtop/sysdeps.h>}:

@example
@cartouche
typedef struct _glibtop_sysdeps         glibtop_sysdeps;

struct _glibtop_sysdeps
@{
    guint64 flags,
        features,
        pointer_size,
        cpu,
        mem,
        swap,
        uptime,
        loadavg,
        shm_limits,
        msg_limits,
        sem_limits,
        proclist,
        proc_state,
        proc_uid,
        proc_mem,
        proc_time,
        proc_signal,
        proc_kernel,
        proc_segment,
        proc_args,
        proc_map,
        mountlist,
        fsusage,
        netload,
        ppp;
@};
@end cartouche
@end example

@table @code
@item features
This is a bit field (the so-called @dfn{server features}) stating
for which features we need to use the server.
@item pointer_size
This was added in LibGTop 1.1.0 and tells you the number of bits a
@code{void*} has in the server (this may be different from the
size on the client machine if we're talking over the daemon to a
remove machine).
@end table

The following constants from @file{<glibtop/sysdeps.h>} serve as bit-indices
for the @code{features} field:

@example
@cartouche
#define GLIBTOP_SYSDEPS_CPU             0
#define GLIBTOP_SYSDEPS_MEM             1
#define GLIBTOP_SYSDEPS_SWAP            2
#define GLIBTOP_SYSDEPS_UPTIME          3
#define GLIBTOP_SYSDEPS_LOADAVG         4
#define GLIBTOP_SYSDEPS_SHM_LIMITS      5
#define GLIBTOP_SYSDEPS_MSG_LIMITS      6
#define GLIBTOP_SYSDEPS_SEM_LIMITS      7
#define GLIBTOP_SYSDEPS_PROCLIST        8
#define GLIBTOP_SYSDEPS_PROC_STATE      9
#define GLIBTOP_SYSDEPS_PROC_UID        10
#define GLIBTOP_SYSDEPS_PROC_MEM        11
#define GLIBTOP_SYSDEPS_PROC_TIME       12
#define GLIBTOP_SYSDEPS_PROC_SIGNAL     13
#define GLIBTOP_SYSDEPS_PROC_KERNEL     14
#define GLIBTOP_SYSDEPS_PROC_SEGMENT    15
#define GLIBTOP_SYSDEPS_PROC_ARGS       16
#define GLIBTOP_SYSDEPS_PROC_MAP        17
#define GLIBTOP_SYSDEPS_MOUNTLIST       18
#define GLIBTOP_SYSDEPS_FSUSAGE         19
#define GLIBTOP_SYSDEPS_NETLOAD         20
#define GLIBTOP_SYSDEPS_PPP             21
@end cartouche
@end example

@node Library Parameters,  , glibtop_sysdeps, Library Functions
@subsection Library Parameters

Library function @code{glibtop_get_parameter}:

@example
@cartouche
size_t
glibtop_get_parameter_l (glibtop *server, const unsigned parameter,
                         void *data_ptr, size_t data_size);

size_t
glibtop_get_parameter (const unsigned parameter, void *data_ptr,
                       size_t data_size);
@end cartouche
@end example

This function is used to retrieve a library parameter (see below for a more
detailed description). It returns the size of the retrieved parameter on
success, zero on failure or minus the actual size of the parameter if
@code{data_size} was too small.

You may call this function with @code{data_ptr} set to @code{NULL} to get the
actual size of a parameter (as a negative value).

@table @code
@item parameter
The parameter you want to retrieve (see below for constants).
@item data_ptr
Pointer to a place where the parameter should be stored.
@item data_size
Maximum size of the parameter.
@end table

Library function @code{glibtop_set_parameter}:

@example
@cartouche
void
glibtop_set_parameter_l (glibtop *server, const unsigned parameter,
                         const void *data_ptr, size_t data_size);

void
glibtop_set_parameter (const unsigned parameter, const void *data_ptr,
                       size_t data_size);
@end cartouche
@end example

This function is used to modify a library parameter. Please not that you
may not set all parameters since some of them are read-only.

@table @code
@item parameter
The parameter you want to modify (see below for constants).
@item data_ptr
Pointer to the value which should be set.
@item data_size
Size of the new value. For fixed-size parameters, this must match
the exact size of the parameter or you'll get an error.
@end table

The following parameters are defined in @file{<glibtop/parameter.h>}:

@table @code
@item GLIBTOP_PARAM_FEATURES
This is a read-only @code{unsigned long} representing the @code{features}
field of @code{glibtop_sysdeps}.
@item GLIBTOP_PARAM_REQUIRED
This is a @code{glibtop_sysdeps} structure specifying which features the
client requires the library return. If it fails to get any of them, you'll
get an error.
@item GLIBTOP_PARAM_ERROR_METHOD
This is an @code{unsigned} telling the library what to do if it fails to
get any of the features that are marked as required via the
@code{GLIBTOP_PARAM_REQUIRED} parameter (see below for constants).
@end table

You can use the following constants for @code{GLIBTOP_PARAM_ERROR_METHOD}
(defined in @file{<glibtop/open.h>}):

@table @code
@item GLIBTOP_ERROR_METHOD_IGNORE
Ignore the error condition.
@item GLIBTOP_ERROR_METHOD_WARN_ONCE
Warn once about the absense of some of the required features, then modify
@code{GLIBTOP_PARAM_REQUIRED} so that the missing ones are no longer
required. This is the prefered value for applications since it'll only
print out the warning message once and not each time the library tries to
get one of those features.
@item GLIBTOP_ERROR_METHOD_WARN
Warn each time the library fails to get some of the required features.
@item GLIBTOP_ERROR_METHOD_ABORT
Abort if the library fails to get some of the required features. This
should not be used by applications.
@end table