#

# Copyright 2005 Sun Microsystems, Inc. All rights reserved.

# Use is subject to license terms.

#

# CDDL HEADER START

#

# The contents of this file are subject to the terms of the

# Common Development and Distribution License, Version 1.0 only

# (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]

#

# CDDL HEADER END

#

#ident "%Z%%M% %I% %E% SMI"

#

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