#
# Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved.
#

#
# Sun::Solaris::Exacct documentation.
# 

=head1 NAME

Sun::Solaris::Exacct - exacct system calls and error handling

=head1 SYNOPSIS

 use Sun::Solaris::Exacct qw(:EXACCT_ALL);
 my $ea_rec = getacct(P_PID, $$);

This module provides access to the C<ea_error(3EXACCT)> function and for all the
extended accounting system calls. Constants from the various C<libexacct(3LIB)>
header files are also provided.

=head2 Constants

The C<P_PID>, C<P_TASKID>, C<P_PROJID> and all the C<EW_*>, C<EP_*>, C<EXR_*>
macros are provided as Perl constants.

=head2 Functions

B<C<getacct($idtype, $id)>>

The C<$idtype> parameter must be either C<P_TASKID> or C<P_PID> and C<$id>
must be a corresponding task or process ID. This function returns an object of
type C<Sun::Solaris::Exacct::Object>, representing the unpacked accounting
buffer returned by the underlying C<getacct(2)> system call. In the event of
error, C<undef> is returned.

B<C<putacct($idtype, $id, $record)>>

The C<$idtype> parameter must be either C<P_TASKID> or C<P_PID> and C<$id>
must be a corresponding task or process ID. If C<$record> is of type
C<Sun::Solaris::Exacct::Object>, it is converted to the corresponding packed
libexacct object and passed to the C<putacct(2)> system call. If C<$record> is
not of type C<Sun::Solaris::Exacct::Object> it is converted to a string using
the normal Perl conversion rules and stored as a raw buffer. For predictable
and endian-independent results, any raw buffers should be constructed using
the Perl C<pack()> function. This function returns C<true> on success and
C<false> on failure.

B<C<wracct($idtype, $id, $flags)>>

The C<$idtype> parameter must be either C<P_TASKID> or C<P_PID> and $id must
be a corresponding task or process ID. The C<$flags> parameter must be either
C<EW_INTERVAL> or C<EW_PARTIAL>. The parameters are passed directly to the
underlying C<wracct(2)> system call. This function returns C<true> on success
and C<false> on failure.

B<C<ea_error()>>

This function provides access to the C<ea_error(3EXACCT)> function. It returns
a double-typed scalar that in a numeric context will be one of the C<EXR_*>
constants. In a string context it will be a descriptive error message. This is
the exacct equivalent to the C<$!> (C<errno>) Perl variable.

B<C<ea_error_str()>>

This function returns a double-typed scalar that in a numeric context will be
one of the C<EXR_*> constants as returned by C<ea_error>. In a string context
it describes the value returned by C<ea_error>. If C<ea_error> returns
C<EXR_SYSCALL_FAIL>, the string value returned is the value returned by
C<strerror(3C)>. This function is provided as a convenience so that repeated
blocks of code like the following can be avoided:

 if (ea_error() == EXR_SYSCALL_FAIL) {
         print("error: $!\n");
 } else {
         print("error: ", ea_error(), "\n");
 }

B<C<ea_register_catalog($cat_pfx, $catalog_id, $export, @idlist)>>

This convenience function is a wrapper around the
C<< Sun::Solaris::Exacct::Catalog->register() >> method.

B<C<ea_new_catalog($integer)>>

B<C<ea_new_catalog($cat_obj)>>

B<C<ea_new_catalog($type, $catalog, $id)>>

These convenience functions are wrappers around the
C<< Sun::Solaris::Exacct::Catalog->new() >> method. See
C<Sun::Solaris::Exacct::Catalog(3)>.

B<C<< ea_new_file($name, $oflags, creator => $creator,
    aflags => $aflags, mode => $mode) >>>

This convenience function is a wrapper around the
C<< Sun::Solaris::Exacct::File->new() >> method. See
C<Sun::Solaris::Exacct::File(3)>.

B<C<ea_new_item($catalog, $value)>>

This convenience function is a wrapper around the
C<< Sun::Solaris::Exacct::Object::Item->new() >> method. See
C<Sun::Solaris::Exacct::Object::Item(3)>.

B<C<ea_new_group($catalog, @objects)>>

This convenience function is a wrapper around the
C<< Sun::Solaris::Exacct::Object::Group->new() >> method. See
C<Exacct::Object::Group(3)>.

B<C<ea_dump_object($object, $filehandle)>>

This convenience function is a wrapper around the
C<< Sun::Solaris::Exacct::Object->dump() >> method.  See
C<Sun::Solaris::Exacct::Object(3)>.

=head2 Class methods

None.

=head2 Object methods

None.

=head2 Exports

By default nothing is exported from this module. The following tags can be
used to selectively import constants and functions defined in this module:

 :SYSCALLS           getacct(), putacct(), and wracct()

 :LIBCALLS           ea_error() and ea_error_str()

 :CONSTANTS          P_PID, P_TASKID, P_PROJID, EW_*, EP_*, and EXR_*

 :SHORTHAND          ea_register_catalog(), ea_new_catalog(), ea_new_file(),
                     ea_new_item(), and ea_new_group()

 :ALL                :SYSCALLS, :LIBCALLS, :CONSTANTS, and :SHORTHAND

 :EXACCT_CONSTANTS   :CONSTANTS, plus the :CONSTANTS tags for
                     Sun::Solaris::Catalog, Sun::Solaris::File,
                     and Sun::Solaris::Object

 :EXACCT_ALL         :ALL, plus the :ALL tags for Sun::Solaris::Catalog,
                     Sun::Solaris::File, and Sun::Solaris::Object

=head1 ATTRIBUTES

See C<attributes(5)> for descriptions of the following attributes:

  ___________________________________________________________
 |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
 |_____________________________|_____________________________|
 | Availability                | CPAN (http://www.cpan.org)  |
 |_____________________________|_____________________________|
 | Interface Stability         | Evolving                    |
 |_____________________________|_____________________________|


=head1 SEE ALSO

C<getacct(2)>, C<putacct(2)>, C<wracct(2)>, C<ea_error(3EXACCT)>,
C<Sun::Solaris::Exacct::Catalog(3)>, C<Sun::Solaris::Exacct::File(3)>,
C<Sun::Solaris::Exacct::Object(3)>, C<Sun::Solaris::Exacct::Object::Group(3)>,
C<Sun::Solaris::Exacct::Object::Item(3)>, C<libexacct(3LIB)>, C<attributes(5)>

=head1 NOTES

The modules described in the C<Sun::Solaris::Exacct> manual pages make
extensive use of the Perl "double-typed scalar" facility. This facility allows
a scalar value to behave either as an integer or as a string, depending upon
context. It is the same behavior as exhibited by the C<$!> Perl variable
(C<errno>). It is useful because it avoids the need to map from an integer
value to the corresponding string to display a value. Some examples are
provided below:

 # Assume $obj is a Sun::Solaris::Exacct::Item
 my $type = $obj->type();

 # Print "2 EO_ITEM"
 printf("%d %s\n", $type, $type);

 # Behave as an integer, $i == 2
 my $i = 0 + $type;

 # Behave as a string, $s = "abc EO_ITEM xyx"
 my $s = "abc $type xyz";

Wherever a function or method is documented as returning a double-typed
scalar, the returned value exhibits this type of behavior.