#

# 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::Catalog documentation.

#

=head1 NAME

Sun::Solaris::Exacct::Catalog - exacct catalog tag manipulation

=head1 SYNOPSIS

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

my $ea_cat = Sun::Solaris::Exacct::Catalog->new(

&EXT_UINT64 | &EXC_DEFAULT | &EXD_PROC_PID);

This class provides a wrapper around the 32-bit integer used as a catalog tag.

The catalog tag is represented as a Perl object blessed into the

C<Sun::Solaris::Exacct::Catalog> class so that methods can be used to manipulate

fields in a catalog tag.

=head2 Constants

All the C<EXT_*>, C<EXC_*>, and C<EXD_*> macros are provided as constants.

Constants passed to the methods below can either be the integer value such as

C<EXT_UINT8> or the string representation such as C<"EXT_UINT8">.

=head2 Functions

None.

=head2 Class methods

B<C<register($cat_pfx, $catalog_id, $export, @idlist)>>

This method is used to register application-defined C<libexacct(3LIB)>

catalogs with the exacct Perl library. See

F</usr/include/sys/exacct_catalog.h> for details of the catalog tag format.

This method allows symbolic names and strings to be used for manipulating

application-defined catalogs. The first two parameters define the catalog

prefix and associated numeric catalog ID. If the C<$export> parameter is true,

the constants are exported into the caller's package. The final parameter is a

list of C<(id, name)> pairs that identify the required constants. The

constants created by this method are formed by appending C<$cat_pfx> and

C<"_"> to each name in the list, replacing any spaces with underscore

characters and converting the resulting string to uppercase characters. The

C<$catalog_name> value is also created as a constant by prefixing it with

C<EXC_> and converting it to uppercase characters. Its value becomes that of

C<$catalog_id> shifted left by 24 bits. For example, the following call:

Sun::Solaris::Exacct::Catalog->ea_register("MYCAT", 0x01, 1,

FIRST => 0x00000001, SECOND => 0x00000010);

results in the definition of the following constants:

EXC_MYCAT 0x01 << 24

MYCAT_FIRST 0x00000001

MYCAT_SECOND 0x00000010

Only the catalog ID value of 0x01 is available for application use

C<(EXC_LOCAL)>. All other values are reserved. While it is possible to use

values other than 0x01, they might conflict with future extensions to the

libexacct file format.

If any errors are detected during this method, a string is returned containing

the appropriate error message. If the call is sucessful, C<undef> is returned.

B<C<new($integer)>>

B<C<new($cat_obj)>>

B<C<new($type, $catalog, $id)>>

This method creates and returns a new Catalog object, which is a wrapper

around a 32-bit integer catalog tag. Three possible argument lists can be

given. The first variant is to pass an integer formed by bitwise-inclusive OR

of the appropriate C<EX[TCD]_*> constants. The second variant is to pass an

existing Catalog object that will be copied. The final variant is to pass in

the type, catalog and ID fields as separate values. Each of these values can

be either an appropriate integer constant or the string representation of the

constant.

=head2 Object methods

B<C<value()>>

This method allows the value of the catalog tag to be queried. In a scalar

context it returns the 32-bit integer representing the tag. In a list context

it returns a C<(type, catalog, id)> triplet, where each member of the triplet

is a dual-typed scalar.

B<C<type()>>

This method returns the type field of the catalog tag as a dual-typed scalar.

B<C<catalog()>>

This method returns the catalog field of the catalog tag as a dual-typed

scalar.

B<C<id()>>

This method returns the id field of the catalog tag as a dual-typed scalar.

B<C<type_str()>>

B<C<catalog_str()>>

B<C<id_str()>>

These methods return string representations of the appropriate value. These

methods can be used for textual output of the various catalog fields. The

string representations of the constants are formed by removing the C<EXT_>,

C<EXC_>, or C<EXD_> prefix, replacing any underscore characters with spaces,

and converting the remaining string to lowercase characters.

=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 EXT_*, EXC_*, and EXD_*

:ALL :CONSTANTS

=head2 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<Sun::Solaris::Exacct(3)>, C<Sun::Solaris::Exacct::File(3)>,

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

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