NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | EXAMPLES | ATTRIBUTES | SEE ALSO
cc [flag ...] file ... -lexacct [library ...] #include <exacct.h>size_t ea_pack_object(ea_object_t *obj, void *buf, size_t bufsize);
The ea_pack_object() function converts exacct objects from their in-memory representation to their file representation. It is passed an object pointer that points to the top of an exacct object hierarchy representing one or more exacct records. It returns the size of the buffer required to contain the packed buffer representing the object hierarchy.
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 (presumably due to a corrupted or incomplete buffer), it returns -1; otherwise, the object type of the first object in the hierarchy 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 resulting object 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. The ea_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 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 -1 and records the extended accounting error code.
The ea_previous_object() function skips back one object in the file and reads its basic fields into the indicated ea_object_t. If the read object is corrupted, ea_previous_object() returns -1 and records the extended accounting error code.
The ea_get_object() function reads the value fields into the ea_object_t indicated by obj, allocating memory as necessary, and advances to the head of the next record. Once a record group object is retrieved using ea_get_object(), a call to ea_next_object() will track through the objects within the record group. If the read object is corrupted, ea_get_object() returns -1 and records the extended accounting error code.
The ea_write_object() function appends the given object to the open exacct file indicated by ef. If the write fails, ea_write_object() returns -1 and sets the extended accounting error code to indicate the error.
The ea_pack_object() function returns the number of bytes associated with the exacct object being operated upon. If the returned size exceeds bufsize, the pack operation will not complete.
The ea_get_object() function returns 1 if the object was retrieved successfully. Otherwise, it returns 0 and sets errno to indicate the error. If the error occured during the execution of read(2), errno will be unchanged.
The ea_next_object() function returns the ea_object_type of the next exacct object in the file. It returns -1 if the exacct file is corrupted.
The ea_unpack_object() function returns the ea_object_type of the first exacct object unpacked from the buffer. It returns -1 if the exacct file is corrupted.
The ea_write_object() function returns 0 on success and -1 on failure.
In the case of failure, these functions will set an extended accounting error code reflecting one of the errors decsribed below. The extended account error code can be retrieved using ea_error(3EXACCT).
These functions may fail if:
A system call invoked by the function failed. The errno variable contains the error value set by the underlying call.
The file referred to by name is not a valid exacct file, or is unparsable, and therefore appears corrupted. This error is also used by ea_unpack_buffer() to indicate a corrupted buffer.
A memory allocation required to complete the operation failed.
The end of the file has been reached. In the case of ea_previous_record(), the previous record could not be reached, either because the head of the file was encountered or because the previous record could not be skipped over.
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.
The following example opens the extended accounting data file for processes. The exacct file is then closed.
#include <stdio.h> #include <exacct.h> ea_file_t ef; ea_object_t obj; ... ea_open(&ef, "foo", O_RDONLY, ...); while (ea_next_object(&ef, &obj) != -1) { if (ea_get_object(&ef, &obj) == -1) { (void) fprintf(stderr, "unrecognized exacct object"); break; } if (obj.eo_type == EO_ITEM) { /* handle item */ } else { /* handle group */ } } ea_close(&ef);
#include <sys/types.h> #include <unistd.h> #include <exacct.h> ... 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, EXD_UINT32 | EXC_DEFAULT | EXT_PROC_PID, &ny_pid, 0); (void) ea_write_object(&ef, &obj); ea_close(&ef); ...
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
MT-Level | MT-Safe |
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | EXAMPLES | ATTRIBUTES | SEE ALSO