ea_next_object man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

ea_pack_object(Extended Accounting File Access Library ea_pack_object(3EXACCT)

NAME
       ea_pack_object,	 ea_unpack_object,   ea_get_creator,  ea_get_hostname,
       ea_next_object,	ea_previous_object,  ea_get_object,   ea_write_object,
       ea_copy_object,	ea_copy_object_tree,  ea_get_object_tree  - construct,
       read, and write extended accounting records

SYNOPSIS
       cc [ flag... ] file... -lexacct [ library... ]
       #include <exacct.h>

       size_t ea_pack_object(ea_object_t *obj, void *buf,
	   size_t bufsize);

       ea_object_type_t ea_unpack_object(ea_object_t **objp, int flag,
	   void *buf, size_t bufsize);

       const char *ea_get_creator(ea_file_t *ef);

       const char *ea_get_hostname(ea_file_t *ef);

       ea_object_type_t ea_next_object(ea_file_t *ef, ea_object_t *obj);

       ea_object_type_t ea_previous_object(ea_file_t *ef,
	   ea_object_t *obj);

       ea_object_type_t ea_get_object(ea_file_t *ef, ea_object_t *obj);

       int ea_write_object(ea_file_t *ef, ea_object_t *obj);

       ea_object_type_t *ea_copy_object(const ea_object_t *src);

       ea_object_type_t *ea_copy_object_tree(const ea_object_t *src);

       ea_object_type_t *ea_get_object_tree(ea_file_t *ef,
	   uint32_tnobj);

DESCRIPTION
       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 opera‐
       tion 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 repre‐
       sent 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 represent‐
       ing the recorded creator of  the	 exacct	 file.	The  ea_get_hostname()
       function	 returns a pointer to a string representing the recorded host‐
       name 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 account‐
       ing 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, acces‐
       sible 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.

RETURN VALUES
       The  ea_pack_object()  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 (size_t) -1 and sets the	 extended  accounting  error  code  to
       indicate the error.

       The  ea_get_object()  function returns the ea_object_type of the object
       if  the	object	was  retrieved	successfully.  Otherwise,  it  returns
       EO_ERROR	 and  sets  the extended accounting error code to indicate the
       error.

       The ea_next_object() function returns the ea_object_type	 of  the  next
       exacct  object  in the file.  It returns EO_ERROR if the exacct file is
       corrupted sets the extended  accounting	error  code  to	 indicate  the
       error.

       The ea_unpack_object() function returns the ea_object_type of the first
       exacct object unpacked from the buffer.	It  returns  EO_ERROR  if  the
       exacct  file  is corrupted, and sets the extended accounting error code
       to indicate the error.

       The ea_write_object() function  returns	0  on  success.	 Otherwise  it
       returns	−1 and sets the extended accounting error code to indicate the
       error.

       The ea_copy_object() and	 ea_copy_object_tree()	functions  return  the
       copied  object  on  success.  Otherwise	they  return  NULL and set the
       extended accounting error code to indicate the error.

       The ea_get_object_tree() function returns the list of objects read from
       the  file  on  success. Otherwise it returns NULL and sets the extended
       accounting error code to indicate the error.

       The   extended	account	  error	  code	 can   be   retrieved	 using
       ea_error(3EXACCT).

ERRORS
       These 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.  On	memory
	   allocation failure, errno will be set to ENOMEM.

       EXR_CORRUPT_FILE

	   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.

       EXR_EOF

	   The	end  of	 the  file has been reached.  In the case of ea_previ‐
	   ous_record(), the previous record  could  not  be  reached,	either
	   because  the head of the file was encountered or because the previ‐
	   ous 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 pro‐
       cesses. 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 ((obj = ea_get_object_tree(&ef, 1)) != NULL) {
	    if (obj->eo_type == EO_ITEM) {
		/* handle item */
	    } else {
		/* handle group */
	    }
	    ea_free_object(obj, EUP_ALLOC);
	 }

	 if (ea_error() != EXR_EOF) {
	    /* handle error */
	 }

	 ea_close(&ef);

       Example 2 Construct an exacct file consisting of a single  object  con‐
       taining 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;

	 ea_open(&ef, "foo", O_CREAT | O_WRONLY, ...);

	 my_pid = getpid();
	 ea_set_item(&obj, EXT_UINT32 | EXC_DEFAULT | EXT_PROC_PID, &my_pid, 0);
	 (void) ea_write_object(&ef, &obj);

	 ea_close(&ef);

	 ...

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

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Committed			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       read(2),	  ea_error(3EXACCT),  ea_open(3EXACCT),	 ea_set_item(3EXACCT),
       libexacct(3LIB), attributes(5)

SunOS 5.10			  4 Oct 2007	       ea_pack_object(3EXACCT)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net