#

# Copyright 2005 Sun Microsystems, Inc. All rights reserved.

# Use is subject to license terms.

#

# CDDL HEADER START

#

# The contents of this file are subject to the terms of the

# Common Development and Distribution License, Version 1.0 only

# (the "License"). You may not use this file except in compliance

# with the License.

#

# 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.

#

# 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]

#

# CDDL HEADER END

#

#ident "%Z%%M% %I% %E% SMI"

#

# Sun::Solaris::Exacct::Object documentation.

#

=head1 NAME

Sun::Solaris::Exacct::Object - exacct object manipulation

=head1 SYNOPSIS

use Sun::Solaris::Exacct::Object qw(:ALL);

print($ea_obj->value(), "\n");

This module is used as a parent of the two possible types of Perl exacct

objects: Items and Groups. An Item is either a single data value such as the

number of seconds of user CPU time consumed by a process, an embedded Perl

exacct object, or a block of raw data. A Group is an ordered collection of

Perl exacct Items such as all of the resource usage values for a particular

process or task. If Groups need to be nested within each other, the inner

Groups can be stored as embedded Perl exacct objects inside the enclosing

Group.

This module contains methods that are common to both Perl exacct Items and

Groups. The attributes of C<Sun::Solaris::Exacct::Object> and all classes

derived from it are read-only after initial creation with new(). This behavior

prevents the inadvertent modification of the attributes that could produce

inconsistent catalog tags and data values. The only exception is the array

used to store the Items inside a Group object, which can be modified using the

normal Perl array operators. See the C<value()> method below.

=head2 Constants

C<EO_ERROR>, C<EO_NONE>, C<EO_ITEM>, and C<EO_GROUP>.

=head2 Functions

None.

=head2 Class methods

B<C<dump($object, $filehandle)>>

This method dumps formatted text representation of a Perl exacct object to the

supplied file handle. If no file handle is specified, the text representation

is dumped to C<STDOUT>. See EXAMPLES below for sample output.

=head2 Object methods

B<C<type()>>

This method returns the type field of the Perl exacct object. The value of the

type field is returned as a dual-typed scalar and is either C<EO_ITEM>,

C<EO_GROUP>, or C<EO_NONE>.

B<C<catalog()>>

This method returns the catalog field of the Perl exacct object. The value is

returned as a C<Sun::Solaris::Exacct::Catalog> object.

B<C<match_catalog($catalog)>>

This method matches the passed catalog tag against the object. C<true> is

returned of a match occurs. Otherwise C<false> is returned. This method has

the same behavior as the underlying C<ea_match_object_catalog(3EXACCT)>

function.

B<C<value()>>

This method returns the value of the Perl exacct object. In the case of an

Item, this object will normally be a Perl scalar, either a number or string.

For raw Items, the buffer contained inside the object is returned as a Perl

string that can be manipulated with the Perl C<unpack()> function. If the Item

contains either a nested Item or a nested Group, the enclosed Item is returned

as a reference to an object of the appropriate subtype of the

C<Sun::Solaris::Exacct::Object> class.

For Group objects, if C<value()> is called in a scalar context, the return

value is a reference to the underlying array used to store the component Items

of the Group. Since this array can be manipulated with the normal Perl array

indexing syntax and array operators, the objects inside the Group can be

manipulated. All objects in the array must be derived from the

C<Sun::Solaris::Exacct::Object> class. Any attempt to insert something else

into the array will generate a fatal runtime error that can be caught with an

C<eval { }> block.

If C<value()> is called in a list context for a Group object, it returns a

list of all the objects in the Group. Unlike the array reference returned in a

scalar context, this list cannot be manipulated to add or delete Items from a

Group. This mechanism is considerably faster than the array mechanism

described above and is the preferred mechanism if a Group is being examined in

a read-only manner.

=head2 Exports

By default nothing is exported from this module. The following tags can be

used to selectively import constants and functions defined in this module:

:CONSTANTS EO_ERROR, EO_NONE, EO_ITEM, and EO_GROUP

:ALL :CONSTANTS

=head1 EXAMPLES

The following is an example of output of the C<dump()> method for a Perl exacct

Group object.

GROUP

Catalog = EXT_GROUP|EXC_DEFAULT|EXD_GROUP_PROC_PARTIAL

ITEM

Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_PID

Value = 3

ITEM

Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_UID

Value = 0

ITEM

Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_GID

Value = 0

ITEM

Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_PROJID

Value = 0

ITEM

Catalog = EXT_UINT32|EXC_DEFAULT|EXD_PROC_TASKID

Value = 0

ITEM

Catalog = EXT_STRING|EXC_DEFAULT|EXD_PROC_COMMAND

Value = fsflush

ENDGROUP

=head1 ATTRIBUTES

See C<attributes(5)> for descriptions of the following attributes:

___________________________________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

|_____________________________|_____________________________|

| Availability | CPAN (http://www.cpan.org) |

|_____________________________|_____________________________|

| Interface Stability | Evolving |

|_____________________________|_____________________________|

=head1 SEE ALSO

C<ea_match_object_catalog(3EXACCT)>, C<Sun::Solaris::Exacct(3)>,

C<Sun::Solaris::Exacct::Catalog(3)>, C<Sun::Solaris::Exacct::File(3)>,

C<Sun::Solaris::Exacct::Object::Group(3)>,

C<Sun::Solaris::Exacct::Object::Item(3)>, C<libexacct(3LIB)>, C<attributes(5)>