te
Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
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

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);

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).

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).

The ea_set_item(), ea_set_group(), and ea_match_object_catalog() functions may fail if: EXR_SYSCALL_FAIL

EXR_INVALID_OBJECT

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.

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));

...

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Evolving

MT-Level MT-Safe

read (2), ea_error (3EXACCT), ea_open (3EXACCT), ea_pack_object (3EXACCT), libexacct (3LIB), attributes (7)