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
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
SEE ALSO
read(2),
ea_error(3EXACCT),
ea_open(3EXACCT),
ea_pack_object(3EXACCT),
libexacct(3LIB),
attributes(7) November 28, 2001
EA_SET_ITEM(3EXACCT)