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
11 Sun::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
18 This module is used as a parent of the two possible types of Perl exacct
19 objects: Items and Groups. An Item is either a single data value such as the
20 number of seconds of user CPU time consumed by a process, an embedded Perl
21 exacct object, or a block of raw data. A Group is an ordered collection of
22 Perl exacct Items such as all of the resource usage values for a particular
23 process or task. If Groups need to be nested within each other, the inner
24 Groups can be stored as embedded Perl exacct objects inside the enclosing
25 Group.
26
27 This module contains methods that are common to both Perl exacct Items and
28 Groups. The attributes of C<Sun::Solaris::Exacct::Object> and all classes
29 derived from it are read-only after initial creation with new(). This behavior
30 prevents the inadvertent modification of the attributes that could produce
31 inconsistent catalog tags and data values. The only exception is the array
32 used to store the Items inside a Group object, which can be modified using the
33 normal Perl array operators. See the C<value()> method below.
34
35 =head2 Constants
36
37 C<EO_ERROR>, C<EO_NONE>, C<EO_ITEM>, and C<EO_GROUP>.
38
39 =head2 Functions
40
41 None.
42
43 =head2 Class methods
44
45 B<C<dump($object, $filehandle)>>
46
47 This method dumps formatted text representation of a Perl exacct object to the
48 supplied file handle. If no file handle is specified, the text representation
49 is dumped to C<STDOUT>. See EXAMPLES below for sample output.
50
51 =head2 Object methods
52
53 B<C<type()>>
54
55 This method returns the type field of the Perl exacct object. The value of the
56 type field is returned as a dual-typed scalar and is either C<EO_ITEM>,
57 C<EO_GROUP>, or C<EO_NONE>.
58
59 B<C<catalog()>>
60
61 This method returns the catalog field of the Perl exacct object. The value is
62 returned as a C<Sun::Solaris::Exacct::Catalog> object.
63
64 B<C<match_catalog($catalog)>>
65
66 This method matches the passed catalog tag against the object. C<true> is
67 returned of a match occurs. Otherwise C<false> is returned. This method has
68 the same behavior as the underlying C<ea_match_object_catalog(3EXACCT)>
69 function.
70
71 B<C<value()>>
72
73 This method returns the value of the Perl exacct object. In the case of an
74 Item, this object will normally be a Perl scalar, either a number or string.
75 For raw Items, the buffer contained inside the object is returned as a Perl
76 string that can be manipulated with the Perl C<unpack()> function. If the Item
77 contains either a nested Item or a nested Group, the enclosed Item is returned
78 as a reference to an object of the appropriate subtype of the
79 C<Sun::Solaris::Exacct::Object> class.
80
81 For Group objects, if C<value()> is called in a scalar context, the return
82 value is a reference to the underlying array used to store the component Items
83 of the Group. Since this array can be manipulated with the normal Perl array
84 indexing syntax and array operators, the objects inside the Group can be
85 manipulated. All objects in the array must be derived from the
86 C<Sun::Solaris::Exacct::Object> class. Any attempt to insert something else
87 into the array will generate a fatal runtime error that can be caught with an
88 C<eval { }> block.
89
90 If C<value()> is called in a list context for a Group object, it returns a
91 list of all the objects in the Group. Unlike the array reference returned in a
92 scalar context, this list cannot be manipulated to add or delete Items from a
93 Group. This mechanism is considerably faster than the array mechanism
94 described above and is the preferred mechanism if a Group is being examined in
95 a read-only manner.
96
97 =head2 Exports
98
99 By default nothing is exported from this module. The following tags can be
100 used 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
108 The following is an example of output of the C<dump()> method for a Perl exacct
109 Group 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
135 See 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
147 C<ea_match_object_catalog(3EXACCT)>, C<Sun::Solaris::Exacct(3)>,
148 C<Sun::Solaris::Exacct::Catalog(3)>, C<Sun::Solaris::Exacct::File(3)>,
149 C<Sun::Solaris::Exacct::Object::Group(3)>,
150 C<Sun::Solaris::Exacct::Object::Item(3)>, C<libexacct(3LIB)>, C<attributes(5)>