1#
2# Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved.
3#
4
5#
6# Sun::Solaris::Exacct documentation.
7# 
8
9=head1 NAME
10
11Sun::Solaris::Exacct - exacct system calls and error handling
12
13=head1 SYNOPSIS
14
15 use Sun::Solaris::Exacct qw(:EXACCT_ALL);
16 my $ea_rec = getacct(P_PID, $$);
17
18This module provides access to the C<ea_error(3EXACCT)> function and for all the
19extended accounting system calls. Constants from the various C<libexacct(3LIB)>
20header files are also provided.
21
22=head2 Constants
23
24The C<P_PID>, C<P_TASKID>, C<P_PROJID> and all the C<EW_*>, C<EP_*>, C<EXR_*>
25macros are provided as Perl constants.
26
27=head2 Functions
28
29B<C<getacct($idtype, $id)>>
30
31The C<$idtype> parameter must be either C<P_TASKID> or C<P_PID> and C<$id>
32must be a corresponding task or process ID. This function returns an object of
33type C<Sun::Solaris::Exacct::Object>, representing the unpacked accounting
34buffer returned by the underlying C<getacct(2)> system call. In the event of
35error, C<undef> is returned.
36
37B<C<putacct($idtype, $id, $record)>>
38
39The C<$idtype> parameter must be either C<P_TASKID> or C<P_PID> and C<$id>
40must be a corresponding task or process ID. If C<$record> is of type
41C<Sun::Solaris::Exacct::Object>, it is converted to the corresponding packed
42libexacct object and passed to the C<putacct(2)> system call. If C<$record> is
43not of type C<Sun::Solaris::Exacct::Object> it is converted to a string using
44the normal Perl conversion rules and stored as a raw buffer. For predictable
45and endian-independent results, any raw buffers should be constructed using
46the Perl C<pack()> function. This function returns C<true> on success and
47C<false> on failure.
48
49B<C<wracct($idtype, $id, $flags)>>
50
51The C<$idtype> parameter must be either C<P_TASKID> or C<P_PID> and $id must
52be a corresponding task or process ID. The C<$flags> parameter must be either
53C<EW_INTERVAL> or C<EW_PARTIAL>. The parameters are passed directly to the
54underlying C<wracct(2)> system call. This function returns C<true> on success
55and C<false> on failure.
56
57B<C<ea_error()>>
58
59This function provides access to the C<ea_error(3EXACCT)> function. It returns
60a double-typed scalar that in a numeric context will be one of the C<EXR_*>
61constants. In a string context it will be a descriptive error message. This is
62the exacct equivalent to the C<$!> (C<errno>) Perl variable.
63
64B<C<ea_error_str()>>
65
66This function returns a double-typed scalar that in a numeric context will be
67one of the C<EXR_*> constants as returned by C<ea_error>. In a string context
68it describes the value returned by C<ea_error>. If C<ea_error> returns
69C<EXR_SYSCALL_FAIL>, the string value returned is the value returned by
70C<strerror(3C)>. This function is provided as a convenience so that repeated
71blocks of code like the following can be avoided:
72
73 if (ea_error() == EXR_SYSCALL_FAIL) {
74         print("error: $!\n");
75 } else {
76         print("error: ", ea_error(), "\n");
77 }
78
79B<C<ea_register_catalog($cat_pfx, $catalog_id, $export, @idlist)>>
80
81This convenience function is a wrapper around the
82C<< Sun::Solaris::Exacct::Catalog->register() >> method.
83
84B<C<ea_new_catalog($integer)>>
85
86B<C<ea_new_catalog($cat_obj)>>
87
88B<C<ea_new_catalog($type, $catalog, $id)>>
89
90These convenience functions are wrappers around the
91C<< Sun::Solaris::Exacct::Catalog->new() >> method. See
92C<Sun::Solaris::Exacct::Catalog(3)>.
93
94B<C<< ea_new_file($name, $oflags, creator => $creator,
95    aflags => $aflags, mode => $mode) >>>
96
97This convenience function is a wrapper around the
98C<< Sun::Solaris::Exacct::File->new() >> method. See
99C<Sun::Solaris::Exacct::File(3)>.
100
101B<C<ea_new_item($catalog, $value)>>
102
103This convenience function is a wrapper around the
104C<< Sun::Solaris::Exacct::Object::Item->new() >> method. See
105C<Sun::Solaris::Exacct::Object::Item(3)>.
106
107B<C<ea_new_group($catalog, @objects)>>
108
109This convenience function is a wrapper around the
110C<< Sun::Solaris::Exacct::Object::Group->new() >> method. See
111C<Exacct::Object::Group(3)>.
112
113B<C<ea_dump_object($object, $filehandle)>>
114
115This convenience function is a wrapper around the
116C<< Sun::Solaris::Exacct::Object->dump() >> method.  See
117C<Sun::Solaris::Exacct::Object(3)>.
118
119=head2 Class methods
120
121None.
122
123=head2 Object methods
124
125None.
126
127=head2 Exports
128
129By default nothing is exported from this module. The following tags can be
130used to selectively import constants and functions defined in this module:
131
132 :SYSCALLS           getacct(), putacct(), and wracct()
133
134 :LIBCALLS           ea_error() and ea_error_str()
135
136 :CONSTANTS          P_PID, P_TASKID, P_PROJID, EW_*, EP_*, and EXR_*
137
138 :SHORTHAND          ea_register_catalog(), ea_new_catalog(), ea_new_file(),
139                     ea_new_item(), and ea_new_group()
140
141 :ALL                :SYSCALLS, :LIBCALLS, :CONSTANTS, and :SHORTHAND
142
143 :EXACCT_CONSTANTS   :CONSTANTS, plus the :CONSTANTS tags for
144                     Sun::Solaris::Catalog, Sun::Solaris::File,
145                     and Sun::Solaris::Object
146
147 :EXACCT_ALL         :ALL, plus the :ALL tags for Sun::Solaris::Catalog,
148                     Sun::Solaris::File, and Sun::Solaris::Object
149
150=head1 ATTRIBUTES
151
152See C<attributes(5)> for descriptions of the following attributes:
153
154  ___________________________________________________________
155 |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
156 |_____________________________|_____________________________|
157 | Availability                | CPAN (http://www.cpan.org)  |
158 |_____________________________|_____________________________|
159 | Interface Stability         | Evolving                    |
160 |_____________________________|_____________________________|
161
162
163=head1 SEE ALSO
164
165C<getacct(2)>, C<putacct(2)>, C<wracct(2)>, C<ea_error(3EXACCT)>,
166C<Sun::Solaris::Exacct::Catalog(3)>, C<Sun::Solaris::Exacct::File(3)>,
167C<Sun::Solaris::Exacct::Object(3)>, C<Sun::Solaris::Exacct::Object::Group(3)>,
168C<Sun::Solaris::Exacct::Object::Item(3)>, C<libexacct(3LIB)>, C<attributes(5)>
169
170=head1 NOTES
171
172The modules described in the C<Sun::Solaris::Exacct> manual pages make
173extensive use of the Perl "double-typed scalar" facility. This facility allows
174a scalar value to behave either as an integer or as a string, depending upon
175context. It is the same behavior as exhibited by the C<$!> Perl variable
176(C<errno>). It is useful because it avoids the need to map from an integer
177value to the corresponding string to display a value. Some examples are
178provided below:
179
180 # Assume $obj is a Sun::Solaris::Exacct::Item
181 my $type = $obj->type();
182
183 # Print "2 EO_ITEM"
184 printf("%d %s\n", $type, $type);
185
186 # Behave as an integer, $i == 2
187 my $i = 0 + $type;
188
189 # Behave as a string, $s = "abc EO_ITEM xyx"
190 my $s = "abc $type xyz";
191
192Wherever a function or method is documented as returning a double-typed
193scalar, the returned value exhibits this type of behavior.
194