Tribblix: manual page: ea_set

EA_SET_ITEM(3EXACCT) Extended Accounting File Access Library Functions

NAME

ea_set_item, ea_alloc, ea_strdup, ea_set_group,
ea_match_object_catalog, ea_attach_to_object, ea_attach_to_group,
ea_free, ea_strfree, ea_free_item, ea_free_object - create, destroy
and manipulate exacct objects

SYNOPSIS

cc [ flag... ] file... -lexacct [ library... ]
#include <exacct.h>

int ea_set_item(ea_object_t *obj, ea_catalog_t tag, void *value,
size_t valsize);

void *ea_alloc(size_t size);

char *ea_strdup(char *ptr);

int ea_set_group(ea_object_t *obj, ea_catalog_t tag);

int ea_match_object_catalog(ea_object_t *obj, ea_catalog_t catmask);

void ea_attach_to_object(ea_object_t *head_obj, ea_object_t *obj);

void ea_attach_to_group(ea_object_t *group_obj, ea_object_t *obj);

void ea_free(void *ptr, size_t size);

void ea_strfree(char *ptr);

int ea_free_item(ea_object_t *obj, int flag);

void ea_free_object(ea_object_t *obj, int flag);

DESCRIPTION

The ea_alloc() function allocates a block of memory of the requested
size. This block can be safely passed to libexacct functions, and can
be safely freed by any of the ea_free() functions.

The ea_strdup() function can be used to duplicate a string that is to
be stored inside an ea_object_t structure.

The ea_set_item() function assigns the given exacct object to be a
data item with value set according to the remaining arguments. For
buffer-based data values (EXT_STRING, EXT_EXACCT_OBJECT, and
EXT_RAW), a copy of the passed buffer is taken. In the case of
EXT_EXACCT_OBJECT, the passed buffer should be a packed exacct object
as returned by ea_pack_object(3EXACCT). Any item assigned with
ea_set_item() should be freed with ea_free_item() specifying a flag
value of EUP_ALLOC when the item is no longer needed.

The ea_match_object_catalog() function returns TRUE if the exacct
object specified by obj has a catalog tag that matches the mask
specified by catmask.

The ea_attach_to_object() function attaches an object to the given
object. The ea_attach_to_group() function attaches a chain of objects
as member items of the given group. Objects are inserted at the end
of the list of any previously attached objects.

The ea_free() function frees a block of memory previously allocated
by ea_alloc().

The ea_strfree() function frees a string previously copied by
ea_strdup().

The ea_free_item() function frees the value fields in the ea_object_t
indicated by obj, if EUP_ALLOC is specified. The object itself is not
freed. The ea_free_object() function frees the specified object and
any attached hierarchy of objects. If the flag argument is set to
EUP_ALLOC, ea_free_object() will also free any variable-length data
in the object hierarchy; if set to EUP_NOALLOC, ea_free_object() will
not free variable-length data. In particular, these flags should
correspond to those specified in calls to ea_unpack_object(3EXACCT).

RETURN VALUES

The ea_match_object_catalog() function returns 0 if the object's
catalog tag does not match the given mask, and 1 if there is a match.

Other integer-valued functions return 0 if successful. Otherwise
these functions return -1 and set the extended accounting error code
appropriately. Pointer-valued functions return a valid pointer if
successful and NULL otherwise, setting the extended accounting error
code appropriately. The extended accounting error code can be
examined with ea_error(3EXACCT).

ERRORS

The ea_set_item(), ea_set_group(), and ea_match_object_catalog()
functions may fail if:

EXR_SYSCALL_FAIL
A system call invoked by the function failed.
The errno variable contains the error value set
by the underlying call.

EXR_INVALID_OBJECT
The passed object is of an incorrect type, for
example passing a group object to
ea_set_item().

USAGE

The exacct file format can be used to represent data other than that
in the extended accounting format. By using a unique creator type in
the file header, application writers can develop their own format
suited to the needs of their application.

EXAMPLES

Example 1: Open and close exacct file.

Construct an exacct file consisting of a single object containing the
current process ID.

#include <sys/types.h>
#include <unistd.h>
#include <exacct.h>

...

ea_file_t ef;
ea_object_t obj;
pid_t my_pid;

my_pid = getpid();
ea_set_item(&obj, EXT_UINT32 | EXC_DEFAULT | EXT_PROC_PID,
&my_pid, sizeof(my_pid));

...

ATTRIBUTES