.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\" ========================================================================
.de Sh \" Subsection heading
.de Sp \" Vertical space (when we can't use .PP)
.de Vb \" Begin verbatim text
.de Ve \" End verbatim text
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
. tm Index:\\$1\t\\n%\t"\\$2"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. \" simple accents for nroff and troff
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
.\" ========================================================================
.IX Title "ExtUtils::Constant 3"
.TH ExtUtils::Constant 3 "2002-06-01" "perl v5.8.0" "Perl Programmers Reference Guide"
ExtUtils::Constant \- generate XS code to import C header constants
\& use ExtUtils::Constant qw (WriteConstants);
\& NAMES => [qw(FOO BAR BAZ)],
\& # Generates wrapper code to make the values of the constants FOO BAR BAZ
ExtUtils::Constant facilitates generating C and \s-1XS\s0 wrapper code to allow
perl modules to \s-1AUTOLOAD\s0 constants defined in C library header files.
It is principally used by the \f(CW\*(C`h2xs\*(C'\fR utility, on which this code is based.
It doesn't contain the routines to scan header files to extract these
Generally one only needs to call the \f(CW\*(C`WriteConstants\*(C'\fR function, and then
\& #include "const-c.inc"
in the C section of \f(CW\*(C`Foo.xs\*(C'\fR
in the \s-1XS\s0 section of \f(CW\*(C`Foo.xs\*(C'\fR.
For greater flexibility use \f(CW\*(C`constant_types()\*(C'\fR, \f(CW\*(C`C_constant\*(C'\fR and
\&\f(CW\*(C`XS_constant\*(C'\fR, with which \f(CW\*(C`WriteConstants\*(C'\fR is implemented.
Currently this module understands the following types. h2xs may only know
a subset. The sizes of the numeric types are chosen by the \f(CW\*(C`Configure\*(C'\fR
signed integer, at least 32 bits.
unsigned integer, the same size as \fI\s-1IV\s0\fR
floating point type, probably \f(CW\*(C`double\*(C'\fR, possibly \f(CW\*(C`long double\*(C'\fR
\&\s-1NUL\s0 terminated string, length will be determined with \f(CW\*(C`strlen\*(C'\fR
A fixed length thing, given as a [pointer, length] pair. If you know the
length of a string at compile time you may use this instead of \fI\s-1PV\s0\fR
A \fBmortal\fR \s-1SV\s0.
Truth. (\f(CW\*(C`PL_sv_yes\*(C'\fR) The value is not needed (and ignored).
Defined Falsehood. (\f(CW\*(C`PL_sv_no\*(C'\fR) The value is not needed (and ignored).
\&\f(CW\*(C`undef\*(C'\fR. The value of the macro is not needed.
.IP "C_stringify \s-1NAME\s0" 4
.IX Item "C_stringify NAME"
A function which returns a 7 bit \s-1ASCII\s0 correctly \e escaped version of the
string passed suitable for C's "" or ''. It will die if passed Unicode
.IP "perl_stringify \s-1NAME\s0" 4
.IX Item "perl_stringify NAME"
A function which returns a 7 bit \s-1ASCII\s0 correctly \e escaped version of the
string passed suitable for a perl "" string.
.IX Item "constant_types"
A function returning a single scalar with \f(CW\*(C`#define\*(C'\fR definitions for the
constants used internally between the generated C and \s-1XS\s0 functions.
.IP "memEQ_clause \s-1NAME\s0, \s-1CHECKED_AT\s0, \s-1INDENT\s0" 4
.IX Item "memEQ_clause NAME, CHECKED_AT, INDENT"
A function to return a suitable C \f(CW\*(C`if\*(C'\fR statement to check whether \fI\s-1NAME\s0\fR
is equal to the C variable \f(CW\*(C`name\*(C'\fR. If \fI\s-1CHECKED_AT\s0\fR is defined, then it
is used to avoid \f(CW\*(C`memEQ\*(C'\fR for short names, or to generate a comment to
highlight the position of the character in the \f(CW\*(C`switch\*(C'\fR statement.
.IP "assign \s-1INDENT\s0, \s-1TYPE\s0, \s-1PRE\s0, \s-1POST\s0, \s-1VALUE\s0..." 4
.IX Item "assign INDENT, TYPE, PRE, POST, VALUE..."
A function to return a suitable assignment clause. If \fI\s-1TYPE\s0\fR is aggregate
(eg \fI\s-1PVN\s0\fR expects both pointer and length) then there should be multiple
\&\fI\s-1VALUE\s0\fRs for the components. \fI\s-1PRE\s0\fR and \fI\s-1POST\s0\fR if defined give snippets
of C code to proceed and follow the assignment. \fI\s-1PRE\s0\fR will be at the start
of a block, so variables may be defined in it.
return_clause \s-1ITEM\s0, \s-1INDENT\s0
A function to return a suitable \f(CW\*(C`#ifdef\*(C'\fR clause. \fI\s-1ITEM\s0\fR is a hashref
(as passed to \f(CW\*(C`C_constant\*(C'\fR and \f(CW\*(C`match_clause\*(C'\fR. \fI\s-1INDENT\s0\fR is the number
of spaces to indent, defaulting to 6.
.IP "switch_clause \s-1INDENT\s0, \s-1NAMELEN\s0, \s-1ITEMHASH\s0, \s-1ITEM\s0..." 4
.IX Item "switch_clause INDENT, NAMELEN, ITEMHASH, ITEM..."
An internal function to generate a suitable \f(CW\*(C`switch\*(C'\fR clause, called by
\&\f(CW\*(C`C_constant\*(C'\fR \fI\s-1ITEM\s0\fRs are in the hash ref format as given in the description
of \f(CW\*(C`C_constant\*(C'\fR, and must all have the names of the same length, given by
\&\fI\s-1NAMELEN\s0\fR (This is not checked). \fI\s-1ITEMHASH\s0\fR is a reference to a hash,
keyed by name, values being the hashrefs in the \fI\s-1ITEM\s0\fR list.
(No parameters are modified, and there can be keys in the \fI\s-1ITEMHASH\s0\fR that
are not in the list of \fI\s-1ITEM\s0\fRs without causing problems).
.IP "params \s-1WHAT\s0" 4
An internal function. \fI\s-1WHAT\s0\fR should be a hashref of types the constant
function will return. \fIparams\fR returns a hashref keyed \s-1IV\s0 \s-1NV\s0 \s-1PV\s0 \s-1SV\s0 to show
which combination of pointers will be needed in the C argument list.
dump_names \s-1DEFAULT_TYPE\s0, \s-1TYPES\s0, \s-1INDENT\s0, \s-1OPTIONS\s0, \s-1ITEM\s0...
An internal function to generate the embedded perl code that will regenerate
the constant subroutines. \fI\s-1DEFAULT_TYPE\s0\fR, \fI\s-1TYPES\s0\fR and \fI\s-1ITEM\s0\fRs are the
same as for C_constant. \fI\s-1INDENT\s0\fR is treated as number of spaces to indent
by. \fI\s-1OPTIONS\s0\fR is a hashref of options. Currently only \f(CW\*(C`declare_types\*(C'\fR is
recognised. If the value is true a \f(CW$types\fR is always declared in the perl
code generated, if defined and false never declared, and if undefined \f(CW$types\fR
is only declared if the values in \fI\s-1TYPES\s0\fR as passed in cannot be inferred from
\&\fI\s-1DEFAULT_TYPES\s0\fR and the \fI\s-1ITEM\s0\fRs.
dogfood \s-1PACKAGE\s0, \s-1SUBNAME\s0, \s-1DEFAULT_TYPE\s0, \s-1TYPES\s0, \s-1INDENT\s0, \s-1BREAKOUT\s0, \s-1ITEM\s0...
An internal function to generate the embedded perl code that will regenerate
the constant subroutines. Parameters are the same as for C_constant.
C_constant \s-1PACKAGE\s0, \s-1SUBNAME\s0, \s-1DEFAULT_TYPE\s0, \s-1TYPES\s0, \s-1INDENT\s0, \s-1BREAKOUT\s0, \s-1ITEM\s0...
A function that returns a \fBlist\fR of C subroutine definitions that return
the value and type of constants when passed the name by the \s-1XS\s0 wrapper.
\&\fI\s-1ITEM\s0...\fR gives a list of constant names. Each can either be a string,
which is taken as a C macro name, or a reference to a hash with the following
The name of the constant, as seen by the perl code.
The type of the constant (\fI\s-1IV\s0\fR, \fI\s-1NV\s0\fR etc)
A C expression for the value of the constant, or a list of C expressions if
the type is aggregate. This defaults to the \fIname\fR if not given.
The C pre-processor macro to use in the \f(CW\*(C`#ifdef\*(C'\fR. This defaults to the
\&\fIname\fR, and is mainly used if \fIvalue\fR is an \f(CW\*(C`enum\*(C'\fR. If a reference an
array is passed then the first element is used in place of the \f(CW\*(C`#ifdef\*(C'\fR
line, and the second element in place of the \f(CW\*(C`#endif\*(C'\fR. This allows
pre-processor constructions such as
to be used to determine if a constant is to be defined.
A \*(L"macro\*(R" 1 signals that the constant is always defined, so the \f(CW\*(C`#if\*(C'\fR/\f(CW\*(C`#endif\*(C'\fR
Default value to use (instead of \f(CW\*(C`croak\*(C'\fRing with \*(L"your vendor has not
defined...\*(R") to return if the macro isn't defined. Specify a reference to
an array with type followed by value(s).
C code to use before the assignment of the value of the constant. This allows
you to use temporary variables to extract a value from part of a \f(CW\*(C`struct\*(C'\fR
and return this as \fIvalue\fR. This C code is places at the start of a block,
so you can declare variables in it.
C code to place between the assignment of value (to a temporary) and the
return from the function. This allows you to clear up anything in \fIpre\fR.
.IP "def_pre =item def_post" 8
.IX Item "def_pre =item def_post"
Equivalents of \fIpre\fR and \fIpost\fR for the default value.
Generated internally. Is zero or undefined if name is 7 bit \s-1ASCII\s0,
\&\*(L"no\*(R" if the name is 8 bit (and so should only match if \fISvUTF8()\fR is false),
\&\*(L"yes\*(R" if the name is utf8 encoded.
The internals automatically clone any name with characters 128\-255 but none
256+ (ie one that could be either in bytes or utf8) into a second entry
\&\fI\s-1PACKAGE\s0\fR is the name of the package, and is only used in comments inside the
The next 5 arguments can safely be given as \f(CW\*(C`undef\*(C'\fR, and are mainly used
for recursion. \fI\s-1SUBNAME\s0\fR defaults to \f(CW\*(C`constant\*(C'\fR if undefined.
\&\fI\s-1DEFAULT_TYPE\s0\fR is the type returned by \f(CW\*(C`ITEM\*(C'\fRs that don't specify their
type. In turn it defaults to \fI\s-1IV\s0\fR. \fI\s-1TYPES\s0\fR should be given either as a comma
separated list of types that the C subroutine \f(CW\*(C`constant\*(C'\fR will generate or as
a reference to a hash. \fI\s-1DEFAULT_TYPE\s0\fR will be added to the list if not
present, as will any types given in the list of \fI\s-1ITEM\s0\fRs. The resultant list
should be the same list of types that \f(CW\*(C`XS_constant\*(C'\fR is given. [Otherwise
\&\f(CW\*(C`XS_constant\*(C'\fR and \f(CW\*(C`C_constant\*(C'\fR may differ in the number of parameters to the
constant function. \fI\s-1INDENT\s0\fR is currently unused and ignored. In future it may
be used to pass in information used to change the C indentation style used.]
The best way to maintain consistency is to pass in a hash reference and let
\&\fI\s-1BREAKOUT\s0\fR governs when child functions of \fI\s-1SUBNAME\s0\fR are generated. If there
are \fI\s-1BREAKOUT\s0\fR or more \fI\s-1ITEM\s0\fRs with the same length of name, then the code
to switch between them is placed into a function named \fI\s-1SUBNAME\s0\fR_\fI\s-1LEN\s0\fR, for
example \f(CW\*(C`constant_5\*(C'\fR for names 5 characters long. The default \fI\s-1BREAKOUT\s0\fR is
3. A single \f(CW\*(C`ITEM\*(C'\fR is always inlined.
.IP "XS_constant \s-1PACKAGE\s0, \s-1TYPES\s0, \s-1SUBNAME\s0, C_SUBNAME" 4
.IX Item "XS_constant PACKAGE, TYPES, SUBNAME, C_SUBNAME"
A function to generate the \s-1XS\s0 code to implement the perl subroutine
\&\fI\s-1PACKAGE\s0\fR::constant used by \fI\s-1PACKAGE\s0\fR::AUTOLOAD to load constants.
This \s-1XS\s0 code is a wrapper around a C subroutine usually generated by
\&\f(CW\*(C`C_constant\*(C'\fR, and usually named \f(CW\*(C`constant\*(C'\fR.
\&\fI\s-1TYPES\s0\fR should be given either as a comma separated list of types that the
C subroutine \f(CW\*(C`constant\*(C'\fR will generate or as a reference to a hash. It should
be the same list of types as \f(CW\*(C`C_constant\*(C'\fR was given.
[Otherwise \f(CW\*(C`XS_constant\*(C'\fR and \f(CW\*(C`C_constant\*(C'\fR may have different ideas about
the number of parameters passed to the C function \f(CW\*(C`constant\*(C'\fR]
You can call the perl visible subroutine something other than \f(CW\*(C`constant\*(C'\fR if
you give the parameter \fI\s-1SUBNAME\s0\fR. The C subroutine it calls defaults to
the name of the perl visible subroutine, unless you give the parameter
.IP "autoload \s-1PACKAGE\s0, \s-1VERSION\s0, \s-1AUTOLOADER\s0" 4
.IX Item "autoload PACKAGE, VERSION, AUTOLOADER"
A function to generate the \s-1AUTOLOAD\s0 subroutine for the module \fI\s-1PACKAGE\s0\fR
\&\fI\s-1VERSION\s0\fR is the perl version the code should be backwards compatible with.
It defaults to the version of perl running the subroutine. If \fI\s-1AUTOLOADER\s0\fR
is true, the \s-1AUTOLOAD\s0 subroutine falls back on AutoLoader::AUTOLOAD for all
names that the \fIconstant()\fR routine doesn't recognise.
.IP "WriteMakefileSnippet" 4
.IX Item "WriteMakefileSnippet"
WriteMakefileSnippet \s-1ATTRIBUTE\s0 => \s-1VALUE\s0 [, ...]
A function to generate perl code for Makefile.PL that will regenerate
the constant subroutines. Parameters are named as passed to \f(CW\*(C`WriteConstants\*(C'\fR,
with the addition of \f(CW\*(C`INDENT\*(C'\fR to specify the number of leading spaces
Currently only \f(CW\*(C`INDENT\*(C'\fR, \f(CW\*(C`NAME\*(C'\fR, \f(CW\*(C`DEFAULT_TYPE\*(C'\fR, \f(CW\*(C`NAMES\*(C'\fR, \f(CW\*(C`C_FILE\*(C'\fR and
\&\f(CW\*(C`XS_FILE\*(C'\fR are recognised.
.IP "WriteConstants \s-1ATTRIBUTE\s0 => \s-1VALUE\s0 [, ...]" 4
.IX Item "WriteConstants ATTRIBUTE => VALUE [, ...]"
Writes a file of C code and a file of \s-1XS\s0 code which you should \f(CW\*(C`#include\*(C'\fR
and \f(CW\*(C`INCLUDE\*(C'\fR in the C and \s-1XS\s0 sections respectively of your module's \s-1XS\s0
code. You probaby want to do this in your \f(CW\*(C`Makefile.PL\*(C'\fR, so that you can
easily edit the list of constants without touching the rest of your module.
The attributes supported are
Name of the module. This must be specified
.IP "\s-1DEFAULT_TYPE\s0" 4
The default type for the constants. If not specified \f(CW\*(C`IV\*(C'\fR is assumed.
.IP "\s-1BREAKOUT_AT\s0" 4
The names of the constants are grouped by length. Generate child subroutines
for each group with this number or more names in.
An array of constants' names, either scalars containing names, or hashrefs
as detailed in \*(L"C_constant\*(R".
The name of the file to write containing the C code. The default is
\&\f(CW\*(C`const\-c.inc\*(C'\fR. The \f(CW\*(C`\-\*(C'\fR in the name ensures that the file can't be
mistaken for anything related to a legitimate perl package name, and
not naming the file \f(CW\*(C`.c\*(C'\fR avoids having to override Makefile.PL's
\&\f(CW\*(C`.xs\*(C'\fR to \f(CW\*(C`.c\*(C'\fR rules.
The name of the file to write containing the \s-1XS\s0 code. The default is
\&\f(CW\*(C`const\-xs.inc\*(C'\fR.
The perl visible name of the \s-1XS\s0 subroutine generated which will return the
constants. The default is \f(CW\*(C`constant\*(C'\fR.
The name of the C subroutine generated which will return the constants.
The default is \fI\s-1SUBNAME\s0\fR. Child subroutines have \f(CW\*(C`_\*(C'\fR and the name
length appended, so constants with 10 character names would be in
\&\f(CW\*(C`constant_10\*(C'\fR with the default \fI\s-1XS_SUBNAME\s0\fR.
Nicholas Clark <nick@ccl4.org> based on the code in \f(CW\*(C`h2xs\*(C'\fR by Larry Wall and
projects / OpenSPARC-T2-DV / blob