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)