Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
Extended Accounting File Access Library Functionsea_set_item(3EXACCT)


NAME

 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

SYNOPSIS

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

DESCRIPTION

 

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

RETURN VALUES

 

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

ERRORS

 

The ea_set_item(), ea_set_group(), and ea_match_object_catalog() 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.
EXR_INVALID_OBJECT
The passed object is of an incorrect type, for example passing a group object to ea_set_item().

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.
 

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

...

ATTRIBUTES

 

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

ATTRIBUTE TYPEATTRIBUTE VALUE
Interface StabilityEvolving
MT-LevelMT-Safe

SEE ALSO

 

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


SunOS 5.9Go To TopLast Changed 28 Nov 2001

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.