1 '\" te
   2 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" 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.
   5 .\" 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]
   6 .TH EXACCT::CATALOG 3PERL "Dec 1, 2002"
   7 .SH NAME
   8 Exacct::Catalog \- exacct catalog tag manipulation
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 use Sun::Solaris::Exacct::Catalog qw(:ALL);
  13 my $ea_cat = Sun::Solaris::Exacct::Catalog->new(
  14     &EXT_UINT64 | &EXC_DEFAULT | &EXD_PROC_PID);
  15 .fi
  16 
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 This class provides a wrapper around the 32-bit integer used as a catalog tag.
  21 The catalog tag is represented as a Perl object blessed into the
  22 \fBSun::Solaris::Exacct::Catalog\fR class so that methods can be used to
  23 manipulate fields in a catalog tag.
  24 .SS "Constants"
  25 .sp
  26 .LP
  27 All the \fBEXT_\fR*, \fBEXC_\fR*, and \fBEXD_\fR* macros are provided as
  28 constants.  Constants passed to the methods below can either be the integer
  29 value such as \fBEXT_UINT8\fR or the string representation such as
  30 "\fBEXT_UINT8\fR".
  31 .SS "Functions"
  32 .sp
  33 .LP
  34 None.
  35 .SS "Class methods"
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fBregister($cat_pfx, $catalog_id, $export, @idlist)\fR\fR
  40 .ad
  41 .sp .6
  42 .RS 4n
  43 This method is used to register application-defined \fBlibexacct\fR(3LIB)
  44 catalogs with the exacct Perl library. See
  45 <\fB/usr/include/sys/exacct_catalog.h\fR> for details of the catalog tag
  46 format.  This method allows symbolic names and strings to be used for
  47 manipulating application-defined catalogs. The first two parameters define the
  48 catalog prefix and associated numeric catalog ID. If the \fB$export\fR
  49 parameter is true, the constants are exported into the caller's package. The
  50 final parameter is a list of (\fBid\fR, \fBname\fR) pairs that identify the
  51 required constants. The constants created by this method are formed by
  52 appending \fB$cat_pfx\fR and "_" to each name in the list, replacing any spaces
  53 with underscore characters and converting the resulting string to uppercase
  54 characters. The \fB$catalog_name\fR value is also created as a constant by
  55 prefixing it with\fB EXC_\fR and converting it to uppercase characters. Its
  56 value becomes that of \fB$catalog_id\fR shifted left by 24 bits. For example,
  57 the following call:
  58 .sp
  59 .in +2
  60 .nf
  61 Sun::Solaris::Exacct::Catalog->ea_register("MYCAT", 0x01, 1,
  62    FIRST => 0x00000001, SECOND => 0x00000010);
  63 .fi
  64 .in -2
  65 
  66 results in the definition of the following constants:
  67 .sp
  68 .in +2
  69 .nf
  70 EXC_MYCAT    0x01 << 24
  71 MYCAT_FIRST  0x00000001
  72 MYCAT_SECOND 0x00000010
  73 .fi
  74 .in -2
  75 
  76 Only the catalog ID value of 0x01 is available for application use
  77 (\fBEXC_LOCAL\fR). All other values are reserved.  While it is possible to use
  78 values other than 0x01, they might conflict with future extensions to the
  79 \fBlibexacct\fR file format.
  80 .sp
  81 If any errors are detected during this method, a string is returned containing
  82 the appropriate error message. If the call is sucessful, \fBundef\fR is
  83 returned.
  84 .RE
  85 
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBnew($integer)\fR\fR
  90 .ad
  91 .br
  92 .na
  93 \fB\fBnew($cat_obj)\fR\fR
  94 .ad
  95 .br
  96 .na
  97 \fB\fBnew($type, $catalog, $id)\fR\fR
  98 .ad
  99 .sp .6
 100 .RS 4n
 101 This method creates and returns a new Catalog object, which is a wrapper around
 102 a 32-bit integer catalog tag. Three possible argument lists can be given. The
 103 first variant is to pass an integer formed by bitwise-inclusive OR of the
 104 appropriate \fBEX[TCD]_\fR* constants. The second variant is to pass an
 105 existing Catalog object that will be copied. The final variant is to pass in
 106 the type, catalog and ID fields as separate values. Each of these values can be
 107 either an appropriate integer constant or the string representation of the
 108 constant.
 109 .RE
 110 
 111 .SS "Object methods"
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBvalue()\fR\fR
 116 .ad
 117 .RS 17n
 118 This method allows the value of the catalog tag to be queried. In a scalar
 119 context it returns the 32-bit integer representing the tag. In a list context
 120 it returns a (\fBtype\fR, \fBcatalog\fR, \fBid\fR) triplet, where each member
 121 of the triplet is a dual-typed scalar.
 122 .RE
 123 
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBtype()\fR\fR
 128 .ad
 129 .RS 17n
 130 This method returns the type field of the catalog tag as a dual-typed scalar.
 131 .RE
 132 
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBcatalog()\fR\fR
 137 .ad
 138 .RS 17n
 139 This method returns the catalog field of the catalog tag as a dual-typed
 140 scalar.
 141 .RE
 142 
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBid()\fR\fR
 147 .ad
 148 .RS 17n
 149 This method returns the id field of the catalog tag as a dual-typed scalar.
 150 .RE
 151 
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fBtype_str()\fR\fR
 156 .ad
 157 .br
 158 .na
 159 \fB\fBcatalog_str()\fR\fR
 160 .ad
 161 .br
 162 .na
 163 \fB\fBid_str()\fR\fR
 164 .ad
 165 .RS 17n
 166 These methods return string representations of the appropriate value. These
 167 methods can be used for textual output of the various catalog fields. The
 168 string representations of the constants are formed by removing the \fBEXT_\fR,
 169 \fBEXC_\fR, or \fBEXD_\fR prefix, replacing any underscore characters with
 170 spaces, and converting the remaining string to lowercase characters.
 171 .RE
 172 
 173 .SS "Exports"
 174 .sp
 175 .LP
 176 By default nothing is exported from this module. The following tags can be used
 177 to selectively import constants and functions defined in this module:
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fB:CONSTANTS\fR\fR
 182 .ad
 183 .RS 14n
 184 \fBEXT_\fR*, \fBEXC_\fR*, and \fBEXD_\fR*
 185 .RE
 186 
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fB:ALL\fR\fR
 191 .ad
 192 .RS 14n
 193 \fB:CONSTANTS\fR
 194 .RE
 195 
 196 .SH ATTRIBUTES
 197 .sp
 198 .LP
 199 See \fBattributes\fR(5) for descriptions of the following attributes:
 200 .sp
 201 
 202 .sp
 203 .TS
 204 box;
 205 c | c
 206 l | l .
 207 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 208 _
 209 Interface Stability     Evolving
 210 .TE
 211 
 212 .SH SEE ALSO
 213 .sp
 214 .LP
 215 \fBExacct\fR(3PERL), \fBExacct::File\fR(3PERL), \fBExacct::Object\fR(3PERL),
 216 \fBExacct::Object::Group\fR(3PERL), \fBExacct::Object::Item\fR(3PERL),
 217 \fBlibexacct\fR(3LIB), \fBattributes\fR(5)