1 '\" te
   2 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH EXACCT::FILE 3PERL "Dec 1, 2002"
   7 .SH NAME
   8 Exacct::File \- exacct file manipulation
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 use Sun::Solaris::Exacct::File qw(:ALL);
  13 my $ea_file = Sun::Solaris::Exacct::File->new($myfile, &O_RDONLY);
  14 my $ea_obj = $ea_file->get();
  15 .fi
  16 
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 This module provides access to the \fBlibexacct\fR(3LIB) functions that
  21 manipulate accounting files. The interface is object-oriented and allows the
  22 creation and reading of \fBlibexacct\fR files. The C library calls wrapped by
  23 this module are \fBea_open\fR(3EXACCT), \fBea_close\fR(3EXACCT),
  24 \fBea_next_object\fR(3EXACCT), \fBea_previous_object\fR(3EXACCT),
  25 \fBea_write_object\fR(3EXACCT), \fBea_get_object\fR(3EXACCT),
  26 \fBea_get_creator\fR(3EXACCT), and \fBea_get_hostname\fR(3EXACCT).  The file
  27 read and write methods all operate on \fBSun::Solaris::Exacct::Object\fR
  28 objects and perform all the necessary memory management, packing, unpacking,
  29 and structure conversions that are required.
  30 .SS "Constants"
  31 .sp
  32 .LP
  33 \fBEO_HEAD\fR, \fBEO_TAIL\fR, \fBEO_NO_VALID_HDR\fR, \fBEO_POSN_MSK\fR, and
  34 \fBEO_VALIDATE_MSK\fR.  Other constants needed by the \fBnew()\fR method below
  35 are in the standard Perl Fcntl module.
  36 .SS "Functions"
  37 .sp
  38 .LP
  39 None.
  40 .SS "Class methods"
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fBnew($name, $oflags, creator => $creator,\fR\fR
  45 .ad
  46 .sp .6
  47 .RS 4n
  48 This method opens a \fBlibexacct\fR file as specified by the mandatory
  49 parameters \fB$name\fR and \fB$oflags\fR, and returns a
  50 \fBSun::Solaris::Exacct::File\fR object, or \fBundef\fR if an error occurs. The
  51 parameters \fB$creator\fR, \fB$aflags\fR, and \fB$mode\fR are optional and are
  52 passed as (\fBname\fR => \fBvalue\fR) pairs. The only valid values for
  53 \fB$oflags\fR are the combinations of \fBO_RDONLY\fR, \fBO_WRONLY\fR,
  54 \fBO_RDWR\fR, and \fBO_CREAT\fR described below.
  55 .sp
  56 The \fB$creator\fR parameter is a string describing the creator of the file. If
  57 it is required (for instance, when writing to a file) but absent, it is set to
  58 the string representation of the caller's UID. The \fB$aflags\fR parameter
  59 describes the required positioning in the file for \fBO_RDONLY\fR access:
  60 either \fBEO_HEAD\fR or \fBEO_TAIL\fR are allowed.  If absent, \fBEO_HEAD\fR is
  61 assumed.  The \fB$mode\fR parameter is the file creation mode and is ignored
  62 unless \fBO_CREAT\fR is specified in \fB$oflags\fR. If \fB$mode\fR is
  63 unspecified, the file creation mode is set to 0666 (octal). If an error occurs,
  64 it can be retrieved with the \fBSun::Solaris::Exacct::ea_error()\fR function.
  65 See \fBExacct\fR(3PERL).
  66 .sp
  67 
  68 .sp
  69 .TS
  70 c c c
  71 l l l .
  72 \fB$oflags\fR   \fB$aflags\fR   Action
  73 \fBO_RDONLY\fR  Absent or \fBEO_HEAD\fR T{
  74 Open for reading at the start of the file.
  75 T}
  76 \fBO_RDONLY\fR  \fBEO_TAIL\fR   Open for reading at the end of the file.
  77 \fBO_WRONLY\fR  Ignored T{
  78 File must exist, open for writing at the end of the file.
  79 T}
  80 \fBO_WRONLY\fR | \fBO_CREAT\fR  Ignored T{
  81 Create file if it does not exist, otherwise truncate and open for writing.
  82 T}
  83 \fBO_RDWR\fR    Ignored T{
  84 File must exist, open for reading/writing, positioned at the end of the file.
  85 T}
  86 \fBO_RDWR\fR | \fBO_CREAT\fR    Ignored T{
  87 Create file if it does not exist, otherwise truncate and open for reading/writing.
  88 T}
  89 .TE
  90 
  91 .RE
  92 
  93 .SS "Object methods"
  94 .sp
  95 .LP
  96 There is no explicit \fBclose()\fR method for a
  97 \fBSun::Solaris::Exacct::File\fR. The file is closed when the file handle
  98 object is undefined or reassigned.
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBcreator()\fR\fR
 103 .ad
 104 .sp .6
 105 .RS 4n
 106 This method returns a string containing the creator of the file or \fBundef\fR
 107 if the file does not contain the information.
 108 .RE
 109 
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBhostname()\fR\fR
 114 .ad
 115 .sp .6
 116 .RS 4n
 117 This method returns a string containing the hostname on which the file was
 118 created, or \fBundef\fR if the file does not contain the information.
 119 .RE
 120 
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBnext()\fR\fR
 125 .ad
 126 .sp .6
 127 .RS 4n
 128 This method reads the header information of the next record in the file. In a
 129 scalar context the value of the type field is returned as a dual-typed scalar
 130 that will be one of \fBEO_ITEM\fR, \fBEO_GROUP\fR, or \fBEO_NONE\fR. In a list
 131 context it returns a two-element list containing the values of the type and
 132 catalog fields. The type element is a dual-typed scalar. The catalog element is
 133 blessed into the \fBSun::Solaris::Exacct::Catalog\fR class. If an error occurs,
 134 \fBundef\fR or (\fBundef\fR, \fBundef\fR) is returned depending upon context.
 135 The status can be accessed with the \fBSun::Solaris::Exacct::ea_error()\fR
 136 function.See \fBExacct\fR(3PERL).
 137 .RE
 138 
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBprevious()\fR\fR
 143 .ad
 144 .sp .6
 145 .RS 4n
 146 This method reads the header information of the previous record in the file. In
 147 a scalar context it returns the type field. In a list context it returns the
 148 two-element list containing the values of the type and catalog fields, in the
 149 same manner as the \fBnext()\fR method. Error are also returned in the same
 150 manner as the \fBnext()\fR method.
 151 .RE
 152 
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBget()\fR\fR
 157 .ad
 158 .sp .6
 159 .RS 4n
 160 This method reads in the \fBlibexacct\fR record at the current position in the
 161 file and returns a \fBSun::Solaris::Exacct::Object\fR containing the unpacked
 162 data from the file.  This object can then be further manipulated using its
 163 methods.  In case of error undef is returned and the error status is made
 164 available with the \fBSun::Solaris::Exacct::ea_error()\fR function.  After this
 165 operation, the position in the file is set to the start of the next record in
 166 the file.
 167 .RE
 168 
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBwrite(@ea_obj)\fR\fR
 173 .ad
 174 .sp .6
 175 .RS 4n
 176 This method converts the passed list of Sun::Solaris::Exacct::Objects into
 177 \fBlibexacct\fR file format and appends them to the \fBlibexacct\fR file, which
 178 must be open for writing. This method returns true if successful and false
 179 otherwise.  On failure the error can be examined with the
 180 \fBSun::Solaris::Exacct::ea_error()\fR function.
 181 .RE
 182 
 183 .SS "Exports"
 184 .sp
 185 .LP
 186 By default nothing is exported from this module. The following tags can be used
 187 to selectively import constants defined in this module:
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fB:CONSTANTS\fR\fR
 192 .ad
 193 .sp .6
 194 .RS 4n
 195 \fBEO_HEAD\fR, \fBEO_TAIL\fR, \fBEO_NO_VALID_HDR\fR, \fBEO_POSN_MSK\fR, and
 196 \fBEO_VALIDATE_MSK\fR
 197 .RE
 198 
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fB:ALL\fR\fR
 203 .ad
 204 .sp .6
 205 .RS 4n
 206 \fB:CONSTANTS\fR, Fcntl(\fB:DEFAULT\fR).
 207 .RE
 208 
 209 .SH ATTRIBUTES
 210 .sp
 211 .LP
 212 See \fBattributes\fR(5) for descriptions of the following attributes:
 213 .sp
 214 
 215 .sp
 216 .TS
 217 box;
 218 c | c
 219 l | l .
 220 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 221 _
 222 Interface Stability     Evolving
 223 .TE
 224 
 225 .SH SEE ALSO
 226 .sp
 227 .LP
 228 \fBea_close\fR(3EXACCT), \fBea_get_creator\fR(3EXACCT),
 229 \fBea_get_hostname\fR(3EXACCT), \fBea_get_object\fR(3EXACCT),
 230 \fBea_next_object\fR(3EXACCT), \fBea_open\fR(3EXACCT),
 231 \fBea_previous_object\fR(3EXACCT), \fBea_write_object\fR(3EXACCT),
 232 \fBExacct\fR(3PERL), \fBExacct::Catalog\fR(3PERL), \fBExacct::Object\fR(3PERL),
 233 \fBExacct::Object::Group\fR(3PERL), \fBExacct::Object::Item\fR(3PERL),
 234 \fBlibexacct\fR(3LIB), \fBattributes\fR(5)