Debian Codegraph @

upstream/opensuse-tumbleweed/man1/h2xs.1

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