1# 2# Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved. 3# 4 5# 6# Sun::Solaris::Exacct::Object documentation. 7# 8 9=head1 NAME 10 11Sun::Solaris::Exacct::Object - exacct object manipulation 12 13=head1 SYNOPSIS 14 15 use Sun::Solaris::Exacct::Object qw(:ALL); 16 print($ea_obj->value(), "\n"); 17 18This module is used as a parent of the two possible types of Perl exacct 19objects: Items and Groups. An Item is either a single data value such as the 20number of seconds of user CPU time consumed by a process, an embedded Perl 21exacct object, or a block of raw data. A Group is an ordered collection of 22Perl exacct Items such as all of the resource usage values for a particular 23process or task. If Groups need to be nested within each other, the inner 24Groups can be stored as embedded Perl exacct objects inside the enclosing 25Group. 26 27This module contains methods that are common to both Perl exacct Items and 28Groups. The attributes of C<Sun::Solaris::Exacct::Object> and all classes 29derived from it are read-only after initial creation with new(). This behavior 30prevents the inadvertent modification of the attributes that could produce 31inconsistent catalog tags and data values. The only exception is the array 32used to store the Items inside a Group object, which can be modified using the 33normal Perl array operators. See the C<value()> method below. 34 35=head2 Constants 36 37C<EO_ERROR>, C<EO_NONE>, C<EO_ITEM>, and C<EO_GROUP>. 38 39=head2 Functions 40 41None. 42 43=head2 Class methods 44 45B<C<dump($object, $filehandle)>> 46 47This method dumps formatted text representation of a Perl exacct object to the 48supplied file handle. If no file handle is specified, the text representation 49is dumped to C<STDOUT>. See EXAMPLES below for sample output. 50 51=head2 Object methods 52 53B<C<type()>> 54 55This method returns the type field of the Perl exacct object. The value of the 56type field is returned as a dual-typed scalar and is either C<EO_ITEM>, 57C<EO_GROUP>, or C<EO_NONE>. 58 59B<C<catalog()>> 60 61This method returns the catalog field of the Perl exacct object. The value is 62returned as a C<Sun::Solaris::Exacct::Catalog> object. 63 64B<C<match_catalog($catalog)>> 65 66This method matches the passed catalog tag against the object. C<true> is 67returned of a match occurs. Otherwise C<false> is returned. This method has 68the same behavior as the underlying C<ea_match_object_catalog(3EXACCT)> 69function. 70 71B<C<value()>> 72 73This method returns the value of the Perl exacct object. In the case of an 74Item, this object will normally be a Perl scalar, either a number or string. 75For raw Items, the buffer contained inside the object is returned as a Perl 76string that can be manipulated with the Perl C<unpack()> function. If the Item 77contains either a nested Item or a nested Group, the enclosed Item is returned 78as a reference to an object of the appropriate subtype of the 79C<Sun::Solaris::Exacct::Object> class. 80 81For Group objects, if C<value()> is called in a scalar context, the return 82value is a reference to the underlying array used to store the component Items 83of the Group. Since this array can be manipulated with the normal Perl array 84indexing syntax and array operators, the objects inside the Group can be 85manipulated. All objects in the array must be derived from the 86C<Sun::Solaris::Exacct::Object> class. Any attempt to insert something else 87into the array will generate a fatal runtime error that can be caught with an 88C<eval { }> block. 89 90If C<value()> is called in a list context for a Group object, it returns a 91list of all the objects in the Group. Unlike the array reference returned in a 92scalar context, this list cannot be manipulated to add or delete Items from a 93Group. This mechanism is considerably faster than the array mechanism 94described above and is the preferred mechanism if a Group is being examined in 95a read-only manner. 96 97=head2 Exports 98 99By default nothing is exported from this module. The following tags can be 100used to selectively import constants and functions defined in this module: 101 102 :CONSTANTS EO_ERROR, EO_NONE, EO_ITEM, and EO_GROUP 103 104 :ALL :CONSTANTS 105 106=head1 EXAMPLES 107 108The following is an example of output of the C<dump()> method for a Perl exacct 109Group object. 110 111 GROUP 112 Catalog = EXT_GROUP|EXC_DEFAULT|EXD_GROUP_PROC_PARTIAL 113 ITEM 114 Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_PID 115 Value = 3 116 ITEM 117 Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_UID 118 Value = 0 119 ITEM 120 Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_GID 121 Value = 0 122 ITEM 123 Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_PROJID 124 Value = 0 125 ITEM 126 Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_TASKID 127 Value = 0 128 ITEM 129 Catalog = EXT_STRING|EXC_DEFAULT|EXD_PROC_COMMAND 130 Value = fsflush 131 ENDGROUP 132 133=head1 ATTRIBUTES 134 135See C<attributes(5)> for descriptions of the following attributes: 136 137 ___________________________________________________________ 138 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 139 |_____________________________|_____________________________| 140 | Availability | CPAN (http://www.cpan.org) | 141 |_____________________________|_____________________________| 142 | Interface Stability | Evolving | 143 |_____________________________|_____________________________| 144 145=head1 SEE ALSO 146 147C<ea_match_object_catalog(3EXACCT)>, C<Sun::Solaris::Exacct(3)>, 148C<Sun::Solaris::Exacct::Catalog(3)>, C<Sun::Solaris::Exacct::File(3)>, 149C<Sun::Solaris::Exacct::Object::Group(3)>, 150C<Sun::Solaris::Exacct::Object::Item(3)>, C<libexacct(3LIB)>, C<attributes(5)> 151