1# 2# Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved. 3# 4 5# 6# Sun::Solaris::Exacct::File documentation. 7# 8 9=head1 NAME 10 11Sun::Solaris::Exacct::File - exacct file manipulation 12 13=head1 SYNOPSIS 14 15 use Sun::Solaris::Exacct::File qw(:ALL); 16 my $ea_file = Sun::Solaris::Exacct::File->new($myfile, &O_RDONLY); 17 my $ea_obj = $ea_file->get(); 18 19This module provides access to the C<libexacct(3LIB)> functions that 20manipulate accounting files. The interface is object-oriented and allows the 21creation and reading of libexacct files. The C library calls wrapped by this 22module are C<ea_open(3EAXACCT)>, C<ea_close(3EAXACCT)>, 23C<ea_next_object(3EAXACCT)>, C<ea_previous_object(3EAXACCT)>, 24C<ea_write_object(3EAXACCT)>, C<ea_get_object(3EAXACCT)>, 25C<ea_get_creator(3EAXACCT)>, and C<ea_get_hostname(3EAXACCT)>. The file read 26and write methods all operate on C<Sun::Solaris::Exacct::Object> objects and 27perform all the necessary memory management, packing, unpacking, and structure 28conversions that are required. 29 30=head2 Constants 31 32C<EO_HEAD>, C<EO_TAIL>, C<EO_NO_VALID_HDR>, C<EO_POSN_MSK>, and 33C<EO_VALIDATE_MSK>. Other constants needed by the C<new()> method below are in 34the standard Perl C<Fcntl> module. 35 36=head2 Functions 37 38None. 39 40=head2 Class methods 41 42B<C<< new($name, $oflags, creator => $creator, 43 aflags => $aflags, mode => $mode) >>> 44 45This method opens a libexacct file as specified by the mandatory parameters 46C<$name> and C<$oflags>, and returns a C<Sun::Solaris::Exacct::File> object, 47or C<undef> if an error occurs. The parameters C<$creator>, C<$aflags>, and 48C<$mode> are optional and are passed as C<(name => value)> pairs. The only 49valid values for C<$oflags> are the combinations of C<O_RDONLY>, C<O_WRONLY>, 50C<O_RDWR>, and C<O_CREAT> described below. 51 52The C<$creator> parameter is a string describing the creator of the file. If 53it is required (for instance, when writing to a file) but absent, it is set to 54the string representation of the caller's UID. The C<$aflags> parameter 55describes the required positioning in the file for C<O_RDONLY> access: either 56C<EO_HEAD> or C<EO_TAIL> are allowed. If absent, C<EO_HEAD> is assumed. The 57C<$mode> parameter is the file creation mode and is ignored unless C<O_CREAT> 58is specified in C<$oflags>. If C<$mode> is unspecified, the file creation mode 59is set to C<0666> (octal). If an error occurs, it can be retrieved with the 60C<Sun::Solaris::Exacct::ea_error()> function. 61(See C<Sun::Solaris::Exacct(3)>). 62 63B<C< $oflags $aflags Action>> 64 65 O_RDONLY Absent or EO_HEAD Open for reading 66 at the start of 67 the file. 68 69 O_RDONLY EO_TAIL Open for reading 70 at the end of the 71 file. 72 73 O_WRONLY Ignored File must exist, 74 open for writing 75 at the end of the 76 file. 77 78 O_WRONLY | O_CREAT Ignored Create file if it 79 does not exist, 80 otherwise truncate 81 and open for writing. 82 83 O_RDWR Ignored File must exist, 84 open for 85 reading/writing, 86 positioned at the 87 end of the file. 88 89 O_RDWR | O_CREAT Ignored Create file if it 90 does not exist, 91 otherwise truncate 92 and open for 93 reading/writing. 94 95=head2 Object methods 96 97B<Note:> Closing a C<Sun::Solaris::Exacct::File> 98 99There is no explicit C<close()> method for a C<Sun::Solaris::Exacct::File>. 100The file is closed when the file handle object is undefined or reassigned. 101 102B<C<creator()>> 103 104This method returns a string containing the creator of the file or C<undef> if 105the file does not contain the information. 106 107B<C<hostname()>> 108 109This method returns a string containing the hostname on which the file was 110created, or C<undef> if the file does not contain the information. 111 112B<C<next()>> 113 114This method reads the header information of the next record in the file. In a 115scalar context the value of the type field is returned as a dual-typed scalar 116that will be one of C<EO_ITEM>, C<EO_GROUP>, or C<EO_NONE>. In a list context 117it returns a two-element list containing the values of the type and catalog 118fields. The type element is a dual-typed scalar. The catalog element is 119blessed into the C<Sun::Solaris::Exacct::Catalog> class. If an error occurs, 120C<undef> or C<(undef, undef)> is returned depending upon context. The status 121can be accessed with the C<Sun::Solaris::Exacct::ea_error()> function. (See 122C<Sun::Solaris::Exacct(3)>). 123 124B<C<previous()>> 125 126This method reads the header information of the previous record in the file. 127In a scalar context it returns the type field. In a list context it returns 128the two element list containing the values of the type and catalog fields, in 129the same manner as the C<next()> method. Error are also returned in the same 130manner as the C<next()> method. 131 132B<C<get()>> 133 134This method reads in the libexacct record at the current position in the file 135and returns a C<Sun::Solaris::Exacct::Object> containing the unpacked data 136from the file. This object can then be further manipulated using its methods. 137In case of error C<undef> is returned and the error status is made available 138with the C<Sun::Solaris::Exacct::ea_error()> function. After this operation, 139the position in the file is set to the start of the next record in the file. 140 141B<C<write(@ea_obj)>> 142 143This method converts the passed list of C<Sun::Solaris::Exacct::Object>s into 144libexacct file format and appends them to the libexacct file, which must be 145open for writing. This method returns C<true> if successful and C<false> 146otherwise. On failure the error can be examined with the 147C<Sun::Solaris::Exacct::ea_error()> function. 148 149=head2 Exports 150 151By default nothing is exported from this module. The following tags can be 152used to selectively import constants defined in this module: 153 154 :CONSTANTS EO_HEAD, EO_TAIL, EO_NO_VALID_HDR, EO_POSN_MSK, and 155 EO_VALIDATE_MSK 156 157 :ALL :CONSTANTS, Fcntl(:DEFAULT). 158 159=head1 ATTRIBUTES 160 161See C<attributes(5)> for descriptions of the following attributes: 162 163 ___________________________________________________________ 164 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 165 |_____________________________|_____________________________| 166 | Availability | SUNWpl5u | 167 |_____________________________|_____________________________| 168 | Interface Stability | CPAN (http://www.cpan.org) | 169 |_____________________________|_____________________________| 170 171=head1 SEE ALSO 172 173C<ea_close(3EXACCT)>, C<ea_get_creator(3EXACCT)>, C<ea_get_hostname(3EXACCT)>, 174C<ea_get_object(3EXACCT)>, C<ea_next_object(3EXACCT)>, C<ea_open(3EXACCT)>, 175C<ea_previous_object(3EXACCT)>, C<ea_write_object(3EXACCT)>, 176C<Sun::Solaris::Exacct(3)>, C<Sun::Solaris::Exacct::Catalog(3)>, 177C<Sun::Solaris::Exacct::Object(3)>, C<Sun::Solaris::Exacct::Object::Group(3)>, 178C<Sun::Solaris::Exacct::Object::Item(3)>, C<libexacct(3LIB)>, C<attributes(5)> 179