diff options
Diffstat (limited to 'usr/src/man/man3perl/Exacct::File.3perl')
| -rw-r--r-- | usr/src/man/man3perl/Exacct::File.3perl | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/usr/src/man/man3perl/Exacct::File.3perl b/usr/src/man/man3perl/Exacct::File.3perl new file mode 100644 index 0000000000..4246148720 --- /dev/null +++ b/usr/src/man/man3perl/Exacct::File.3perl @@ -0,0 +1,246 @@ +'\" 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 "1 Dec 2002" "SunOS 5.11" "Perl Library Functions" +.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 +.mk +.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 +tab(); +cw(1.83i) cw(1.83i) cw(1.83i) +lw(1.83i) lw(1.83i) lw(1.83i) +. +\fB$oflags\fR\fB$aflags\fRAction +\fBO_RDONLY\fRAbsent or \fBEO_HEAD\fRT{ +Open for reading at the start of the file. +T} +\fBO_RDONLY\fR\fBEO_TAIL\fROpen for reading at the end of the file. +\fBO_WRONLY\fRIgnoredT{ +File must exist, open for writing at the end of the file. +T} +\fBO_WRONLY\fR | \fBO_CREAT\fRIgnoredT{ +Create file if it does not exist, otherwise truncate and open for writing. +T} +\fBO_RDWR\fRIgnoredT{ +File must exist, open for reading/writing, positioned at the end of the file. +T} +\fBO_RDWR\fR | \fBO_CREAT\fRIgnoredT{ +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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +.mk +.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 +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +.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) |