1 # 2 # Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved. 3 # 4 5 # 6 # Sun::Solaris::Exacct::Catalog documentation. 7 # 8 9 =head1 NAME 10 11 Sun::Solaris::Exacct::Catalog - exacct catalog tag manipulation 12 13 =head1 SYNOPSIS 14 15 use Sun::Solaris::Exacct::Catalog qw(:ALL); 16 my $ea_cat = Sun::Solaris::Exacct::Catalog->new( 17 &EXT_UINT64 | &EXC_DEFAULT | &EXD_PROC_PID); 18 19 This class provides a wrapper around the 32-bit integer used as a catalog tag. 20 The catalog tag is represented as a Perl object blessed into the 21 C<Sun::Solaris::Exacct::Catalog> class so that methods can be used to manipulate 22 fields in a catalog tag. 23 24 =head2 Constants 25 26 All the C<EXT_*>, C<EXC_*>, and C<EXD_*> macros are provided as constants. 27 Constants passed to the methods below can either be the integer value such as 28 C<EXT_UINT8> or the string representation such as C<"EXT_UINT8">. 29 30 =head2 Functions 31 32 None. 33 34 =head2 Class methods 35 36 B<C<register($cat_pfx, $catalog_id, $export, @idlist)>> 37 38 This method is used to register application-defined C<libexacct(3LIB)> 39 catalogs with the exacct Perl library. See 40 F</usr/include/sys/exacct_catalog.h> for details of the catalog tag format. 41 This method allows symbolic names and strings to be used for manipulating 42 application-defined catalogs. The first two parameters define the catalog 43 prefix and associated numeric catalog ID. If the C<$export> parameter is true, 44 the constants are exported into the caller's package. The final parameter is a 45 list of C<(id, name)> pairs that identify the required constants. The 46 constants created by this method are formed by appending C<$cat_pfx> and 47 C<"_"> to each name in the list, replacing any spaces with underscore 48 characters and converting the resulting string to uppercase characters. The 49 C<$catalog_name> value is also created as a constant by prefixing it with 50 C<EXC_> and converting it to uppercase characters. Its value becomes that of 51 C<$catalog_id> shifted left by 24 bits. For example, the following call: 52 53 Sun::Solaris::Exacct::Catalog->ea_register("MYCAT", 0x01, 1, 54 FIRST => 0x00000001, SECOND => 0x00000010); 55 56 results in the definition of the following constants: 57 58 EXC_MYCAT 0x01 << 24 59 MYCAT_FIRST 0x00000001 60 MYCAT_SECOND 0x00000010 61 62 Only the catalog ID value of 0x01 is available for application use 63 C<(EXC_LOCAL)>. All other values are reserved. While it is possible to use 64 values other than 0x01, they might conflict with future extensions to the 65 libexacct file format. 66 67 If any errors are detected during this method, a string is returned containing 68 the appropriate error message. If the call is sucessful, C<undef> is returned. 69 70 B<C<new($integer)>> 71 72 B<C<new($cat_obj)>> 73 74 B<C<new($type, $catalog, $id)>> 75 76 This method creates and returns a new Catalog object, which is a wrapper 77 around a 32-bit integer catalog tag. Three possible argument lists can be 78 given. The first variant is to pass an integer formed by bitwise-inclusive OR 79 of the appropriate C<EX[TCD]_*> constants. The second variant is to pass an 80 existing Catalog object that will be copied. The final variant is to pass in 81 the type, catalog and ID fields as separate values. Each of these values can 82 be either an appropriate integer constant or the string representation of the 83 constant. 84 85 =head2 Object methods 86 87 B<C<value()>> 88 89 This method allows the value of the catalog tag to be queried. In a scalar 90 context it returns the 32-bit integer representing the tag. In a list context 91 it returns a C<(type, catalog, id)> triplet, where each member of the triplet 92 is a dual-typed scalar. 93 94 B<C<type()>> 95 96 This method returns the type field of the catalog tag as a dual-typed scalar. 97 98 B<C<catalog()>> 99 100 This method returns the catalog field of the catalog tag as a dual-typed 101 scalar. 102 103 B<C<id()>> 104 105 This method returns the id field of the catalog tag as a dual-typed scalar. 106 107 B<C<type_str()>> 108 109 B<C<catalog_str()>> 110 111 B<C<id_str()>> 112 113 These methods return string representations of the appropriate value. These 114 methods can be used for textual output of the various catalog fields. The 115 string representations of the constants are formed by removing the C<EXT_>, 116 C<EXC_>, or C<EXD_> prefix, replacing any underscore characters with spaces, 117 and converting the remaining string to lowercase characters. 118 119 =head2 Exports 120 121 By default nothing is exported from this module. The following tags can be 122 used to selectively import constants and functions defined in this module: 123 124 :CONSTANTS EXT_*, EXC_*, and EXD_* 125 126 :ALL :CONSTANTS 127 128 =head2 ATTRIBUTES 129 130 See C<attributes(5)> for descriptions of the following attributes: 131 132 ___________________________________________________________ 133 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 134 |_____________________________|_____________________________| 135 | Availability | CPAN (http://www.cpan.org) | 136 |_____________________________|_____________________________| 137 | Interface Stability | Evolving | 138 |_____________________________|_____________________________| 139 140 =head1 SEE ALSO 141 142 C<Sun::Solaris::Exacct(3)>, C<Sun::Solaris::Exacct::File(3)>, 143 C<Sun::Solaris::Exacct::Object(3)>, C<Sun::Solaris::Exacct::Object::Group(3)>, 144 C<Sun::Solaris::Exacct::Object::Item(3)>, C<libexacct(3LIB)>, C<attributes(5)>