Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::Constant.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ExtUtils::Constant 3perl"
58 .TH ExtUtils::Constant 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ExtUtils::Constant \- generate XS code to import C header constants
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 7
68 \& use ExtUtils::Constant qw (WriteConstants);
69 \& WriteConstants(
70 \& NAME => \*(AqFoo\*(Aq,
71 \& NAMES => [qw(FOO BAR BAZ)],
72 \& );
73 \& # Generates wrapper code to make the values of the constants FOO BAR BAZ
74 \& # available to perl
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 ExtUtils::Constant facilitates generating C and XS wrapper code to allow
79 perl modules to AUTOLOAD constants defined in C library header files.
80 It is principally used by the \f(CW\*(C`h2xs\*(C'\fR utility, on which this code is based.
81 It doesn't contain the routines to scan header files to extract these
82 constants.
83 .SH USAGE
84 .IX Header "USAGE"
85 Generally one only needs to call the \f(CW\*(C`WriteConstants\*(C'\fR function, and then
86 .PP
87 .Vb 1
88 \& #include "const\-c.inc"
89 .Ve
90 .PP
91 in the C section of \f(CW\*(C`Foo.xs\*(C'\fR
92 .PP
93 .Vb 1
94 \& INCLUDE: const\-xs.inc
95 .Ve
96 .PP
97 in the XS section of \f(CW\*(C`Foo.xs\*(C'\fR.
98 .PP
99 For greater flexibility use \f(CWconstant_types()\fR, \f(CW\*(C`C_constant\*(C'\fR and
100 \&\f(CW\*(C`XS_constant\*(C'\fR, with which \f(CW\*(C`WriteConstants\*(C'\fR is implemented.
101 .PP
102 Currently this module understands the following types. h2xs may only know
103 a subset. The sizes of the numeric types are chosen by the \f(CW\*(C`Configure\*(C'\fR
104 script at compile time.
105 .IP IV 4
106 .IX Item "IV"
107 signed integer, at least 32 bits.
108 .IP UV 4
109 .IX Item "UV"
110 unsigned integer, the same size as \fIIV\fR
111 .IP NV 4
112 .IX Item "NV"
113 floating point type, probably \f(CW\*(C`double\*(C'\fR, possibly \f(CW\*(C`long double\*(C'\fR
114 .IP PV 4
115 .IX Item "PV"
116 NUL terminated string, length will be determined with \f(CW\*(C`strlen\*(C'\fR
117 .IP PVN 4
118 .IX Item "PVN"
119 A fixed length thing, given as a [pointer, length] pair. If you know the
120 length of a string at compile time you may use this instead of \fIPV\fR
121 .IP SV 4
122 .IX Item "SV"
123 A \fBmortal\fR SV.
124 .IP YES 4
125 .IX Item "YES"
126 Truth. (\f(CW\*(C`PL_sv_yes\*(C'\fR) The value is not needed (and ignored).
127 .IP NO 4
128 .IX Item "NO"
129 Defined Falsehood. (\f(CW\*(C`PL_sv_no\*(C'\fR) The value is not needed (and ignored).
130 .IP UNDEF 4
131 .IX Item "UNDEF"
132 \&\f(CW\*(C`undef\*(C'\fR. The value of the macro is not needed.
133 .SH FUNCTIONS
134 .IX Header "FUNCTIONS"
135 .IP constant_types 4
136 .IX Item "constant_types"
137 A function returning a single scalar with \f(CW\*(C`#define\*(C'\fR definitions for the
138 constants used internally between the generated C and XS functions.
139 .IP "XS_constant PACKAGE, TYPES, XS_SUBNAME, C_SUBNAME" 4
140 .IX Item "XS_constant PACKAGE, TYPES, XS_SUBNAME, C_SUBNAME"
141 A function to generate the XS code to implement the perl subroutine
142 \&\fIPACKAGE\fR::constant used by \fIPACKAGE\fR::AUTOLOAD to load constants.
143 This XS code is a wrapper around a C subroutine usually generated by
144 \&\f(CW\*(C`C_constant\*(C'\fR, and usually named \f(CW\*(C`constant\*(C'\fR.
145 .Sp
146 \&\fITYPES\fR should be given either as a comma separated list of types that the
147 C subroutine \f(CW\*(C`constant\*(C'\fR will generate or as a reference to a hash. It should
148 be the same list of types as \f(CW\*(C`C_constant\*(C'\fR was given.
149 [Otherwise \f(CW\*(C`XS_constant\*(C'\fR and \f(CW\*(C`C_constant\*(C'\fR may have different ideas about
150 the number of parameters passed to the C function \f(CW\*(C`constant\*(C'\fR]
151 .Sp
152 You can call the perl visible subroutine something other than \f(CW\*(C`constant\*(C'\fR if
153 you give the parameter \fIXS_SUBNAME\fR. The C subroutine it calls defaults to
154 the name of the perl visible subroutine, unless you give the parameter
155 \&\fIC_SUBNAME\fR.
156 .IP "autoload PACKAGE, VERSION, AUTOLOADER" 4
157 .IX Item "autoload PACKAGE, VERSION, AUTOLOADER"
158 A function to generate the AUTOLOAD subroutine for the module \fIPACKAGE\fR
159 \&\fIVERSION\fR is the perl version the code should be backwards compatible with.
160 It defaults to the version of perl running the subroutine. If \fIAUTOLOADER\fR
161 is true, the AUTOLOAD subroutine falls back on AutoLoader::AUTOLOAD for all
162 names that the \fBconstant()\fR routine doesn't recognise.
163 .IP WriteMakefileSnippet 4
164 .IX Item "WriteMakefileSnippet"
165 WriteMakefileSnippet ATTRIBUTE => VALUE [, ...]
166 .Sp
167 A function to generate perl code for Makefile.PL that will regenerate
168 the constant subroutines. Parameters are named as passed to \f(CW\*(C`WriteConstants\*(C'\fR,
169 with the addition of \f(CW\*(C`INDENT\*(C'\fR to specify the number of leading spaces
170 (default 2).
171 .Sp
172 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
173 \&\f(CW\*(C`XS_FILE\*(C'\fR are recognised.
174 .IP "WriteConstants ATTRIBUTE => VALUE [, ...]" 4
175 .IX Item "WriteConstants ATTRIBUTE => VALUE [, ...]"
176 Writes a file of C code and a file of XS code which you should \f(CW\*(C`#include\*(C'\fR
177 and \f(CW\*(C`INCLUDE\*(C'\fR in the C and XS sections respectively of your module's XS
178 code. You probably want to do this in your \f(CW\*(C`Makefile.PL\*(C'\fR, so that you can
179 easily edit the list of constants without touching the rest of your module.
180 The attributes supported are
181 .RS 4
182 .IP NAME 4
183 .IX Item "NAME"
184 Name of the module. This must be specified
185 .IP DEFAULT_TYPE 4
186 .IX Item "DEFAULT_TYPE"
187 The default type for the constants. If not specified \f(CW\*(C`IV\*(C'\fR is assumed.
188 .IP BREAKOUT_AT 4
189 .IX Item "BREAKOUT_AT"
190 The names of the constants are grouped by length. Generate child subroutines
191 for each group with this number or more names in.
192 .IP NAMES 4
193 .IX Item "NAMES"
194 An array of constants' names, either scalars containing names, or hashrefs
195 as detailed in "C_constant".
196 .IP PROXYSUBS 4
197 .IX Item "PROXYSUBS"
198 If true, uses proxy subs. See ExtUtils::Constant::ProxySubs.
199 .IP C_FH 4
200 .IX Item "C_FH"
201 A filehandle to write the C code to. If not given, then \fIC_FILE\fR is opened
202 for writing.
203 .IP C_FILE 4
204 .IX Item "C_FILE"
205 The name of the file to write containing the C code. The default is
206 \&\f(CW\*(C`const\-c.inc\*(C'\fR. The \f(CW\*(C`\-\*(C'\fR in the name ensures that the file can't be
207 mistaken for anything related to a legitimate perl package name, and
208 not naming the file \f(CW\*(C`.c\*(C'\fR avoids having to override Makefile.PL's
209 \&\f(CW\*(C`.xs\*(C'\fR to \f(CW\*(C`.c\*(C'\fR rules.
210 .IP XS_FH 4
211 .IX Item "XS_FH"
212 A filehandle to write the XS code to. If not given, then \fIXS_FILE\fR is opened
213 for writing.
214 .IP XS_FILE 4
215 .IX Item "XS_FILE"
216 The name of the file to write containing the XS code. The default is
217 \&\f(CW\*(C`const\-xs.inc\*(C'\fR.
218 .IP XS_SUBNAME 4
219 .IX Item "XS_SUBNAME"
220 The perl visible name of the XS subroutine generated which will return the
221 constants. The default is \f(CW\*(C`constant\*(C'\fR.
222 .IP C_SUBNAME 4
223 .IX Item "C_SUBNAME"
224 The name of the C subroutine generated which will return the constants.
225 The default is \fIXS_SUBNAME\fR. Child subroutines have \f(CW\*(C`_\*(C'\fR and the name
226 length appended, so constants with 10 character names would be in
227 \&\f(CW\*(C`constant_10\*(C'\fR with the default \fIXS_SUBNAME\fR.
228 .RE
229 .RS 4
230 .RE
231 .SH AUTHOR
232 .IX Header "AUTHOR"
233 Nicholas Clark <[email protected]> based on the code in \f(CW\*(C`h2xs\*(C'\fR by Larry Wall and
234 others