#

# 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::File documentation.

#

=head1 NAME

Sun::Solaris::Exacct::File - exacct file manipulation

=head1 SYNOPSIS

use Sun::Solaris::Exacct::File qw(:ALL);

my $ea_file = Sun::Solaris::Exacct::File->new($myfile, &O_RDONLY);

my $ea_obj = $ea_file->get();

This module provides access to the C<libexacct(3LIB)> functions that

manipulate accounting files. The interface is object-oriented and allows the

creation and reading of libexacct files. The C library calls wrapped by this

module are C<ea_open(3EAXACCT)>, C<ea_close(3EAXACCT)>,

C<ea_next_object(3EAXACCT)>, C<ea_previous_object(3EAXACCT)>,

C<ea_write_object(3EAXACCT)>, C<ea_get_object(3EAXACCT)>,

C<ea_get_creator(3EAXACCT)>, and C<ea_get_hostname(3EAXACCT)>. The file read

and write methods all operate on C<Sun::Solaris::Exacct::Object> objects and

perform all the necessary memory management, packing, unpacking, and structure

conversions that are required.

=head2 Constants

C<EO_HEAD>, C<EO_TAIL>, C<EO_NO_VALID_HDR>, C<EO_POSN_MSK>, and

C<EO_VALIDATE_MSK>. Other constants needed by the C<new()> method below are in

the standard Perl C<Fcntl> module.

=head2 Functions

None.

=head2 Class methods

B<C<< new($name, $oflags, creator => $creator,

aflags => $aflags, mode => $mode) >>>

This method opens a libexacct file as specified by the mandatory parameters

C<$name> and C<$oflags>, and returns a C<Sun::Solaris::Exacct::File> object,

or C<undef> if an error occurs. The parameters C<$creator>, C<$aflags>, and

C<$mode> are optional and are passed as C<(name => value)> pairs. The only

valid values for C<$oflags> are the combinations of C<O_RDONLY>, C<O_WRONLY>,

C<O_RDWR>, and C<O_CREAT> described below.

The C<$creator> parameter is a string describing the creator of the file. If

it is required (for instance, when writing to a file) but absent, it is set to

the string representation of the caller's UID. The C<$aflags> parameter

describes the required positioning in the file for C<O_RDONLY> access: either

C<EO_HEAD> or C<EO_TAIL> are allowed. If absent, C<EO_HEAD> is assumed. The

C<$mode> parameter is the file creation mode and is ignored unless C<O_CREAT>

is specified in C<$oflags>. If C<$mode> is unspecified, the file creation mode

is set to C<0666> (octal). If an error occurs, it can be retrieved with the

C<Sun::Solaris::Exacct::ea_error()> function.

(See C<Sun::Solaris::Exacct(3)>).

B<C< $oflags $aflags Action>>

O_RDONLY Absent or EO_HEAD Open for reading

at the start of

the file.

O_RDONLY EO_TAIL Open for reading

at the end of the

file.

O_WRONLY Ignored File must exist,

open for writing

at the end of the

file.

O_WRONLY | O_CREAT Ignored Create file if it

does not exist,

otherwise truncate

and open for writing.

O_RDWR Ignored File must exist,

open for

reading/writing,

positioned at the

end of the file.

O_RDWR | O_CREAT Ignored Create file if it

does not exist,

otherwise truncate

and open for

reading/writing.

=head2 Object methods

B<Note:> Closing a C<Sun::Solaris::Exacct::File>

There is no explicit C<close()> method for a C<Sun::Solaris::Exacct::File>.

The file is closed when the file handle object is undefined or reassigned.

B<C<creator()>>

This method returns a string containing the creator of the file or C<undef> if

the file does not contain the information.

B<C<hostname()>>

This method returns a string containing the hostname on which the file was

created, or C<undef> if the file does not contain the information.

B<C<next()>>

This method reads the header information of the next record in the file. In a

scalar context the value of the type field is returned as a dual-typed scalar

that will be one of C<EO_ITEM>, C<EO_GROUP>, or C<EO_NONE>. In a list context

it returns a two-element list containing the values of the type and catalog

fields. The type element is a dual-typed scalar. The catalog element is

blessed into the C<Sun::Solaris::Exacct::Catalog> class. If an error occurs,

C<undef> or C<(undef, undef)> is returned depending upon context. The status

can be accessed with the C<Sun::Solaris::Exacct::ea_error()> function. (See

C<Sun::Solaris::Exacct(3)>).

B<C<previous()>>

This method reads the header information of the previous record in the file.

In a scalar context it returns the type field. In a list context it returns

the two element list containing the values of the type and catalog fields, in

the same manner as the C<next()> method. Error are also returned in the same

manner as the C<next()> method.

B<C<get()>>

This method reads in the libexacct record at the current position in the file

and returns a C<Sun::Solaris::Exacct::Object> containing the unpacked data

from the file. This object can then be further manipulated using its methods.

In case of error C<undef> is returned and the error status is made available

with the C<Sun::Solaris::Exacct::ea_error()> function. After this operation,

the position in the file is set to the start of the next record in the file.

B<C<write(@ea_obj)>>

This method converts the passed list of C<Sun::Solaris::Exacct::Object>s into

libexacct file format and appends them to the libexacct file, which must be

open for writing. This method returns C<true> if successful and C<false>

otherwise. On failure the error can be examined with the

C<Sun::Solaris::Exacct::ea_error()> function.

=head2 Exports

By default nothing is exported from this module. The following tags can be

used to selectively import constants defined in this module:

:CONSTANTS EO_HEAD, EO_TAIL, EO_NO_VALID_HDR, EO_POSN_MSK, and

EO_VALIDATE_MSK

:ALL :CONSTANTS, Fcntl(:DEFAULT).

=head1 ATTRIBUTES

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

___________________________________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

|_____________________________|_____________________________|

| Availability | SUNWpl5u |

|_____________________________|_____________________________|

| Interface Stability | CPAN (http://www.cpan.org) |

|_____________________________|_____________________________|

=head1 SEE ALSO

C<ea_close(3EXACCT)>, C<ea_get_creator(3EXACCT)>, C<ea_get_hostname(3EXACCT)>,

C<ea_get_object(3EXACCT)>, C<ea_next_object(3EXACCT)>, C<ea_open(3EXACCT)>,

C<ea_previous_object(3EXACCT)>, C<ea_write_object(3EXACCT)>,

C<Sun::Solaris::Exacct(3)>, C<Sun::Solaris::Exacct::Catalog(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)>