Extended Accounting File Access Library Functions
ea_pack_object(3EXACCT)
NAME
ea_pack_object, ea_unpack_object, ea_get_creator,
ea_get_hostname, ea_next_object, ea_previous_object,
ea_get_object, ea_write_object, ea_copy_object,
ea_copy_object_tree, ea_get_object_tree - construct, read,
and write extended accounting recordsSYNOPSIS
cc [ flag... ] file... -lexacct [ library... ]
#include
size_t ea_pack_object(ea_object_t *obj, void *buf,
size_t bufsize);
ea_object_type_t ea_unpack_object(ea_object_t **objp, int flag,
void *buf, size_t bufsize);
const char *ea_get_creator(ea_file_t *ef);
const char *ea_get_hostname(ea_file_t *ef);
ea_object_type_t ea_next_object(ea_file_t *ef, ea_object_t *obj);
ea_object_type_t ea_previous_object(ea_file_t *ef,
ea_object_t *obj);
ea_object_type_t ea_get_object(ea_file_t *ef, ea_object_t *obj);
int ea_write_object(ea_file_t *ef, ea_object_t *obj);
ea_object_type_t *ea_copy_object(const ea_object_t *src);
ea_object_type_t *ea_copy_object_tree(const ea_object_t *src);
ea_object_type_t *ea_get_object_tree(ea_file_t *ef,
uint32_tnobj);
DESCRIPTION
The ea_pack_object() function converts exacct objects from
their in-memory representation to their file representation.
SunOS 5.11 Last change: 4 Oct 2007 1
Extended Accounting File Access Library Functionsea_pack_object(3EXACCT)
It is passed an object pointer that points to the top of an exacct object hierarchy representing one or more exacctrecords. It returns the size of the buffer required to con-
tain the packed buffer representing the object hierarchy. To obtain the correct size of the required buffer, the buf and bufsize parameters can be set to NULL and 0 respectively, and the required buffer size will be returned. The resulting packed record can be passed to putacct(2) or toea_set_item(3EXACCT) when constructing an object of type
EXT_EXACCT_OBJECT.
The ea_unpack_object() function reverses the packing process
performed by ea_pack_object(). A packed buffer passed to
ea_unpack_object() is unpacked into the original hierarchy
of objects. If the unpack operation fails (for example, dueto a corrupted or incomplete buffer), it returns EO_ERROR;
otherwise, the object type of the first object in thehierarchy is returned. If ea_unpack_object() is invoked
with flag equal to EUP_ALLOC, it allocates memory for the
variable-length data in the included objects. Otherwise,
with flag equal to EUP_NOALLOC, it sets the variable length
data pointers within the unpacked object structures to point within the buffer indicated by buf. In both cases,ea_unpack_object() allocates all the necessary exacct
objects to represent the unpacked record. The resultingobject hierarchy can be freed using ea_free_object(3EXACCT)
with the same flag value.The ea_get_creator() function returns a pointer to a string
representing the recorded creator of the exacct file. Theea_get_hostname() function returns a pointer to a string
representing the recorded hostname on which the exacct file was created. These functions will return NULL if their respective field was not recorded in the exacct file header.The ea_next_object() function reads the basic fields
(eo_catalog and eo_type) into the ea_object_t indicated by
obj from the exacct file referred to by ef and rewinds to the head of the record. If the read object is corrupted,ea_next_object() returns EO_ERROR and records the extended
accounting error code, accessible with ea_error(3EXACCT). If
end-of-file is reached, EO_ERROR is returned and the
extended accounting error code is set to EXR_EOF.
The ea_previous_object() function skips back one object in
the file and reads its basic fields (eo_catalog and eo_type)
into the indicated ea_object_t. If the read object is
SunOS 5.11 Last change: 4 Oct 2007 2
Extended Accounting File Access Library Functionsea_pack_object(3EXACCT)
corrupted, ea_previous_object() returns EO_ERROR and records
the extended accounting error code, accessible withea_error(3EXACCT). If end-of-file is reached, EO_ERROR is
returned and the extended accounting error code is set toEXR_EOF.
The ea_get_object() function reads the value fields into the
ea_object_t indicated by obj, allocating memory as neces-
sary, and advances to the head of the next record. Once arecord group object is retrieved using ea_get_object(), sub-
sequent calls to ea_get_object() and ea_next_object() will
track through the objects within the record group, and on reaching the end of the group, will return the next object at the same level as the group from the file. If the readobject is corrupted, ea_get_object() returns EO_ERROR and
records the extended accounting error code, accessible withea_error(3EXACCT). If end-of-file is reached, EO_ERROR is
returned and the extended accounting error code is set toEXR_EOF.
The ea_write_object() function appends the given object to
the open exacct file indicated by ef and returns 0. If thewrite fails, ea_write_object() returns -1 and sets the
extended accounting error code to indicate the error, acces-
sible with ea_error(3EXACCT).
The ea_copy_object() function copies an ea_object_t. If the
source object is part of a chain, only the current object is copied. If the source object is a group, only the group object is copied without its list of members and theeg_nobjs and eg_objs fields are set to 0 and NULL, respec-
tively. Use ea_copy_tree() to copy recursively a group or a
list of items.The ea_copy_object_tree() function recursively copies an
ea_object_t. All elements in the eo_next list are copied,
and any group objects are recursively copied. The returnedobject can be completely freed with ea_free_object(3EXACCT)
by specifying the EUP_ALLOC flag.
The ea_get_object_tree() function reads in nobj top-level
objects from the file, returning the same data structurethat would have originally been passed to ea_write_object().
On encountering a group object, the ea_get_object() function
reads only the group header part of the group, whereasea_get_object_tree() reads the group and all its member
SunOS 5.11 Last change: 4 Oct 2007 3
Extended Accounting File Access Library Functionsea_pack_object(3EXACCT)
items, recursing into sub-records if necessary. The returned
object data structure can be completely freed withea_free_object() by specifying the EUP_ALLOC flag.
RETURN VALUES
The ea_pack_object() function returns the number of bytes
required to hold the exacct object being operated upon. If the returned size exceeds bufsize, the pack operation doesnot complete and the function returns (size_t) -1 and sets
the extended accounting error code to indicate the error.The ea_get_object() function returns the ea_object_type of
the object if the object was retrieved successfully. Other-
wise, it returns EO_ERROR and sets the extended accounting
error code to indicate the error.The ea_next_object() function returns the ea_object_type of
the next exacct object in the file. It returns EO_ERROR if
the exacct file is corrupted sets the extended accounting error code to indicate the error.The ea_unpack_object() function returns the ea_object_type
of the first exacct object unpacked from the buffer. Itreturns EO_ERROR if the exacct file is corrupted, and sets
the extended accounting error code to indicate the error.The ea_write_object() function returns 0 on success. Other-
wise it returns -1 and sets the extended accounting error
code to indicate the error.The ea_copy_object() and ea_copy_object_tree() functions
return the copied object on success. Otherwise they return NULL and set the extended accounting error code to indicate the error.The ea_get_object_tree() function returns the list of
objects read from the file on success. Otherwise it returns NULL and sets the extended accounting error code to indicate the error. The extended account error code can be retrieved usingea_error(3EXACCT).
SunOS 5.11 Last change: 4 Oct 2007 4
Extended Accounting File Access Library Functionsea_pack_object(3EXACCT)
ERRORS
These 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. On memory allocation failure, errno will be set to ENOMEM.EXR_CORRUPT_FILE
The file referred to by name is not a valid exacct file, or is unparsable, and therefore appears corrupted. Thiserror is also used by ea_unpack_buffer() to indicate a
corrupted buffer.EXR_EOF
The end of the file has been reached. In the case ofea_previous_record(), the previous record could not be
reached, either because the head of the file was encoun-
tered or because the previous record could not be skipped over.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. The following example opens the extended accounting data file for processes. The exacct file is then closed.#include
#include
ea_file_t ef;
ea_object_t *obj;
...SunOS 5.11 Last change: 4 Oct 2007 5
Extended Accounting File Access Library Functionsea_pack_object(3EXACCT)
ea_open(&ef, "foo", O_RDONLY, ...);
while ((obj = ea_get_object_tree(&ef, 1)) != NULL) {
if (obj->eo_type == EO_ITEM) {
/* handle item */ } else { /* handle group */ }ea_free_object(obj, EUP_ALLOC);
}if (ea_error() != EXR_EOF) {
/* handle error */ }ea_close(&ef);
Example 2 Construct an exacct file consisting of a single object containing the current process ID.#include
#include
#include
...ea_file_t ef;
ea_object_t obj;
pid_t my_pid;
ea_open(&ef, "foo", O_CREAT | O_WRONLY, ...);
my_pid = getpid();
ea_set_item(&obj, EXT_UINT32 | EXC_DEFAULT | EXT_PROC_PID, &my_pid, 0);
(void) ea_write_object(&ef, &obj);
ea_close(&ef);
...ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 4 Oct 2007 6
Extended Accounting File Access Library Functionsea_pack_object(3EXACCT)
______________________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
read(2), ea_error(3EXACCT), ea_open(3EXACCT),
ea_set_item(3EXACCT), libexacct(3LIB), attributes(5)
SunOS 5.11 Last change: 4 Oct 2007 7
Extended Accounting File Access Library Functionsea_pack_object(3EXACCT)
SunOS 5.11 Last change: 4 Oct 2007 8