Debian Codegraph @

upstream/debian-unstable/man1/h2xs.1

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 "H2XS 1"
58 .TH H2XS 1 2026-04-10 "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 h2xs \- convert .h C header files to Perl extensions
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 \&\fBh2xs\fR [\fBOPTIONS\fR ...] [headerfile ... [extra_libraries]]
68 .PP
69 \&\fBh2xs\fR \fB\-h\fR|\fB\-?\fR|\fB\-\-help\fR
70 .SH DESCRIPTION
71 .IX Header "DESCRIPTION"
72 \&\fIh2xs\fR builds a Perl extension from C header files. The extension
73 will include functions which can be used to retrieve the value of any
74 #define statement which was in the C header files.
75 .PP
76 The \fImodule_name\fR will be used for the name of the extension. If
77 module_name is not supplied then the name of the first header file
78 will be used, with the first character capitalized.
79 .PP
80 If the extension might need extra libraries, they should be included
81 here. The extension Makefile.PL will take care of checking whether
82 the libraries actually exist and how they should be loaded. The extra
83 libraries should be specified in the form \-lm \-lposix, etc, just as on
84 the cc command line. By default, the Makefile.PL will search through
85 the library path determined by Configure. That path can be augmented
86 by including arguments of the form \fB\-L/another/library/path\fR in the
87 extra-libraries argument.
88 .PP
89 In spite of its name, \fIh2xs\fR may also be used to create a skeleton pure
90 Perl module. See the \fB\-X\fR option.
91 .SH OPTIONS
92 .IX Header "OPTIONS"
93 .IP "\fB\-A\fR, \fB\-\-omit\-autoload\fR" 5
94 .IX Item "-A, --omit-autoload"
95 Omit all autoload facilities. This is the same as \fB\-c\fR but also
96 removes the \f(CW\*(C`use\ AutoLoader\*(C'\fR statement from the .pm file.
97 .IP "\fB\-B\fR, \fB\-\-beta\-version\fR" 5
98 .IX Item "-B, --beta-version"
99 Use an alpha/beta style version number. Causes version number to
100 be "0.00_01" unless \fB\-v\fR is specified.
101 .IP "\fB\-C\fR, \fB\-\-omit\-changes\fR" 5
102 .IX Item "-C, --omit-changes"
103 Omits creation of the \fIChanges\fR file, and adds a HISTORY section to
104 the POD template.
105 .IP "\fB\-F\fR, \fB\-\-cpp\-flags\fR=\fIaddflags\fR" 5
106 .IX Item "-F, --cpp-flags=addflags"
107 Additional flags to specify to C preprocessor when scanning header for
108 function declarations. Writes these options in the generated \fIMakefile.PL\fR
109 too.
110 .IP "\fB\-M\fR, \fB\-\-func\-mask\fR=\fIregular expression\fR" 5
111 .IX Item "-M, --func-mask=regular expression"
112 selects functions/macros to process.
113 .IP "\fB\-O\fR, \fB\-\-overwrite\-ok\fR" 5
114 .IX Item "-O, --overwrite-ok"
115 Allows a pre-existing extension directory to be overwritten.
116 .IP "\fB\-P\fR, \fB\-\-omit\-pod\fR" 5
117 .IX Item "-P, --omit-pod"
118 Omit the autogenerated stub POD section.
119 .IP "\fB\-X\fR, \fB\-\-omit\-XS\fR" 5
120 .IX Item "-X, --omit-XS"
121 Omit the XS portion. Used to generate a skeleton pure Perl module.
122 \&\f(CW\*(C`\-c\*(C'\fR and \f(CW\*(C`\-f\*(C'\fR are implicitly enabled.
123 .IP "\fB\-a\fR, \fB\-\-gen\-accessors\fR" 5
124 .IX Item "-a, --gen-accessors"
125 Generate an accessor method for each element of structs and unions. The
126 generated methods are named after the element name; will return the current
127 value of the element if called without additional arguments; and will set
128 the element to the supplied value (and return the new value) if called with
129 an additional argument. Embedded structures and unions are returned as a
130 pointer rather than the complete structure, to facilitate chained calls.
131 .Sp
132 These methods all apply to the Ptr type for the structure; additionally
133 two methods are constructed for the structure type itself, \f(CW\*(C`_to_ptr\*(C'\fR
134 which returns a Ptr type pointing to the same structure, and a \f(CW\*(C`new\*(C'\fR
135 method to construct and return a new structure, initialised to zeroes.
136 .IP "\fB\-b\fR, \fB\-\-compat\-version\fR=\fIversion\fR" 5
137 .IX Item "-b, --compat-version=version"
138 Generates a .pm file which is backwards compatible with the specified
139 perl version.
140 .Sp
141 For versions < 5.6.0, the changes are.
142 \- no use of 'our' (uses 'use vars' instead)
143 \- no 'use warnings'
144 .Sp
145 Specifying a compatibility version higher than the version of perl you
146 are using to run h2xs will have no effect. If unspecified h2xs will default
147 to compatibility with the version of perl you are using to run h2xs.
148 .IP "\fB\-c\fR, \fB\-\-omit\-constant\fR" 5
149 .IX Item "-c, --omit-constant"
150 Omit \f(CWconstant()\fR from the .xs file and corresponding specialised
151 \&\f(CW\*(C`AUTOLOAD\*(C'\fR from the .pm file.
152 .IP "\fB\-d\fR, \fB\-\-debugging\fR" 5
153 .IX Item "-d, --debugging"
154 Turn on debugging messages.
155 .IP "\fB\-e\fR, \fB\-\-omit\-enums\fR=[\fIregular expression\fR]" 5
156 .IX Item "-e, --omit-enums=[regular expression]"
157 If \fIregular expression\fR is not given, skip all constants that are defined in
158 a C enumeration. Otherwise skip only those constants that are defined in an
159 enum whose name matches \fIregular expression\fR.
160 .Sp
161 Since \fIregular expression\fR is optional, make sure that this switch is followed
162 by at least one other switch if you omit \fIregular expression\fR and have some
163 pending arguments such as header-file names. This is ok:
164 .Sp
165 .Vb 1
166 \& h2xs \-e \-n Module::Foo foo.h
167 .Ve
168 .Sp
169 This is not ok:
170 .Sp
171 .Vb 1
172 \& h2xs \-n Module::Foo \-e foo.h
173 .Ve
174 .Sp
175 In the latter, foo.h is taken as \fIregular expression\fR.
176 .IP "\fB\-f\fR, \fB\-\-force\fR" 5
177 .IX Item "-f, --force"
178 Allows an extension to be created for a header even if that header is
179 not found in standard include directories.
180 .IP "\fB\-g\fR, \fB\-\-global\fR" 5
181 .IX Item "-g, --global"
182 Include code for safely storing static data in the .xs file.
183 Extensions that do no make use of static data can ignore this option.
184 .IP "\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR" 5
185 .IX Item "-h, -?, --help"
186 Print the usage, help and version for this h2xs and exit.
187 .IP "\fB\-k\fR, \fB\-\-omit\-const\-func\fR" 5
188 .IX Item "-k, --omit-const-func"
189 For function arguments declared as \f(CW\*(C`const\*(C'\fR, omit the const attribute in the
190 generated XS code.
191 .IP "\fB\-m\fR, \fB\-\-gen\-tied\-var\fR" 5
192 .IX Item "-m, --gen-tied-var"
193 \&\fBExperimental\fR: for each variable declared in the header file(s), declare
194 a perl variable of the same name magically tied to the C variable.
195 .IP "\fB\-n\fR, \fB\-\-name\fR=\fImodule_name\fR" 5
196 .IX Item "-n, --name=module_name"
197 Specifies a name to be used for the extension, e.g., \-n\ RPC::DCE
198 .IP "\fB\-o\fR, \fB\-\-opaque\-re\fR=\fIregular expression\fR" 5
199 .IX Item "-o, --opaque-re=regular expression"
200 Use "opaque" data type for the C types matched by the regular
201 expression, even if these types are \f(CW\*(C`typedef\*(C'\fR\-equivalent to types
202 from typemaps. Should not be used without \fB\-x\fR.
203 .Sp
204 This may be useful since, say, types which are \f(CW\*(C`typedef\*(C'\fR\-equivalent
205 to integers may represent OS-related handles, and one may want to work
206 with these handles in OO-way, as in \f(CW\*(C`$handle\->do_something()\*(C'\fR.
207 Use \f(CW\*(C`\-o .\*(C'\fR if you want to handle all the \f(CW\*(C`typedef\*(C'\fRed types as opaque
208 types.
209 .Sp
210 The type-to-match is whitewashed (except for commas, which have no
211 whitespace before them, and multiple \f(CW\*(C`*\*(C'\fR which have no whitespace
212 between them).
213 .IP "\fB\-p\fR, \fB\-\-remove\-prefix\fR=\fIprefix\fR" 5
214 .IX Item "-p, --remove-prefix=prefix"
215 Specify a prefix which should be removed from the Perl function names,
216 e.g., \-p\ sec_rgy_ This sets up the XS \fBPREFIX\fR keyword and removes
217 the prefix from functions that are autoloaded via the \f(CWconstant()\fR
218 mechanism.
219 .IP "\fB\-s\fR, \fB\-\-const\-subs\fR=\fIsub1,sub2\fR" 5
220 .IX Item "-s, --const-subs=sub1,sub2"
221 Create a perl subroutine for the specified macros rather than autoload
222 with the \fBconstant()\fR subroutine. These macros are assumed to have a
223 return type of \fBchar *\fR, e.g.,
224 \&\-s\ sec_rgy_wildcard_name,sec_rgy_wildcard_sid.
225 .IP "\fB\-t\fR, \fB\-\-default\-type\fR=\fItype\fR" 5
226 .IX Item "-t, --default-type=type"
227 Specify the internal type that the \fBconstant()\fR mechanism uses for macros.
228 The default is IV (signed integer). Currently all macros found during the
229 header scanning process will be assumed to have this type. Future versions
230 of \f(CW\*(C`h2xs\*(C'\fR may gain the ability to make educated guesses.
231 .IP \fB\-\-use\-new\-tests\fR 5
232 .IX Item "--use-new-tests"
233 When \fB\-\-compat\-version\fR (\fB\-b\fR) is present the generated tests will use
234 \&\f(CW\*(C`Test::More\*(C'\fR rather than \f(CW\*(C`Test\*(C'\fR which is the default for versions before
235 5.6.2. \f(CW\*(C`Test::More\*(C'\fR will be added to PREREQ_PM in the generated
236 \&\f(CW\*(C`Makefile.PL\*(C'\fR.
237 .IP \fB\-\-use\-old\-tests\fR 5
238 .IX Item "--use-old-tests"
239 Will force the generation of test code that uses the older \f(CW\*(C`Test\*(C'\fR module.
240 .IP \fB\-\-skip\-exporter\fR 5
241 .IX Item "--skip-exporter"
242 Do not use \f(CW\*(C`Exporter\*(C'\fR and/or export any symbol.
243 .IP \fB\-\-skip\-ppport\fR 5
244 .IX Item "--skip-ppport"
245 Do not use \f(CW\*(C`Devel::PPPort\*(C'\fR: no portability to older version.
246 .IP \fB\-\-skip\-autoloader\fR 5
247 .IX Item "--skip-autoloader"
248 Do not use the module \f(CW\*(C`AutoLoader\*(C'\fR; but keep the \fBconstant()\fR function
249 and \f(CW\*(C`sub AUTOLOAD\*(C'\fR for constants.
250 .IP \fB\-\-skip\-strict\fR 5
251 .IX Item "--skip-strict"
252 Do not use the pragma \f(CW\*(C`strict\*(C'\fR.
253 .IP \fB\-\-skip\-warnings\fR 5
254 .IX Item "--skip-warnings"
255 Do not use the pragma \f(CW\*(C`warnings\*(C'\fR.
256 .IP "\fB\-v\fR, \fB\-\-version\fR=\fIversion\fR" 5
257 .IX Item "-v, --version=version"
258 Specify a version number for this extension. This version number is added
259 to the templates. The default is 0.01, or 0.00_01 if \f(CW\*(C`\-B\*(C'\fR is specified.
260 The version specified should be numeric.
261 .IP "\fB\-x\fR, \fB\-\-autogen\-xsubs\fR" 5
262 .IX Item "-x, --autogen-xsubs"
263 Automatically generate XSUBs basing on function declarations in the
264 header file. The package \f(CW\*(C`C::Scan\*(C'\fR should be installed. If this
265 option is specified, the name of the header file may look like
266 \&\f(CW\*(C`NAME1,NAME2\*(C'\fR. In this case NAME1 is used instead of the specified
267 string, but XSUBs are emitted only for the declarations included from
268 file NAME2.
269 .Sp
270 Note that some types of arguments/return\-values for functions may
271 result in XSUB\-declarations/typemap\-entries which need
272 hand-editing. Such may be objects which cannot be converted from/to a
273 pointer (like \f(CW\*(C`long long\*(C'\fR), pointers to functions, or arrays. See
274 also the section on "LIMITATIONS of \fB\-x\fR".
275 .SH EXAMPLES
276 .IX Header "EXAMPLES"
277 .Vb 2
278 \& # Default behavior, extension is Rusers
279 \& h2xs rpcsvc/rusers
280 \&
281 \& # Same, but extension is RUSERS
282 \& h2xs \-n RUSERS rpcsvc/rusers
283 \&
284 \& # Extension is rpcsvc::rusers. Still finds <rpcsvc/rusers.h>
285 \& h2xs rpcsvc::rusers
286 \&
287 \& # Extension is ONC::RPC. Still finds <rpcsvc/rusers.h>
288 \& h2xs \-n ONC::RPC rpcsvc/rusers
289 \&
290 \& # Without constant() or AUTOLOAD
291 \& h2xs \-c rpcsvc/rusers
292 \&
293 \& # Creates templates for an extension named RPC
294 \& h2xs \-cfn RPC
295 \&
296 \& # Extension is ONC::RPC.
297 \& h2xs \-cfn ONC::RPC
298 \&
299 \& # Extension is a pure Perl module with no XS code.
300 \& h2xs \-X My::Module
301 \&
302 \& # Extension is Lib::Foo which works at least with Perl5.005_03.
303 \& # Constants are created for all #defines and enums h2xs can find
304 \& # in foo.h.
305 \& h2xs \-b 5.5.3 \-n Lib::Foo foo.h
306 \&
307 \& # Extension is Lib::Foo which works at least with Perl5.005_03.
308 \& # Constants are created for all #defines but only for enums
309 \& # whose names do not start with \*(Aqbar_\*(Aq.
310 \& h2xs \-b 5.5.3 \-e \*(Aq^bar_\*(Aq \-n Lib::Foo foo.h
311 \&
312 \& # Makefile.PL will look for library \-lrpc in
313 \& # additional directory /opt/net/lib
314 \& h2xs rpcsvc/rusers \-L/opt/net/lib \-lrpc
315 \&
316 \& # Extension is DCE::rgynbase
317 \& # prefix "sec_rgy_" is dropped from perl function names
318 \& h2xs \-n DCE::rgynbase \-p sec_rgy_ dce/rgynbase
319 \&
320 \& # Extension is DCE::rgynbase
321 \& # prefix "sec_rgy_" is dropped from perl function names
322 \& # subroutines are created for sec_rgy_wildcard_name and
323 \& # sec_rgy_wildcard_sid
324 \& h2xs \-n DCE::rgynbase \-p sec_rgy_ \e
325 \& \-s sec_rgy_wildcard_name,sec_rgy_wildcard_sid dce/rgynbase
326 \&
327 \& # Make XS without defines in perl.h, but with function declarations
328 \& # visible from perl.h. Name of the extension is perl1.
329 \& # When scanning perl.h, define \-DEXT=extern \-DdEXT= \-DINIT(x)=
330 \& # Extra backslashes below because the string is passed to shell.
331 \& # Note that a directory with perl header files would
332 \& # be added automatically to include path.
333 \& h2xs \-xAn perl1 \-F "\-DEXT=extern \-DdEXT= \-DINIT\e(x\e)=" perl.h
334 \&
335 \& # Same with function declaration in proto.h as visible from perl.h.
336 \& h2xs \-xAn perl2 perl.h,proto.h
337 \&
338 \& # Same but select only functions which match /^av_/
339 \& h2xs \-M \*(Aq^av_\*(Aq \-xAn perl2 perl.h,proto.h
340 \&
341 \& # Same but treat SV* etc as "opaque" types
342 \& h2xs \-o \*(Aq^[S]V \e*$\*(Aq \-M \*(Aq^av_\*(Aq \-xAn perl2 perl.h,proto.h
343 .Ve
344 .SS "Extension based on \fI.h\fP and \fI.c\fP files"
345 .IX Subsection "Extension based on .h and .c files"
346 Suppose that you have some C files implementing some functionality,
347 and the corresponding header files. How to create an extension which
348 makes this functionality accessible in Perl? The example below
349 assumes that the header files are \fIinterface_simple.h\fR and
350 \&\fIinterface_hairy.h\fR, and you want the perl module be named as
351 \&\f(CW\*(C`Ext::Ension\*(C'\fR. If you need some preprocessor directives and/or
352 linking with external libraries, see the flags \f(CW\*(C`\-F\*(C'\fR, \f(CW\*(C`\-L\*(C'\fR and \f(CW\*(C`\-l\*(C'\fR
353 in "OPTIONS".
354 .IP "Find the directory name" 4
355 .IX Item "Find the directory name"
356 Start with a dummy run of h2xs:
357 .Sp
358 .Vb 1
359 \& h2xs \-Afn Ext::Ension
360 .Ve
361 .Sp
362 The only purpose of this step is to create the needed directories, and
363 let you know the names of these directories. From the output you can
364 see that the directory for the extension is \fIExt/Ension\fR.
365 .IP "Copy C files" 4
366 .IX Item "Copy C files"
367 Copy your header files and C files to this directory \fIExt/Ension\fR.
368 .IP "Create the extension" 4
369 .IX Item "Create the extension"
370 Run h2xs, overwriting older autogenerated files:
371 .Sp
372 .Vb 1
373 \& h2xs \-Oxan Ext::Ension interface_simple.h interface_hairy.h
374 .Ve
375 .Sp
376 h2xs looks for header files \fIafter\fR changing to the extension
377 directory, so it will find your header files OK.
378 .IP "Archive and test" 4
379 .IX Item "Archive and test"
380 As usual, run
381 .Sp
382 .Vb 5
383 \& cd Ext/Ension
384 \& perl Makefile.PL
385 \& make dist
386 \& make
387 \& make test
388 .Ve
389 .IP Hints 4
390 .IX Item "Hints"
391 It is important to do \f(CW\*(C`make dist\*(C'\fR as early as possible. This way you
392 can easily \fBmerge\fR\|(1) your changes to autogenerated files if you decide
393 to edit your \f(CW\*(C`.h\*(C'\fR files and rerun h2xs.
394 .Sp
395 Do not forget to edit the documentation in the generated \fI.pm\fR file.
396 .Sp
397 Consider the autogenerated files as skeletons only, you may invent
398 better interfaces than what h2xs could guess.
399 .Sp
400 Consider this section as a guideline only, some other options of h2xs
401 may better suit your needs.
402 .SH ENVIRONMENT
403 .IX Header "ENVIRONMENT"
404 No environment variables are used.
405 .SH AUTHOR
406 .IX Header "AUTHOR"
407 Larry Wall and others
408 .SH "SEE ALSO"
409 .IX Header "SEE ALSO"
410 perl, perlxstut, ExtUtils::MakeMaker, and AutoLoader.
411 .SH DIAGNOSTICS
412 .IX Header "DIAGNOSTICS"
413 The usual warnings if it cannot read or write the files involved.
414 .SH "LIMITATIONS of \fB\-x\fP"
415 .IX Header "LIMITATIONS of -x"
416 \&\fIh2xs\fR would not distinguish whether an argument to a C function
417 which is of the form, say, \f(CW\*(C`int *\*(C'\fR, is an input, output, or
418 input/output parameter. In particular, argument declarations of the
419 form
420 .PP
421 .Vb 3
422 \& int
423 \& foo(n)
424 \& int *n
425 .Ve
426 .PP
427 should be better rewritten as
428 .PP
429 .Vb 3
430 \& int
431 \& foo(n)
432 \& int &n
433 .Ve
434 .PP
435 if \f(CW\*(C`n\*(C'\fR is an input parameter.
436 .PP
437 Additionally, \fIh2xs\fR has no facilities to intuit that a function
438 .PP
439 .Vb 4
440 \& int
441 \& foo(addr,l)
442 \& char *addr
443 \& int l
444 .Ve
445 .PP
446 takes a pair of address and length of data at this address, so it is better
447 to rewrite this function as
448 .PP
449 .Vb 11
450 \& int
451 \& foo(sv)
452 \& SV *addr
453 \& PREINIT:
454 \& STRLEN len;
455 \& char *s;
456 \& CODE:
457 \& s = SvPV(sv,len);
458 \& RETVAL = foo(s, len);
459 \& OUTPUT:
460 \& RETVAL
461 .Ve
462 .PP
463 or alternately
464 .PP
465 .Vb 5
466 \& static int
467 \& my_foo(SV *sv)
468 \& {
469 \& STRLEN len;
470 \& char *s = SvPV(sv,len);
471 \&
472 \& return foo(s, len);
473 \& }
474 \&
475 \& MODULE = foo PACKAGE = foo PREFIX = my_
476 \&
477 \& int
478 \& foo(sv)
479 \& SV *sv
480 .Ve
481 .PP
482 See perlxs and perlxstut for additional details.