2 # Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved.
6 # Sun::Solaris::Exacct::File documentation.
11 Sun::Solaris::Exacct::File - exacct file manipulation
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();
19 This module provides access to the C<libexacct(3LIB)> functions that
20 manipulate accounting files. The interface is object-oriented and allows the
21 creation and reading of libexacct files. The C library calls wrapped by this
22 module are C<ea_open(3EAXACCT)>, C<ea_close(3EAXACCT)>,
23 C<ea_next_object(3EAXACCT)>, C<ea_previous_object(3EAXACCT)>,
24 C<ea_write_object(3EAXACCT)>, C<ea_get_object(3EAXACCT)>,
25 C<ea_get_creator(3EAXACCT)>, and C<ea_get_hostname(3EAXACCT)>. The file read
26 and write methods all operate on C<Sun::Solaris::Exacct::Object> objects and
27 perform all the necessary memory management, packing, unpacking, and structure
28 conversions that are required.
32 C<EO_HEAD>, C<EO_TAIL>, C<EO_NO_VALID_HDR>, C<EO_POSN_MSK>, and
33 C<EO_VALIDATE_MSK>. Other constants needed by the C<new()> method below are in
34 the standard Perl C<Fcntl> module.
42 B<C<< new($name, $oflags, creator => $creator,
43 aflags => $aflags, mode => $mode) >>>
45 This method opens a libexacct file as specified by the mandatory parameters
46 C<$name> and C<$oflags>, and returns a C<Sun::Solaris::Exacct::File> object,
47 or C<undef> if an error occurs. The parameters C<$creator>, C<$aflags>, and
48 C<$mode> are optional and are passed as C<(name => value)> pairs. The only
49 valid values for C<$oflags> are the combinations of C<O_RDONLY>, C<O_WRONLY>,
50 C<O_RDWR>, and C<O_CREAT> described below.
52 The C<$creator> parameter is a string describing the creator of the file. If
53 it is required (for instance, when writing to a file) but absent, it is set to
54 the string representation of the caller's UID. The C<$aflags> parameter
55 describes the required positioning in the file for C<O_RDONLY> access: either
56 C<EO_HEAD> or C<EO_TAIL> are allowed. If absent, C<EO_HEAD> is assumed. The
57 C<$mode> parameter is the file creation mode and is ignored unless C<O_CREAT>
58 is specified in C<$oflags>. If C<$mode> is unspecified, the file creation mode
59 is set to C<0666> (octal). If an error occurs, it can be retrieved with the
60 C<Sun::Solaris::Exacct::ea_error()> function.
61 (See C<Sun::Solaris::Exacct(3)>).
63 B<C< $oflags $aflags Action>>
65 O_RDONLY Absent or EO_HEAD Open for reading
69 O_RDONLY EO_TAIL Open for reading
73 O_WRONLY Ignored File must exist,
78 O_WRONLY | O_CREAT Ignored Create file if it
83 O_RDWR Ignored File must exist,
89 O_RDWR | O_CREAT Ignored Create file if it
97 B<Note:> Closing a C<Sun::Solaris::Exacct::File>
99 There is no explicit C<close()> method for a C<Sun::Solaris::Exacct::File>.
100 The file is closed when the file handle object is undefined or reassigned.
104 This method returns a string containing the creator of the file or C<undef> if
105 the file does not contain the information.
109 This method returns a string containing the hostname on which the file was
110 created, or C<undef> if the file does not contain the information.
114 This method reads the header information of the next record in the file. In a
115 scalar context the value of the type field is returned as a dual-typed scalar
116 that will be one of C<EO_ITEM>, C<EO_GROUP>, or C<EO_NONE>. In a list context
117 it returns a two-element list containing the values of the type and catalog
118 fields. The type element is a dual-typed scalar. The catalog element is
119 blessed into the C<Sun::Solaris::Exacct::Catalog> class. If an error occurs,
120 C<undef> or C<(undef, undef)> is returned depending upon context. The status
121 can be accessed with the C<Sun::Solaris::Exacct::ea_error()> function. (See
122 C<Sun::Solaris::Exacct(3)>).
126 This method reads the header information of the previous record in the file.
127 In a scalar context it returns the type field. In a list context it returns
128 the two element list containing the values of the type and catalog fields, in
129 the same manner as the C<next()> method. Error are also returned in the same
130 manner as the C<next()> method.
134 This method reads in the libexacct record at the current position in the file
135 and returns a C<Sun::Solaris::Exacct::Object> containing the unpacked data
136 from the file. This object can then be further manipulated using its methods.
137 In case of error C<undef> is returned and the error status is made available
138 with the C<Sun::Solaris::Exacct::ea_error()> function. After this operation,
139 the position in the file is set to the start of the next record in the file.
143 This method converts the passed list of C<Sun::Solaris::Exacct::Object>s into
144 libexacct file format and appends them to the libexacct file, which must be
145 open for writing. This method returns C<true> if successful and C<false>
146 otherwise. On failure the error can be examined with the
147 C<Sun::Solaris::Exacct::ea_error()> function.
151 By default nothing is exported from this module. The following tags can be
152 used to selectively import constants defined in this module:
154 :CONSTANTS EO_HEAD, EO_TAIL, EO_NO_VALID_HDR, EO_POSN_MSK, and
157 :ALL :CONSTANTS, Fcntl(:DEFAULT).
161 See C<attributes(5)> for descriptions of the following attributes:
163 ___________________________________________________________
164 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
165 |_____________________________|_____________________________|
166 | Availability | SUNWpl5u |
167 |_____________________________|_____________________________|
168 | Interface Stability | CPAN (http://www.cpan.org) |
169 |_____________________________|_____________________________|
173 C<ea_close(3EXACCT)>, C<ea_get_creator(3EXACCT)>, C<ea_get_hostname(3EXACCT)>,
174 C<ea_get_object(3EXACCT)>, C<ea_next_object(3EXACCT)>, C<ea_open(3EXACCT)>,
175 C<ea_previous_object(3EXACCT)>, C<ea_write_object(3EXACCT)>,
176 C<Sun::Solaris::Exacct(3)>, C<Sun::Solaris::Exacct::Catalog(3)>,
177 C<Sun::Solaris::Exacct::Object(3)>, C<Sun::Solaris::Exacct::Object::Group(3)>,
178 C<Sun::Solaris::Exacct::Object::Item(3)>, C<libexacct(3LIB)>, C<attributes(5)>