#
# Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved.
#

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