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.