path: root/usr/src/man/man3perl/Exacct::File.3perl

'\" te
.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (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]
.TH EXACCT::FILE 3PERL "Dec 1, 2002"
.SH NAME
Exacct::File \- exacct file manipulation
.SH SYNOPSIS
.LP
.nf
use Sun::Solaris::Exacct::File qw(:ALL);
my $ea_file = Sun::Solaris::Exacct::File->new($myfile, &O_RDONLY);
my $ea_obj = $ea_file->get();
.fi

.SH DESCRIPTION
.sp
.LP
This module provides access to the \fBlibexacct\fR(3LIB) functions that
manipulate accounting files. The interface is object-oriented and allows the
creation and reading of \fBlibexacct\fR files. The C library calls wrapped by
this module are \fBea_open\fR(3EXACCT), \fBea_close\fR(3EXACCT),
\fBea_next_object\fR(3EXACCT), \fBea_previous_object\fR(3EXACCT),
\fBea_write_object\fR(3EXACCT), \fBea_get_object\fR(3EXACCT),
\fBea_get_creator\fR(3EXACCT), and \fBea_get_hostname\fR(3EXACCT).  The file
read and write methods all operate on \fBSun::Solaris::Exacct::Object\fR
objects and perform all the necessary memory management, packing, unpacking,
and structure conversions that are required.
.SS "Constants"
.sp
.LP
\fBEO_HEAD\fR, \fBEO_TAIL\fR, \fBEO_NO_VALID_HDR\fR, \fBEO_POSN_MSK\fR, and
\fBEO_VALIDATE_MSK\fR.  Other constants needed by the \fBnew()\fR method below
are in the standard Perl Fcntl module.
.SS "Functions"
.sp
.LP
None.
.SS "Class methods"
.sp
.ne 2
.na
\fB\fBnew($name, $oflags, creator => $creator,\fR\fR
.ad
.sp .6
.RS 4n
This method opens a \fBlibexacct\fR file as specified by the mandatory
parameters \fB$name\fR and \fB$oflags\fR, and returns a
\fBSun::Solaris::Exacct::File\fR object, or \fBundef\fR if an error occurs. The
parameters \fB$creator\fR, \fB$aflags\fR, and \fB$mode\fR are optional and are
passed as (\fBname\fR => \fBvalue\fR) pairs. The only valid values for
\fB$oflags\fR are the combinations of \fBO_RDONLY\fR, \fBO_WRONLY\fR,
\fBO_RDWR\fR, and \fBO_CREAT\fR described below.
.sp
The \fB$creator\fR 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 \fB$aflags\fR parameter
describes the required positioning in the file for \fBO_RDONLY\fR access:
either \fBEO_HEAD\fR or \fBEO_TAIL\fR are allowed.  If absent, \fBEO_HEAD\fR is
assumed.  The \fB$mode\fR parameter is the file creation mode and is ignored
unless \fBO_CREAT\fR is specified in \fB$oflags\fR. If \fB$mode\fR is
unspecified, the file creation mode is set to 0666 (octal). If an error occurs,
it can be retrieved with the \fBSun::Solaris::Exacct::ea_error()\fR function.
See \fBExacct\fR(3PERL).
.sp

.sp
.TS
c c c
l l l .
\fB$oflags\fR	\fB$aflags\fR	Action
\fBO_RDONLY\fR	Absent or \fBEO_HEAD\fR	T{
Open for reading at the start of the file.
T}
\fBO_RDONLY\fR	\fBEO_TAIL\fR	Open for reading at the end of the file.
\fBO_WRONLY\fR	Ignored	T{
File must exist, open for writing at the end of the file.
T}
\fBO_WRONLY\fR | \fBO_CREAT\fR	Ignored	T{
Create file if it does not exist, otherwise truncate and open for writing.
T}
\fBO_RDWR\fR	Ignored	T{
File must exist, open for reading/writing, positioned at the end of the file.
T}
\fBO_RDWR\fR | \fBO_CREAT\fR	Ignored	T{
Create file if it does not exist, otherwise truncate and open for reading/writing.
T}
.TE

.RE

.SS "Object methods"
.sp
.LP
There is no explicit \fBclose()\fR method for a
\fBSun::Solaris::Exacct::File\fR. The file is closed when the file handle
object is undefined or reassigned.
.sp
.ne 2
.na
\fB\fBcreator()\fR\fR
.ad
.sp .6
.RS 4n
This method returns a string containing the creator of the file or \fBundef\fR
if the file does not contain the information.
.RE

.sp
.ne 2
.na
\fB\fBhostname()\fR\fR
.ad
.sp .6
.RS 4n
This method returns a string containing the hostname on which the file was
created, or \fBundef\fR if the file does not contain the information.
.RE

.sp
.ne 2
.na
\fB\fBnext()\fR\fR
.ad
.sp .6
.RS 4n
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 \fBEO_ITEM\fR, \fBEO_GROUP\fR, or \fBEO_NONE\fR. 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 \fBSun::Solaris::Exacct::Catalog\fR class. If an error occurs,
\fBundef\fR or (\fBundef\fR, \fBundef\fR) is returned depending upon context.
The status can be accessed with the \fBSun::Solaris::Exacct::ea_error()\fR
function.See \fBExacct\fR(3PERL).
.RE

.sp
.ne 2
.na
\fB\fBprevious()\fR\fR
.ad
.sp .6
.RS 4n
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 \fBnext()\fR method. Error are also returned in the same
manner as the \fBnext()\fR method.
.RE

.sp
.ne 2
.na
\fB\fBget()\fR\fR
.ad
.sp .6
.RS 4n
This method reads in the \fBlibexacct\fR record at the current position in the
file and returns a \fBSun::Solaris::Exacct::Object\fR containing the unpacked
data from the file.  This object can then be further manipulated using its
methods.  In case of error undef is returned and the error status is made
available with the \fBSun::Solaris::Exacct::ea_error()\fR function.  After this
operation, the position in the file is set to the start of the next record in
the file.
.RE

.sp
.ne 2
.na
\fB\fBwrite(@ea_obj)\fR\fR
.ad
.sp .6
.RS 4n
This method converts the passed list of Sun::Solaris::Exacct::Objects into
\fBlibexacct\fR file format and appends them to the \fBlibexacct\fR file, which
must be open for writing. This method returns true if successful and false
otherwise.  On failure the error can be examined with the
\fBSun::Solaris::Exacct::ea_error()\fR function.
.RE

.SS "Exports"
.sp
.LP
By default nothing is exported from this module. The following tags can be used
to selectively import constants defined in this module:
.sp
.ne 2
.na
\fB\fB:CONSTANTS\fR\fR
.ad
.sp .6
.RS 4n
\fBEO_HEAD\fR, \fBEO_TAIL\fR, \fBEO_NO_VALID_HDR\fR, \fBEO_POSN_MSK\fR, and
\fBEO_VALIDATE_MSK\fR
.RE

.sp
.ne 2
.na
\fB\fB:ALL\fR\fR
.ad
.sp .6
.RS 4n
\fB:CONSTANTS\fR, Fcntl(\fB:DEFAULT\fR).
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
\fBea_close\fR(3EXACCT), \fBea_get_creator\fR(3EXACCT),
\fBea_get_hostname\fR(3EXACCT), \fBea_get_object\fR(3EXACCT),
\fBea_next_object\fR(3EXACCT), \fBea_open\fR(3EXACCT),
\fBea_previous_object\fR(3EXACCT), \fBea_write_object\fR(3EXACCT),
\fBExacct\fR(3PERL), \fBExacct::Catalog\fR(3PERL), \fBExacct::Object\fR(3PERL),
\fBExacct::Object::Group\fR(3PERL), \fBExacct::Object::Item\fR(3PERL),
\fBlibexacct\fR(3LIB), \fBattributes\fR(5)