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. 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 to ea_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, due to
a corrupted or incomplete buffer), it returns EO_ERROR; 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 (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 corrupted, ea_previous_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_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(), subsequent 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 read object is corrupted, ea_get_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_write_object() function appends the given object to the open exacct file indicated by ef and returns 0. If the write fails, ea_write_object() returns -1 and sets the extended accounting error code to indicate
the error, accessible 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 the eg_nobjs
and eg_objs fields are set to 0 and NULL, respectively. 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 returned object 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 structure that 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, whereas ea_get_object_tree() reads the group and all its member items, recursing into sub-records if necessary. The returned object data structure can be completely freed with ea_free_object() by
specifying the EUP_ALLOC flag.
|