usr/src/man/man3perl/Exacct::Object.3perl

   1 '\" te
   2 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH EXACCT::OBJECT 3PERL "Dec 1, 2002"
   7 .SH NAME
   8 Exacct::Object \- exacct object manipulation
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 use Sun::Solaris::Exacct::Object qw(:ALL);
  13 print($ea_obj->value(), "\en");
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 This module is used as a parent of the two possible types of Perl exacct
  20 objects: Items and Groups. An Item is either a single data value such as the
  21 number of seconds of user CPU time consumed by a process, an embedded Perl
  22 exacct object, or a block of raw data.  A Group is an ordered collection of
  23 Perl exacct Items such as all of the resource usage values for a particular
  24 process or task. If Groups need to be nested within each other, the inner
  25 Groups can be stored as embedded Perl exacct objects inside the enclosing
  26 Group.
  27 .sp
  28 .LP
  29 This module contains methods that are common to both Perl exacct Items and
  30 Groups. The attributes of \fBSun::Solaris::Exacct::Object\fR and all classes
  31 derived from it are read-only after initial creation with \fBnew()\fR. This
  32 behavior prevents the inadvertent modification of the attributes that could
  33 produce inconsistent catalog tags and data values. The only exception is the
  34 array used to store the Items inside a Group object, which can be modified
  35 using the normal Perl array operators. See the \fBvalue()\fR method below.
  36 .SS "Constants"
  37 .sp
  38 .LP
  39 \fBEO_ERROR\fR, \fBEO_NONE\fR, \fBEO_ITEM\fR, and \fBEO_GROUP\fR.
  40 .SS "Functions"
  41 .sp
  42 .LP
  43 None.
  44 .SS "Class methods"
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fBdump($object, $filehandle)\fR\fR
  49 .ad
  50 .RS 30n
  51 This method dumps formatted text representation of a Perl exacct object to the
  52 supplied file handle. If no file handle is specified, the text representation
  53 is dumped to \fBSTDOUT\fR. See EXAMPLES below for sample output.
  54 .RE
  55
  56 .SS "Object methods"
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fBtype()\fR\fR
  61 .ad
  62 .RS 27n
  63 This method returns the type field of the Perl exacct object. The value of the
  64 type field is returned as a dual-typed scalar and is either \fBEO_ITEM\fR,
  65 \fBEO_GROUP\fR, or \fBEO_NONE\fR.
  66 .RE
  67
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fBcatalog()\fR\fR
  72 .ad
  73 .RS 27n
  74 This method returns the catalog field of the Perl exacct object. The value is
  75 returned as a \fBSun::Solaris::Exacct::Catalog\fR object.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBmatch_catalog($catalog)\fR\fR
  82 .ad
  83 .RS 27n
  84 This method matches the passed catalog tag against the object. True is returned
  85 of a match occurs.  Otherwise false is returned. This method has the same
  86 behavior as the underlying \fBea_match_object_catalog\fR(3EXACCT) function.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBvalue()\fR\fR
  93 .ad
  94 .RS 27n
  95 This method returns the value of the Perl exacct object. In the case of an
  96 Item, this object will normally be a Perl scalar, either a number or string.
  97 For raw Items, the buffer contained inside the object is returned as a Perl
  98 string that can be manipulated with the Perl \fBunpack()\fR function. If the
  99 Item contains either a nested Item or a nested Group, the enclosed Item is
 100 returned as a reference to an object of the appropriate subtype of the
 101 \fBSun::Solaris::Exacct::Object\fR class.
 102 .sp
 103 For Group objects, if \fBvalue()\fR is called in a scalar context, the return
 104 value is a reference to the underlying array used to store the component Items
 105 of the Group. Since this array can be manipulated with the normal Perl array
 106 indexing syntax and array operators, the objects inside the Group can be
 107 manipulated. All objects in the array must be derived from the
 108 \fBSun::Solaris::Exacct::Object\fR class. Any attempt to insert something else
 109 into the array will generate a fatal runtime error that can be caught with an
 110 \fBeval { }\fR block.
 111 .sp
 112 If \fBvalue()\fR is called in a list context for a Group object, it returns a
 113 list of all the objects in the Group. Unlike the array reference returned in a
 114 scalar context, this list cannot be manipulated to add or delete Items from a
 115 Group. This mechanism is considerably faster than the array mechanism described
 116 above and is the preferred mechanism if a Group is being examined in a
 117 read-only manner.
 118 .RE
 119
 120 .SS "Exports"
 121 .sp
 122 .LP
 123 By default nothing is exported from this module. The following tags can be used
 124 to selectively import constants and functions defined in this module:
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fB:CONSTANTS\fR\fR
 129 .ad
 130 .RS 14n
 131 \fBEO_ERROR\fR, \fBEO_NONE\fR, \fBEO_ITEM\fR, and \fBEO_GROUP\fR
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fB:ALL\fR\fR
 138 .ad
 139 .RS 14n
 140 \fB:CONSTANTS\fR
 141 .RE
 142
 143 .SH EXAMPLES
 144 .LP
 145 \fBExample 1 \fROutput of the \fBdump()\fR method for a Perl exacct Group
 146 object.
 147 .sp
 148 .LP
 149 The following is an example of output of the \fBdump()\fR method for a Perl
 150 exacct Group object.
 151
 152 .sp
 153 .in +2
 154 .nf
 155 GROUP
 156   Catalog = EXT_GROUP|EXC_DEFAULT|EXD_GROUP_PROC_PARTIAL
 157   ITEM
 158     Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_PID
 159     Value = 3
 160   ITEM
 161     Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_UID
 162     Value = 0
 163   ITEM
 164     Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_GID
 165     Value = 0
 166   ITEM
 167     Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_PROJID
 168     Value = 0
 169   ITEM
 170     Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_TASKID
 171     Value = 0
 172   ITEM
 173     Catalog = EXT_STRING|EXC_DEFAULT|EXD_PROC_COMMAND
 174     Value = fsflush
 175 ENDGROUP
 176 .fi
 177 .in -2
 178
 179 .SH ATTRIBUTES
 180 .sp
 181 .LP
 182 See \fBattributes\fR(5) for descriptions of the following attributes:
 183 .sp
 184
 185 .sp
 186 .TS
 187 box;
 188 c | c
 189 l | l .
 190 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 191 _
 192 Interface Stability     Evolving
 193 .TE
 194
 195 .SH SEE ALSO
 196 .sp
 197 .LP
 198 \fBea_match_object_catalog\fR(3EXACCT), \fBExacct\fR(3PERL),
 199 \fBExacct::Catalog\fR(3PERL), \fBExacct::File\fR(3PERL),
 200 \fBExacct::Object::Group\fR(3PERL), \fBExacct::Object::Item\fR(3PERL),
 201 \fBlibexacct\fR(3LIB), \fBattributes\fR(5)