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
11 Sun::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
18 This module provides access to the C<ea_error(3EXACCT)> function and for all the
19 extended accounting system calls. Constants from the various C<libexacct(3LIB)>
20 header files are also provided.
21
22 =head2 Constants
23
24 The C<P_PID>, C<P_TASKID>, C<P_PROJID> and all the C<EW_*>, C<EP_*>, C<EXR_*>
25 macros are provided as Perl constants.
26
27 =head2 Functions
28
29 B<C<getacct($idtype, $id)>>
30
31 The C<$idtype> parameter must be either C<P_TASKID> or C<P_PID> and C<$id>
32 must be a corresponding task or process ID. This function returns an object of
33 type C<Sun::Solaris::Exacct::Object>, representing the unpacked accounting
34 buffer returned by the underlying C<getacct(2)> system call. In the event of
35 error, C<undef> is returned.
36
37 B<C<putacct($idtype, $id, $record)>>
38
39 The C<$idtype> parameter must be either C<P_TASKID> or C<P_PID> and C<$id>
40 must be a corresponding task or process ID. If C<$record> is of type
41 C<Sun::Solaris::Exacct::Object>, it is converted to the corresponding packed
42 libexacct object and passed to the C<putacct(2)> system call. If C<$record> is
43 not of type C<Sun::Solaris::Exacct::Object> it is converted to a string using
44 the normal Perl conversion rules and stored as a raw buffer. For predictable
45 and endian-independent results, any raw buffers should be constructed using
46 the Perl C<pack()> function. This function returns C<true> on success and
47 C<false> on failure.
48
49 B<C<wracct($idtype, $id, $flags)>>
50
51 The C<$idtype> parameter must be either C<P_TASKID> or C<P_PID> and $id must
52 be a corresponding task or process ID. The C<$flags> parameter must be either
53 C<EW_INTERVAL> or C<EW_PARTIAL>. The parameters are passed directly to the
54 underlying C<wracct(2)> system call. This function returns C<true> on success
55 and C<false> on failure.
56
57 B<C<ea_error()>>
58
59 This function provides access to the C<ea_error(3EXACCT)> function. It returns
60 a double-typed scalar that in a numeric context will be one of the C<EXR_*>
61 constants. In a string context it will be a descriptive error message. This is
62 the exacct equivalent to the C<$!> (C<errno>) Perl variable.
63
64 B<C<ea_error_str()>>
65
66 This function returns a double-typed scalar that in a numeric context will be
67 one of the C<EXR_*> constants as returned by C<ea_error>. In a string context
68 it describes the value returned by C<ea_error>. If C<ea_error> returns
69 C<EXR_SYSCALL_FAIL>, the string value returned is the value returned by
70 C<strerror(3C)>. This function is provided as a convenience so that repeated
71 blocks 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
79 B<C<ea_register_catalog($cat_pfx, $catalog_id, $export, @idlist)>>
80
81 This convenience function is a wrapper around the
82 C<< Sun::Solaris::Exacct::Catalog->register() >> method.
83
84 B<C<ea_new_catalog($integer)>>
85
86 B<C<ea_new_catalog($cat_obj)>>
87
88 B<C<ea_new_catalog($type, $catalog, $id)>>
89
90 These convenience functions are wrappers around the
91 C<< Sun::Solaris::Exacct::Catalog->new() >> method. See
92 C<Sun::Solaris::Exacct::Catalog(3)>.
93
94 B<C<< ea_new_file($name, $oflags, creator => $creator,
95 aflags => $aflags, mode => $mode) >>>
96
97 This convenience function is a wrapper around the
98 C<< Sun::Solaris::Exacct::File->new() >> method. See
99 C<Sun::Solaris::Exacct::File(3)>.
100
101 B<C<ea_new_item($catalog, $value)>>
102
103 This convenience function is a wrapper around the
104 C<< Sun::Solaris::Exacct::Object::Item->new() >> method. See
105 C<Sun::Solaris::Exacct::Object::Item(3)>.
106
107 B<C<ea_new_group($catalog, @objects)>>
108
109 This convenience function is a wrapper around the
110 C<< Sun::Solaris::Exacct::Object::Group->new() >> method. See
111 C<Exacct::Object::Group(3)>.
112
113 B<C<ea_dump_object($object, $filehandle)>>
114
115 This convenience function is a wrapper around the
116 C<< Sun::Solaris::Exacct::Object->dump() >> method. See
117 C<Sun::Solaris::Exacct::Object(3)>.
118
119 =head2 Class methods
120
121 None.
122
123 =head2 Object methods
124
125 None.
126
127 =head2 Exports
128
129 By default nothing is exported from this module. The following tags can be
130 used 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
152 See 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
165 C<getacct(2)>, C<putacct(2)>, C<wracct(2)>, C<ea_error(3EXACCT)>,
166 C<Sun::Solaris::Exacct::Catalog(3)>, C<Sun::Solaris::Exacct::File(3)>,
167 C<Sun::Solaris::Exacct::Object(3)>, C<Sun::Solaris::Exacct::Object::Group(3)>,
168 C<Sun::Solaris::Exacct::Object::Item(3)>, C<libexacct(3LIB)>, C<attributes(5)>
169
170 =head1 NOTES
171
172 The modules described in the C<Sun::Solaris::Exacct> manual pages make
173 extensive use of the Perl "double-typed scalar" facility. This facility allows
174 a scalar value to behave either as an integer or as a string, depending upon
175 context. 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
177 value to the corresponding string to display a value. Some examples are
178 provided 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
192 Wherever a function or method is documented as returning a double-typed
193 scalar, the returned value exhibits this type of behavior.