The h2xs utility builds a Perl extension from C header
files. The extension will include functions that can be used to
retrieve the value of any #define statement that was in the
C header files.
The module_name will be used for the name of the
extension. If module_name is not supplied, the name of the
first header file will be used, with the first character
capitalized.
If the extension might need extra libraries, they should be
included here. The extension Makefile.PL will check to
determine whether the libraries actually exist and how they should
be loaded. The extra libraries should be specified in the form
-lm-lposix, and so on, just as on the cc(1) command
line. By default, the Makefile.PL will search through the
library path determined by Configure. That path can be
augmented by including arguments of the form: -L/dirname/subdirname/subdirname2
in the extra_libraries argument.
Omit all autoload facilities. This is the same as -c,
but also removes the "use AutoLoader" statement from the .pm
file.
-C
Omits creation of the Changes file, and adds a HISTORY
section to the POD template.
-F
Additional flags to specify to C preprocessor when scanning
header for function declarations. Should not be used without
-x.
-Mregular_expression
Selects functions/macros to process.
-O
Allows a pre-existing extension directory to be
overwritten.
-P
Omit the autogenerated stub POD section.
-X
Omit the XS portion. Used to generate templates for a module
which is not XS-based. The -c and -f options are
implicitly enabled.
-a
Generate an accessor method for each element of structures and
unions. The generated methods are named after the element name;
will return the current value of the element if called without
additional arguments; and will set the element to the supplied
value (and return the new value) if called with an additional
argument. Embedded structures and unions are returned as a pointer
rather than the complete structure, to facilitate chained calls.
These methods all apply to the Ptr type for the
structure. Additionally, two methods are constructed for the
structure type itself, _to_ptr which returns a Ptr
type pointing to the same structure, and a new method to
construct and return a new structure, initialized to
zeroes.
-c
Omit "constant()" from the .xs file and corresponding
specialized "AUTOLOAD" from the .pm file.
-d
Turn on debugging messages.
-f
Allows an extension to be created for a header even if that
header is not found in standard include directories.
-h
Print the usage, help and version for this h2xs and
exit.
-k
For function arguments declared as const, omit the
const attribute in the generated XS code.
-m
Experimental: for each variable declared in a header file,
declare a Perl variable of the same name tied to the C
variable.
-nmodule_name
Specifies a name to be used for the extension; for example:
-n RPC::DCE
-oregular_expression
Use "opaque" data type for the C types matched by the regular
expression, even if these types are typedef-equivalent to types
from typemaps. Should not be used without -x.
This can be useful because, for example, types that are
typedef-equivalent to integers can represent operating
system-related handles, and you might want to work with these
handles in OO-way, as in: $handle->do_something()
Use -o . if you want to handle all the defined types as
opaque types.
The type-to-match is whitewashed (except for commas, which have
no white space before them, and multiple asterisks (*) which
have no white space between them).
-pprefix
Specify a prefix that should be removed from the Perl function
names; for example: -p sec_rgy_. This sets up the XS
PREFIX keyword and removes the prefix from functions that
are autoloaded through the constant() mechanism.
-ssub1,sub2
Create a Perl subroutine for the specified macros rather than
autoload with the constant() subroutine. These macros are
assumed to have a return type of char *, as in the
following example: -s
sec_rgy_wildcard_name,sec_rgy_wildcard_sid.
-vversion
Specify a version number for this extension. This version
number is added to the templates. The default is 0.01.
-x
Automatically generate XSUBs basing on function declarations in
the header file. The package C::Scan should be installed. If
this option is specified, the name of the header file might look
like NAME1,NAME2. In this case NAME1 is
used instead of the specified string, but XSUBs are emitted only
for the declarations included from file NAME2.
Some types of arguments and return values for functions can
result in XSUB declarations and typemap entries must be edited,
such as objects that cannot be converted from or to a pointer (like
long long), pointers to functions, and arrays. See also the
section on the LIMITATIONS of -x entry elsewhere in this
document.