diff options
Diffstat (limited to 'upstream/debian-unstable/man3/ExtUtils::Constant.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/ExtUtils::Constant.3perl | 234 |
1 files changed, 234 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/ExtUtils::Constant.3perl b/upstream/debian-unstable/man3/ExtUtils::Constant.3perl new file mode 100644 index 00000000..95a5dcd5 --- /dev/null +++ b/upstream/debian-unstable/man3/ExtUtils::Constant.3perl @@ -0,0 +1,234 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ExtUtils::Constant 3perl" +.TH ExtUtils::Constant 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +ExtUtils::Constant \- generate XS code to import C header constants +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 7 +\& use ExtUtils::Constant qw (WriteConstants); +\& WriteConstants( +\& NAME => \*(AqFoo\*(Aq, +\& NAMES => [qw(FOO BAR BAZ)], +\& ); +\& # Generates wrapper code to make the values of the constants FOO BAR BAZ +\& # available to perl +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +ExtUtils::Constant facilitates generating C and XS wrapper code to allow +perl modules to AUTOLOAD 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 +constants. +.SH USAGE +.IX Header "USAGE" +Generally one only needs to call the \f(CW\*(C`WriteConstants\*(C'\fR function, and then +.PP +.Vb 1 +\& #include "const\-c.inc" +.Ve +.PP +in the C section of \f(CW\*(C`Foo.xs\*(C'\fR +.PP +.Vb 1 +\& INCLUDE: const\-xs.inc +.Ve +.PP +in the XS section of \f(CW\*(C`Foo.xs\*(C'\fR. +.PP +For greater flexibility use \f(CWconstant_types()\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. +.PP +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 +script at compile time. +.IP IV 4 +.IX Item "IV" +signed integer, at least 32 bits. +.IP UV 4 +.IX Item "UV" +unsigned integer, the same size as \fIIV\fR +.IP NV 4 +.IX Item "NV" +floating point type, probably \f(CW\*(C`double\*(C'\fR, possibly \f(CW\*(C`long double\*(C'\fR +.IP PV 4 +.IX Item "PV" +NUL terminated string, length will be determined with \f(CW\*(C`strlen\*(C'\fR +.IP PVN 4 +.IX Item "PVN" +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 \fIPV\fR +.IP SV 4 +.IX Item "SV" +A \fBmortal\fR SV. +.IP YES 4 +.IX Item "YES" +Truth. (\f(CW\*(C`PL_sv_yes\*(C'\fR) The value is not needed (and ignored). +.IP NO 4 +.IX Item "NO" +Defined Falsehood. (\f(CW\*(C`PL_sv_no\*(C'\fR) The value is not needed (and ignored). +.IP UNDEF 4 +.IX Item "UNDEF" +\&\f(CW\*(C`undef\*(C'\fR. The value of the macro is not needed. +.SH FUNCTIONS +.IX Header "FUNCTIONS" +.IP constant_types 4 +.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 XS functions. +.IP "XS_constant PACKAGE, TYPES, XS_SUBNAME, C_SUBNAME" 4 +.IX Item "XS_constant PACKAGE, TYPES, XS_SUBNAME, C_SUBNAME" +A function to generate the XS code to implement the perl subroutine +\&\fIPACKAGE\fR::constant used by \fIPACKAGE\fR::AUTOLOAD to load constants. +This XS 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. +.Sp +\&\fITYPES\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] +.Sp +You can call the perl visible subroutine something other than \f(CW\*(C`constant\*(C'\fR if +you give the parameter \fIXS_SUBNAME\fR. The C subroutine it calls defaults to +the name of the perl visible subroutine, unless you give the parameter +\&\fIC_SUBNAME\fR. +.IP "autoload PACKAGE, VERSION, AUTOLOADER" 4 +.IX Item "autoload PACKAGE, VERSION, AUTOLOADER" +A function to generate the AUTOLOAD subroutine for the module \fIPACKAGE\fR +\&\fIVERSION\fR is the perl version the code should be backwards compatible with. +It defaults to the version of perl running the subroutine. If \fIAUTOLOADER\fR +is true, the AUTOLOAD subroutine falls back on AutoLoader::AUTOLOAD for all +names that the \fBconstant()\fR routine doesn't recognise. +.IP WriteMakefileSnippet 4 +.IX Item "WriteMakefileSnippet" +WriteMakefileSnippet ATTRIBUTE => VALUE [, ...] +.Sp +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 +(default 2). +.Sp +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 ATTRIBUTE => VALUE [, ...]" 4 +.IX Item "WriteConstants ATTRIBUTE => VALUE [, ...]" +Writes a file of C code and a file of XS code which you should \f(CW\*(C`#include\*(C'\fR +and \f(CW\*(C`INCLUDE\*(C'\fR in the C and XS sections respectively of your module's XS +code. You probably 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 +.RS 4 +.IP NAME 4 +.IX Item "NAME" +Name of the module. This must be specified +.IP DEFAULT_TYPE 4 +.IX Item "DEFAULT_TYPE" +The default type for the constants. If not specified \f(CW\*(C`IV\*(C'\fR is assumed. +.IP BREAKOUT_AT 4 +.IX Item "BREAKOUT_AT" +The names of the constants are grouped by length. Generate child subroutines +for each group with this number or more names in. +.IP NAMES 4 +.IX Item "NAMES" +An array of constants' names, either scalars containing names, or hashrefs +as detailed in "C_constant". +.IP PROXYSUBS 4 +.IX Item "PROXYSUBS" +If true, uses proxy subs. See ExtUtils::Constant::ProxySubs. +.IP C_FH 4 +.IX Item "C_FH" +A filehandle to write the C code to. If not given, then \fIC_FILE\fR is opened +for writing. +.IP C_FILE 4 +.IX Item "C_FILE" +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. +.IP XS_FH 4 +.IX Item "XS_FH" +A filehandle to write the XS code to. If not given, then \fIXS_FILE\fR is opened +for writing. +.IP XS_FILE 4 +.IX Item "XS_FILE" +The name of the file to write containing the XS code. The default is +\&\f(CW\*(C`const\-xs.inc\*(C'\fR. +.IP XS_SUBNAME 4 +.IX Item "XS_SUBNAME" +The perl visible name of the XS subroutine generated which will return the +constants. The default is \f(CW\*(C`constant\*(C'\fR. +.IP C_SUBNAME 4 +.IX Item "C_SUBNAME" +The name of the C subroutine generated which will return the constants. +The default is \fIXS_SUBNAME\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 \fIXS_SUBNAME\fR. +.RE +.RS 4 +.RE +.SH AUTHOR +.IX Header "AUTHOR" +Nicholas Clark <nick@ccl4.org> based on the code in \f(CW\*(C`h2xs\*(C'\fR by Larry Wall and +others |