Extended Accounting File Access Library Functions
eapackobject(3EXACT)
NAME
eapackobject, eaunpackobject, eagetcreator,
eagethostname, eanextobject, eapreviousobject,
eagetobject, eawriteobject, eacopyobject,
eacopyobjecttree, eagetobjecttree - construct, read,
and write extended accounting records
SYNOPSIS
cc [ flag... ] file... -lexacct [ library... ]
#include
sizet eapackobject(eaobjectt *obj, void *buf,
sizet bufsize);
eaobjecttypet eaunpackobject(eaobjectt **objp, int flag,
void *buf, sizet bufsize);
const char *eagetcreator(eafilet *ef);
const char *eagethostname(eafilet *ef);
eaobjecttypet eanextobject(eafilet *ef, eaobjectt *obj);
eaobjecttypet eapreviousobject(eafilet *ef,
eaobjectt *obj);
eaobjecttypet eagetobject(eafilet *ef, eaobjectt *obj);
int eawriteobject(eafilet *ef, eaobjectt *obj);
eaobjecttypet *eacopyobject(const eaobjectt *src);
eaobjecttypet *eacopyobjecttree(const eaobjectt *src);
eaobjecttypet *eagetobjecttree(eafilet *ef,
uint32tnobj);
DESCRIPTION
The eapackobject() 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 Functions
eapackobject(3EXACT)
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 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 NUL and 0 respectively,
and the required buffer size will be returned. The resulting
packed record can be passed to putacct(2) or to
easetitem(3EXACT) when constructing an object of type
EXTEXACTOBJECT.
The eaunpackobject() function reverses the packing process
performed by eapackobject(). A packed buffer passed to
eaunpackobject() is unpacked into the original hierarchy
of objects. If the unpack operation fails (for example, due
to a corrupted or incomplete buffer), it returns EOEROR;
otherwise, the object type of the first object in the
hierarchy is returned. If eaunpackobject() is invoked
with flag equal to EUPALOC, it allocates memory for the
variable-length data in the included objects. Otherwise,
with flag equal to EUPNOALOC, it sets the variable length
data pointers within the unpacked object structures to point
within the buffer indicated by buf. In both cases,
eaunpackobject() allocates all the necessary exacct
objects to represent the unpacked record. The resulting
object hierarchy can be freed using eafreeobject(3EXACT)
with the same flag value.
The eagetcreator() function returns a pointer to a string
representing the recorded creator of the exacct file. The
eagethostname() function returns a pointer to a string
representing the recorded hostname on which the exacct file
was created. These functions will return NUL if their
respective field was not recorded in the exacct file header.
The eanextobject() function reads the basic fields
(eocatalog and eotype) into the eaobjectt 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,
eanextobject() returns EOEROR and records the extended
accounting error code, accessible with eaerror(3EXACT). If
end-of-file is reached, EOEROR is returned and the
extended accounting error code is set to EXREOF.
The eapreviousobject() function skips back one object in
the file and reads its basic fields (eocatalog and eotype)
into the indicated eaobjectt. If the read object is
SunOS 5.11 Last change: 4 Oct 2007 2
Extended Accounting File Access Library Functions
eapackobject(3EXACT)
corrupted, eapreviousobject() returns EOEROR and records
the extended accounting error code, accessible with
eaerror(3EXACT). If end-of-file is reached, EOEROR is
returned and the extended accounting error code is set to
EXREOF.
The eagetobject() function reads the value fields into the
eaobjectt indicated by obj, allocating memory as neces-
sary, and advances to the head of the next record. Once a
record group object is retrieved using eagetobject(), sub-
sequent calls to eagetobject() and eanextobject() 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, eagetobject() returns EOEROR and
records the extended accounting error code, accessible with
eaerror(3EXACT). If end-of-file is reached, EOEROR is
returned and the extended accounting error code is set to
EXREOF.
The eawriteobject() function appends the given object to
the open exacct file indicated by ef and returns 0. If the
write fails, eawriteobject() returns -1 and sets the
extended accounting error code to indicate the error, acces-
sible with eaerror(3EXACT).
The eacopyobject() function copies an eaobjectt. 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
egnobjs and egobjs fields are set to 0 and NUL, respec-
tively. Use eacopytree() to copy recursively a group or a
list of items.
The eacopyobjecttree() function recursively copies an
eaobjectt. All elements in the eonext list are copied,
and any group objects are recursively copied. The returned
object can be completely freed with eafreeobject(3EXACT)
by specifying the EUPALOC flag.
The eagetobjecttree() function reads in nobj top-level
objects from the file, returning the same data structure
that would have originally been passed to eawriteobject().
On encountering a group object, the eagetobject() function
reads only the group header part of the group, whereas
eagetobjecttree() reads the group and all its member
SunOS 5.11 Last change: 4 Oct 2007 3
Extended Accounting File Access Library Functions
eapackobject(3EXACT)
items, recursing into sub-records if necessary. The returned
object data structure can be completely freed with
eafreeobject() by specifying the EUPALOC flag.
RETURN VALUES
The eapackobject() function returns the number of bytes
required to hold the exacct object being operated upon. If
the returned size exceeds bufsize, the pack operation does
not complete and the function returns (sizet) -1 and sets
the extended accounting error code to indicate the error.
The eagetobject() function returns the eaobjecttype of
the object if the object was retrieved successfully. Other-
wise, it returns EOEROR and sets the extended accounting
error code to indicate the error.
The eanextobject() function returns the eaobjecttype of
the next exacct object in the file. It returns EOEROR if
the exacct file is corrupted sets the extended accounting
error code to indicate the error.
The eaunpackobject() function returns the eaobjecttype
of the first exacct object unpacked from the buffer. It
returns EOEROR if the exacct file is corrupted, and sets
the extended accounting error code to indicate the error.
The eawriteobject() function returns 0 on success. Other-
wise it returns -1 and sets the extended accounting error
code to indicate the error.
The eacopyobject() and eacopyobjecttree() functions
return the copied object on success. Otherwise they return
NUL and set the extended accounting error code to indicate
the error.
The eagetobjecttree() function returns the list of
objects read from the file on success. Otherwise it returns
NUL and sets the extended accounting error code to indicate
the error.
The extended account error code can be retrieved using
eaerror(3EXACT).
SunOS 5.11 Last change: 4 Oct 2007 4
Extended Accounting File Access Library Functions
eapackobject(3EXACT)
ERORS
These functions may fail if:
EXRSYSCALFAIL
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.
EXRCORUPTFILE
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 eaunpackbuffer() to indicate a
corrupted buffer.
EXREOF
The end of the file has been reached. In the case of
eapreviousrecord(), 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
eafilet ef;
eaobjectt *obj;
...
SunOS 5.11 Last change: 4 Oct 2007 5
Extended Accounting File Access Library Functions
eapackobject(3EXACT)
eaopen(&ef, "foo", ORDONLY, ...);
while ((obj = eagetobjecttree(&ef, 1)) != NUL) {
if (obj->eotype == EOITEM) {
/* handle item */
} else {
/* handle group */
}
eafreeobject(obj, EUPALOC);
}
if (eaerror() != EXREOF) {
/* handle error */
}
eaclose(&ef);
Example 2 Construct an exacct file consisting of a single
object containing the current process ID.
#include
#include
#include
...
eafilet ef;
eaobjectt obj;
pidt mypid;
eaopen(&ef, "foo", OCREAT OWRONLY, ...);
mypid = getpid();
easetitem(&obj, EXTUINT32 EXCDEFAULT EXTPROCPID, &mypid, 0);
(void) eawriteobject(&ef, &obj);
eaclose(&ef);
...
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 4 Oct 2007 6
Extended Accounting File Access Library Functions
eapackobject(3EXACT)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level MT-Safe
SEE ALSO
read(2), eaerror(3EXACT), eaopen(3EXACT),
easetitem(3EXACT), libexacct(3LIB), attributes(5)
SunOS 5.11 Last change: 4 Oct 2007 7
Extended Accounting File Access Library Functions
eapackobject(3EXACT)
SunOS 5.11 Last change: 4 Oct 2007 8
|
