=head2 Introduction
-XS is a language used to create an extension interface
-between Perl and some C library which one wishes to use with
-Perl. The XS interface is combined with the library to
-create a new library which can be linked to Perl. An B<XSUB>
-is a function in the XS language and is the core component
-of the Perl application interface.
-
-The XS compiler is called B<xsubpp>. This compiler will embed
-the constructs necessary to let an XSUB, which is really a C
-function in disguise, manipulate Perl values and creates the
-glue necessary to let Perl access the XSUB. The compiler
+XS is an interface description file format used to create an extension
+interface between Perl and C code (or a C library) which one wishes
+to use with Perl. The XS interface is combined with the library to
+create a new library which can then be either dynamically loaded
+or statically linked into perl. The XS interface description is
+written in the XS language and is the core component of the Perl
+extension interface.
+
+An B<XSUB> forms the basic unit of the XS interface. After compilation
+by the B<xsubpp> compiler, each XSUB amounts to a C function definition
+which will provide the glue between Perl calling conventions and C
+calling conventions.
+
+The glue code pulls the arguments from the Perl stack, converts these
+Perl values to the formats expected by a C function, call this C function,
+transfers the return values of the C function back to Perl.
+Return values here may be a conventional C return value or any C
+function arguments that may serve as output parameters. These return
+values may be passed back to Perl either by putting them on the
+Perl stack, or by modifying the arguments supplied from the Perl side.
+
+The above is a somewhat simplified view of what really happens. Since
+Perl allows more flexible calling conventions than C, XSUBs may do much
+more in practice, such as checking input parameters for validity,
+throwing exceptions (or returning undef/empty list) if the return value
+from the C function indicates failure, calling different C functions
+based on numbers and types of the arguments, providing an object-oriented
+interface, etc.
+
+Of course, one could write such glue code directly in C. However, this
+would be a tedious task, especially if one needs to write glue for
+multiple C functions, and/or one is not familiar enough with the Perl
+stack discipline and other such arcana. XS comes to the rescue here:
+instead of writing this glue C code in long-hand, one can write
+a more concise short-hand I<description> of what should be done by
+the glue, and let the XS compiler B<xsubpp> handle the rest.
+
+The XS language allows one to describe the mapping between how the C
+routine is used, and how the corresponding Perl routine is used. It
+also allows creation of Perl routines which are directly translated to
+C code and which are not related to a pre-existing C function. In cases
+when the C interface coincides with the Perl interface, the XSUB
+declaration is almost identical to a declaration of a C function (in K&R
+style). In such circumstances, there is another tool called C<h2xs>
+that is able to translate an entire C header file into a corresponding
+XS file that will provide glue to the functions/macros described in
+the header file.
+
+The XS compiler is called B<xsubpp>. This compiler creates
+the constructs necessary to let an XSUB manipulate Perl values, and
+creates the glue necessary to let Perl call the XSUB. The compiler
uses B<typemaps> to determine how to map C function parameters
-and variables to Perl values. The default typemap handles
-many common C types. A supplement typemap must be created
-to handle special structures and types for the library being
-linked.
+and output values to Perl values and back. The default typemap
+(which comes with Perl) handles many common C types. A supplementary
+typemap may also be needed to handle any special structures and types
+for the library being linked.
+
+A file in XS format starts with a C language section which goes until the
+first C<MODULE =Z<>> directive. Other XS directives and XSUB definitions
+may follow this line. The "language" used in this part of the file
+is usually referred to as the XS language. B<xsubpp> recognizes and
+skips POD (see L<perlpod>) in both the C and XS language sections, which
+allows the XS file to contain embedded documentation.
See L<perlxstut> for a tutorial on the whole extension creation process.
-Note: For many extensions, Dave Beazley's SWIG system provides a
-significantly more convenient mechanism for creating the XS glue
-code. See L<http://www.cs.utah.edu/~beazley/SWIG> for more
-information.
+Note: For some extensions, Dave Beazley's SWIG system may provide a
+significantly more convenient mechanism for creating the extension
+glue code. See http://www.swig.org/ for more information.
=head2 On The Road
rpcb_gettime(host,timep)
char *host
time_t &timep
- OUTPUT:
+ OUTPUT:
timep
Any extension to Perl, including those containing XSUBs,
=head2 The Anatomy of an XSUB
+The simplest XSUBs consist of 3 parts: a description of the return
+value, the name of the XSUB routine and the names of its arguments,
+and a description of types or formats of the arguments.
+
The following XSUB allows a Perl program to access a C library function
called sin(). The XSUB will imitate the C function which takes a single
argument and returns a single value.
sin(x)
double x
-When using C pointers the indirection operator C<*> should be considered
-part of the type and the address operator C<&> should be considered part of
-the variable, as is demonstrated in the rpcb_gettime() function above. See
-the section on typemaps for more about handling qualifiers and unary
-operators in C types.
+Optionally, one can merge the description of types and the list of
+argument names, rewriting this as
+
+ double
+ sin(double x)
+
+This makes this XSUB look similar to an ANSI C declaration. An optional
+semicolon is allowed after the argument list, as in
+
+ double
+ sin(double x);
+
+Parameters with C pointer types can have different semantic: C functions
+with similar declarations
+
+ bool string_looks_as_a_number(char *s);
+ bool make_char_uppercase(char *c);
+
+are used in absolutely incompatible manner. Parameters to these functions
+could be described B<xsubpp> like this:
+
+ char * s
+ char &c
+
+Both these XS declarations correspond to the C<char*> C type, but they have
+different semantics, see L<"The & Unary Operator">.
+
+It is convenient to think that the indirection operator
+C<*> should be considered as a part of the type and the address operator C<&>
+should be considered part of the variable. See L<"The Typemap">
+for more info about handling qualifiers and unary operators in C types.
The function name and the return type must be placed on
-separate lines.
+separate lines and should be flush left-adjusted.
INCORRECT CORRECT
double x sin(x)
double x
-The function body may be indented or left-adjusted. The following example
-shows a function with its body left-adjusted. Most examples in this
-document will indent the body.
+The rest of the function description may be indented or left-adjusted. The
+following example shows a function with its body left-adjusted. Most
+examples in this document will indent the body for better readability.
CORRECT
sin(x)
double x
+More complicated XSUBs may contain many other sections. Each section of
+an XSUB starts with the corresponding keyword, such as INIT: or CLEANUP:.
+However, the first two lines of an XSUB always contain the same data:
+descriptions of the return type and the names of the function and its
+parameters. Whatever immediately follows these is considered to be
+an INPUT: section unless explicitly marked with another keyword.
+(See L<The INPUT: Keyword>.)
+
+An XSUB section continues until another section-start keyword is found.
+
=head2 The Argument Stack
-The argument stack is used to store the values which are
+The Perl argument stack is used to store the values which are
sent as parameters to the XSUB and to store the XSUB's
-return value. In reality all Perl functions keep their
-values on this stack at the same time, each limited to its
-own range of positions on the stack. In this document the
+return value(s). In reality all Perl functions (including non-XSUB
+ones) keep their values on this stack all the same time, each limited
+to its own range of positions on the stack. In this document the
first position on that stack which belongs to the active
function will be referred to as position 0 for that function.
=head2 The RETVAL Variable
-The RETVAL variable is a magic variable which always matches
-the return type of the C library function. The B<xsubpp> compiler will
-supply this variable in each XSUB and by default will use it to hold the
-return value of the C library function being called. In simple cases the
-value of RETVAL will be placed in ST(0) of the argument stack where it can
-be received by Perl as the return value of the XSUB.
+The RETVAL variable is a special C variable that is declared automatically
+for you. The C type of RETVAL matches the return type of the C library
+function. The B<xsubpp> compiler will declare this variable in each XSUB
+with non-C<void> return type. By default the generated C function
+will use RETVAL to hold the return value of the C library function being
+called. In simple cases the value of RETVAL will be placed in ST(0) of
+the argument stack where it can be received by Perl as the return value
+of the XSUB.
If the XSUB has a return type of C<void> then the compiler will
-not supply a RETVAL variable for that function. When using
-the PPCODE: directive the RETVAL variable is not needed, unless used
-explicitly.
+not declare a RETVAL variable for that function. When using
+a PPCODE: section no manipulation of the RETVAL variable is required, the
+section may use direct stack manipulation to place output values on the stack.
If PPCODE: directive is not used, C<void> return value should be used
only for subroutines which do not return a value, I<even if> CODE:
=head2 The MODULE Keyword
-The MODULE keyword is used to start the XS code and to
-specify the package of the functions which are being
-defined. All text preceding the first MODULE keyword is
-considered C code and is passed through to the output
-untouched. Every XS module will have a bootstrap function
-which is used to hook the XSUBs into Perl. The package name
-of this bootstrap function will match the value of the last
-MODULE statement in the XS source files. The value of
-MODULE should always remain constant within the same XS
-file, though this is not required.
+The MODULE keyword is used to start the XS code and to specify the package
+of the functions which are being defined. All text preceding the first
+MODULE keyword is considered C code and is passed through to the output with
+POD stripped, but otherwise untouched. Every XS module will have a
+bootstrap function which is used to hook the XSUBs into Perl. The package
+name of this bootstrap function will match the value of the last MODULE
+statement in the XS source files. The value of MODULE should always remain
+constant within the same XS file, though this is not required.
The following example will start the XS code and will place
all functions in a package named RPC.
[ XS code in package RPC ]
+The same package name can be used more than once, allowing for
+non-contiguous code. This is useful if you have a stronger ordering
+principle than package names.
+
Although this keyword is optional and in some cases provides redundant
information it should always be used. This keyword will ensure that the
XSUBs appear in the desired package.
The OUTPUT: keyword indicates that certain function parameters should be
updated (new values made visible to Perl) when the XSUB terminates or that
certain values should be returned to the calling Perl function. For
-simple functions, such as the sin() function above, the RETVAL variable is
-automatically designated as an output value. In more complex functions
+simple functions which have no CODE: or PPCODE: section,
+such as the sin() function above, the RETVAL variable is
+automatically designated as an output value. For more complex functions
the B<xsubpp> compiler will need help to determine which variables are output
variables.
rpcb_gettime(host,timep)
char *host
time_t &timep
- OUTPUT:
+ OUTPUT:
timep
The OUTPUT: keyword will also allow an output parameter to
rpcb_gettime(host,timep)
char *host
time_t &timep
- OUTPUT:
+ OUTPUT:
timep sv_setnv(ST(1), (double)timep);
B<xsubpp> emits an automatic C<SvSETMAGIC()> for all parameters in the
remainder of the OUTPUT section. See L<perlguts> for more details
about 'set' magic.
+=head2 The NO_OUTPUT Keyword
+
+The NO_OUTPUT can be placed as the first token of the XSUB. This keyword
+indicates that while the C subroutine we provide an interface to has
+a non-C<void> return type, the return value of this C subroutine should not
+be returned from the generated Perl subroutine.
+
+With this keyword present L<The RETVAL Variable> is created, and in the
+generated call to the subroutine this variable is assigned to, but the value
+of this variable is not going to be used in the auto-generated code.
+
+This keyword makes sense only if C<RETVAL> is going to be accessed by the
+user-supplied code. It is especially useful to make a function interface
+more Perl-like, especially when the C return value is just an error condition
+indicator. For example,
+
+ NO_OUTPUT int
+ delete_file(char *name)
+ POSTCALL:
+ if (RETVAL != 0)
+ croak("Error %d while deleting file '%s'", RETVAL, name);
+
+Here the generated XS function returns nothing on success, and will die()
+with a meaningful error message on error.
+
=head2 The CODE: Keyword
This keyword is used in more complicated XSUBs which require
special handling for the C function. The RETVAL variable is
-available but will not be returned unless it is specified
-under the OUTPUT: keyword.
+still declared, but it will not be returned unless it is specified
+in the OUTPUT: section.
The following XSUB is for a C function which requires special handling of
its parameters. The Perl usage is given first.
rpcb_gettime(host,timep)
char *host
time_t timep
- CODE:
+ CODE:
RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ OUTPUT:
timep
RETVAL
rpcb_gettime(host,timep)
char *host
time_t &timep
- INIT:
+ INIT:
printf("# Host is %s\n", host );
- OUTPUT:
+ OUTPUT:
timep
+Another use for the INIT: section is to check for preconditions before
+making a call to the C function:
+
+ long long
+ lldiv(a,b)
+ long long a
+ long long b
+ INIT:
+ if (a == 0 && b == 0)
+ XSRETURN_UNDEF;
+ if (b == 0)
+ croak("lldiv: cannot divide by 0");
+
=head2 The NO_INIT Keyword
The NO_INIT keyword is used to indicate that a function
rpcb_gettime(host,timep)
char *host
time_t &timep = NO_INIT
- OUTPUT:
+ OUTPUT:
timep
=head2 Initializing Function Parameters
-Function parameters are normally initialized with their
-values from the argument stack. The typemaps contain the
-code segments which are used to transfer the Perl values to
+C function parameters are normally initialized with their values from
+the argument stack (which in turn contains the parameters that were
+passed to the XSUB from Perl). The typemaps contain the
+code segments which are used to translate the Perl values to
the C parameters. The programmer, however, is allowed to
override the typemaps and supply alternate (or additional)
-initialization code.
+initialization code. Initialization code starts with the first
+C<=>, C<;> or C<+> on a line in the INPUT: section. The only
+exception happens if this C<;> terminates the line, then this C<;>
+is quietly ignored.
The following code demonstrates how to supply initialization code for
function parameters. The initialization code is eval'd within double
rpcb_gettime(host,timep)
char *host = (char *)SvPV($arg,PL_na);
time_t &timep = 0;
- OUTPUT:
+ OUTPUT:
timep
This should not be used to supply default values for parameters. One
another library function before it can be used. Default parameters are
covered in the next section.
-If the initialization begins with C<=>, then it is output on
-the same line where the input variable is declared. If the
-initialization begins with C<;> or C<+>, then it is output after
-all of the input variables have been declared. The C<=> and C<;>
-cases replace the initialization normally supplied from the typemap.
-For the C<+> case, the initialization from the typemap will precede
-the initialization code included after the C<+>. A global
+If the initialization begins with C<=>, then it is output in
+the declaration for the input variable, replacing the initialization
+supplied by the typemap. If the initialization
+begins with C<;> or C<+>, then it is performed after
+all of the input variables have been declared. In the C<;>
+case the initialization normally supplied by the typemap is not performed.
+For the C<+> case, the declaration for the variable will include the
+initialization from the typemap. A global
variable, C<%v>, is available for the truly rare case where
information from one initialization is needed in another
initialization.
+Here's a truly obscure example:
+
bool_t
rpcb_gettime(host,timep)
- time_t &timep ; /*\$v{time}=@{[$v{time}=$arg]}*/
- char *host + SvOK($v{time}) ? SvPV($arg,PL_na) : NULL;
- OUTPUT:
+ time_t &timep ; /* \$v{timep}=@{[$v{timep}=$arg]} */
+ char *host + SvOK($v{timep}) ? SvPV($arg,PL_na) : NULL;
+ OUTPUT:
timep
+The construct C<\$v{timep}=@{[$v{timep}=$arg]}> used in the above
+example has a two-fold purpose: first, when this line is processed by
+B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated. Second,
+the text of the evaluated snippet is output into the generated C file
+(inside a C comment)! During the processing of C<char *host> line,
+$arg will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
+C<ST(1)>.
+
=head2 Default Parameter Values
-Default values can be specified for function parameters by
-placing an assignment statement in the parameter list. The
-default value may be a number or a string. Defaults should
+Default values for XSUB arguments can be specified by placing an
+assignment statement in the parameter list. The default value may
+be a number, a string or the special string C<NO_INIT>. Defaults should
always be used on the right-most parameters only.
To allow the XSUB for rpcb_gettime() to have a default host
value the parameters to the XSUB could be rearranged. The
XSUB will then call the real rpcb_gettime() function with
-the parameters in the correct order. Perl will call this
-XSUB with either of the following statements.
+the parameters in the correct order. This XSUB can be called
+from Perl with either of the following statements:
$status = rpcb_gettime( $timep, $host );
rpcb_gettime(timep,host="localhost")
char *host
time_t timep = NO_INIT
- CODE:
+ CODE:
RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ OUTPUT:
timep
RETVAL
=head2 The PREINIT: Keyword
-The PREINIT: keyword allows extra variables to be declared before the
-typemaps are expanded. If a variable is declared in a CODE: block then that
-variable will follow any typemap code. This may result in a C syntax
-error. To force the variable to be declared before the typemap code, place
-it into a PREINIT: block. The PREINIT: keyword may be used one or more
-times within an XSUB.
+The PREINIT: keyword allows extra variables to be declared immediately
+before or after the declarations of the parameters from the INPUT: section
+are emitted.
+
+If a variable is declared inside a CODE: section it will follow any typemap
+code that is emitted for the input parameters. This may result in the
+declaration ending up after C code, which is C syntax error. Similar
+errors may happen with an explicit C<;>-type or C<+>-type initialization of
+parameters is used (see L<"Initializing Function Parameters">). Declaring
+these variables in an INIT: section will not help.
+
+In such cases, to force an additional variable to be declared together
+with declarations of other variables, place the declaration into a
+PREINIT: section. The PREINIT: keyword may be used one or more times
+within an XSUB.
The following examples are equivalent, but if the code is using complex
typemaps then the first example is safer.
bool_t
rpcb_gettime(timep)
time_t timep = NO_INIT
- PREINIT:
+ PREINIT:
char *host = "localhost";
- CODE:
+ CODE:
RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ OUTPUT:
timep
RETVAL
-A correct, but error-prone example.
+For this particular case an INIT: keyword would generate the
+same C code as the PREINIT: keyword. Another correct, but error-prone example:
bool_t
rpcb_gettime(timep)
time_t timep = NO_INIT
- CODE:
+ CODE:
char *host = "localhost";
RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ OUTPUT:
+ timep
+ RETVAL
+
+Another way to declare C<host> is to use a C block in the CODE: section:
+
+ bool_t
+ rpcb_gettime(timep)
+ time_t timep = NO_INIT
+ CODE:
+ {
+ char *host = "localhost";
+ RETVAL = rpcb_gettime( host, &timep );
+ }
+ OUTPUT:
+ timep
+ RETVAL
+
+The ability to put additional declarations before the typemap entries are
+processed is very handy in the cases when typemap conversions manipulate
+some global state:
+
+ MyObject
+ mutate(o)
+ PREINIT:
+ MyState st = global_state;
+ INPUT:
+ MyObject o;
+ CLEANUP:
+ reset_to(global_state, st);
+
+Here we suppose that conversion to C<MyObject> in the INPUT: section and from
+MyObject when processing RETVAL will modify a global variable C<global_state>.
+After these conversions are performed, we restore the old value of
+C<global_state> (to avoid memory leaks, for example).
+
+There is another way to trade clarity for compactness: INPUT sections allow
+declaration of C variables which do not appear in the parameter list of
+a subroutine. Thus the above code for mutate() can be rewritten as
+
+ MyObject
+ mutate(o)
+ MyState st = global_state;
+ MyObject o;
+ CLEANUP:
+ reset_to(global_state, st);
+
+and the code for rpcb_gettime() can be rewritten as
+
+ bool_t
+ rpcb_gettime(timep)
+ time_t timep = NO_INIT
+ char *host = "localhost";
+ C_ARGS:
+ host, &timep
+ OUTPUT:
timep
RETVAL
enabled, the XSUB will invoke ENTER and LEAVE automatically.
To support potentially complex type mappings, if a typemap entry used
-by this XSUB contains a comment like C</*scope*/> then scoping will
-automatically be enabled for that XSUB.
+by an XSUB contains a comment like C</*scope*/> then scoping will
+be automatically enabled for that XSUB.
To enable scoping:
bool_t
rpcb_gettime(host,timep)
char *host
- PREINIT:
+ PREINIT:
time_t tt;
- INPUT:
+ INPUT:
time_t timep
- CODE:
+ CODE:
RETVAL = rpcb_gettime( host, &tt );
timep = tt;
- OUTPUT:
+ OUTPUT:
timep
RETVAL
bool_t
rpcb_gettime(host,timep)
- PREINIT:
+ PREINIT:
time_t tt;
- INPUT:
+ INPUT:
char *host
- PREINIT:
+ PREINIT:
char *h;
- INPUT:
+ INPUT:
time_t timep
- CODE:
+ CODE:
h = host;
RETVAL = rpcb_gettime( h, &tt );
timep = tt;
- OUTPUT:
+ OUTPUT:
+ timep
+ RETVAL
+
+Since INPUT sections allow declaration of C variables which do not appear
+in the parameter list of a subroutine, this may be shortened to:
+
+ bool_t
+ rpcb_gettime(host,timep)
+ time_t tt;
+ char *host;
+ char *h = host;
+ time_t timep;
+ CODE:
+ RETVAL = rpcb_gettime( h, &tt );
+ timep = tt;
+ OUTPUT:
timep
RETVAL
+(We used our knowledge that input conversion for C<char *> is a "simple" one,
+thus C<host> is initialized on the declaration line, and our assignment
+C<h = host> is not performed too early. Otherwise one would need to have the
+assignment C<h = host> in a CODE: or INIT: section.)
+
+=head2 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
+
+In the list of parameters for an XSUB, one can precede parameter names
+by the C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> keywords.
+C<IN> keyword is the default, the other keywords indicate how the Perl
+interface should differ from the C interface.
+
+Parameters preceded by C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT>
+keywords are considered to be used by the C subroutine I<via
+pointers>. C<OUTLIST>/C<OUT> keywords indicate that the C subroutine
+does not inspect the memory pointed by this parameter, but will write
+through this pointer to provide additional return values.
+
+Parameters preceded by C<OUTLIST> keyword do not appear in the usage
+signature of the generated Perl function.
+
+Parameters preceded by C<IN_OUTLIST>/C<IN_OUT>/C<OUT> I<do> appear as
+parameters to the Perl function. With the exception of
+C<OUT>-parameters, these parameters are converted to the corresponding
+C type, then pointers to these data are given as arguments to the C
+function. It is expected that the C function will write through these
+pointers.
+
+The return list of the generated Perl function consists of the C return value
+from the function (unless the XSUB is of C<void> return type or
+C<The NO_OUTPUT Keyword> was used) followed by all the C<OUTLIST>
+and C<IN_OUTLIST> parameters (in the order of appearance). On the
+return from the XSUB the C<IN_OUT>/C<OUT> Perl parameter will be
+modified to have the values written by the C function.
+
+For example, an XSUB
+
+ void
+ day_month(OUTLIST day, IN unix_time, OUTLIST month)
+ int day
+ int unix_time
+ int month
+
+should be used from Perl as
+
+ my ($day, $month) = day_month(time);
+
+The C signature of the corresponding function should be
+
+ void day_month(int *day, int unix_time, int *month);
+
+The C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<IN_OUT>/C<OUT> keywords can be
+mixed with ANSI-style declarations, as in
+
+ void
+ day_month(OUTLIST int day, int unix_time, OUTLIST int month)
+
+(here the optional C<IN> keyword is omitted).
+
+The C<IN_OUT> parameters are identical with parameters introduced with
+L<The & Unary Operator> and put into the C<OUTPUT:> section (see
+L<The OUTPUT: Keyword>). The C<IN_OUTLIST> parameters are very similar,
+the only difference being that the value C function writes through the
+pointer would not modify the Perl parameter, but is put in the output
+list.
+
+The C<OUTLIST>/C<OUT> parameter differ from C<IN_OUTLIST>/C<IN_OUT>
+parameters only by the initial value of the Perl parameter not
+being read (and not being given to the C function - which gets some
+garbage instead). For example, the same C function as above can be
+interfaced with as
+
+ void day_month(OUT int day, int unix_time, OUT int month);
+
+or
+
+ void
+ day_month(day, unix_time, month)
+ int &day = NO_INIT
+ int unix_time
+ int &month = NO_INIT
+ OUTPUT:
+ day
+ month
+
+However, the generated Perl function is called in very C-ish style:
+
+ my ($day, $month);
+ day_month($day, time, $month);
+
+=head2 The C<length(NAME)> Keyword
+
+If one of the input arguments to the C function is the length of a string
+argument C<NAME>, one can substitute the name of the length-argument by
+C<length(NAME)> in the XSUB declaration. This argument must be omited when
+the generated Perl function is called. E.g.,
+
+ void
+ dump_chars(char *s, short l)
+ {
+ short n = 0;
+ while (n < l) {
+ printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);
+ n++;
+ }
+ }
+
+ MODULE = x PACKAGE = x
+
+ void dump_chars(char *s, short length(s))
+
+should be called as C<dump_chars($string)>.
+
+This directive is supported with ANSI-type function declarations only.
+
=head2 Variable-length Parameter Lists
XSUBs can have variable-length parameter lists by specifying an ellipsis
bool_t
rpcb_gettime(timep, ...)
time_t timep = NO_INIT
- PREINIT:
+ PREINIT:
char *host = "localhost";
STRLEN n_a;
- CODE:
- if( items > 1 )
- host = (char *)SvPV(ST(1), n_a);
- RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ CODE:
+ if( items > 1 )
+ host = (char *)SvPV(ST(1), n_a);
+ RETVAL = rpcb_gettime( host, &timep );
+ OUTPUT:
timep
RETVAL
The C_ARGS: keyword allows creating of XSUBS which have different
calling sequence from Perl than from C, without a need to write
-CODE: or CPPCODE: section. The contents of the C_ARGS: paragraph is
+CODE: or PPCODE: section. The contents of the C_ARGS: paragraph is
put as the argument to the called C function without any change.
-For example, suppose that C function is declared as
+For example, suppose that a C function is declared as
symbolic nth_derivative(int n, symbolic function, int flags);
nth_derivative(function, n)
symbolic function
int n
- C_ARGS:
+ C_ARGS:
n, function, default_flags
=head2 The PPCODE: Keyword
control the argument stack for the XSUBs return values. Occasionally one
will want an XSUB to return a list of values rather than a single value.
In these cases one must use PPCODE: and then explicitly push the list of
-values on the stack. The PPCODE: and CODE: keywords are not used
+values on the stack. The PPCODE: and CODE: keywords should not be used
together within the same XSUB.
+The actual difference between PPCODE: and CODE: sections is in the
+initialization of C<SP> macro (which stands for the I<current> Perl
+stack pointer), and in the handling of data on the stack when returning
+from an XSUB. In CODE: sections SP preserves the value which was on
+entry to the XSUB: SP is on the function pointer (which follows the
+last parameter). In PPCODE: sections SP is moved backward to the
+beginning of the parameter list, which allows C<PUSH*()> macros
+to place output values in the place Perl expects them to be when
+the XSUB returns back to Perl.
+
+The generated trailer for a CODE: section ensures that the number of return
+values Perl will see is either 0 or 1 (depending on the C<void>ness of the
+return value of the C function, and heuristics mentioned in
+L<"The RETVAL Variable">). The trailer generated for a PPCODE: section
+is based on the number of return values and on the number of times
+C<SP> was updated by C<[X]PUSH*()> macros.
+
+Note that macros C<ST(i)>, C<XST_m*()> and C<XSRETURN*()> work equally
+well in CODE: sections and PPCODE: sections.
+
The following XSUB will call the C rpcb_gettime() function
and will return its two output values, timep and status, to
Perl as a single list.
void
rpcb_gettime(host)
char *host
- PREINIT:
+ PREINIT:
time_t timep;
bool_t status;
- PPCODE:
+ PPCODE:
status = rpcb_gettime( host, &timep );
EXTEND(SP, 2);
PUSHs(sv_2mortal(newSViv(status)));
SV *
rpcb_gettime(host)
char * host
- PREINIT:
+ PREINIT:
time_t timep;
bool_t x;
- CODE:
+ CODE:
ST(0) = sv_newmortal();
if( rpcb_gettime( host, &timep ) )
sv_setnv( ST(0), (double)timep);
SV *
rpcb_gettime(host)
char * host
- PREINIT:
+ PREINIT:
time_t timep;
bool_t x;
- CODE:
+ CODE:
ST(0) = sv_newmortal();
if( rpcb_gettime( host, &timep ) ){
sv_setnv( ST(0), (double)timep);
void
rpcb_gettime(host)
char *host
- PREINIT:
+ PREINIT:
time_t timep;
- PPCODE:
+ PPCODE:
if( rpcb_gettime( host, &timep ) )
PUSHs(sv_2mortal(newSViv(timep)));
else{
- /* Nothing pushed on stack, so an empty */
- /* list is implicitly returned. */
+ /* Nothing pushed on stack, so an empty
+ * list is implicitly returned. */
}
Some people may be inclined to include an explicit C<return> in the above
the XSUB stack is properly adjusted. Consult L<perlguts/"API LISTING"> for
other C<XSRETURN> macros.
+Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
+rewrite this example as:
+
+ int
+ rpcb_gettime(host)
+ char *host
+ PREINIT:
+ time_t timep;
+ CODE:
+ RETVAL = rpcb_gettime( host, &timep );
+ if (RETVAL == 0)
+ XSRETURN_UNDEF;
+ OUTPUT:
+ RETVAL
+
+In fact, one can put this check into a POSTCALL: section as well. Together
+with PREINIT: simplifications, this leads to:
+
+ int
+ rpcb_gettime(host)
+ char *host
+ time_t timep;
+ POSTCALL:
+ if (RETVAL == 0)
+ XSRETURN_UNDEF;
+
=head2 The REQUIRE: Keyword
The REQUIRE: keyword is used to indicate the minimum version of the
code specified for the cleanup block will be added as the last statements
in the XSUB.
+=head2 The POSTCALL: Keyword
+
+This keyword can be used when an XSUB requires special procedures
+executed after the C subroutine call is performed. When the POSTCALL:
+keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
+present in the XSUB.
+
+See examples in L<"The NO_OUTPUT Keyword"> and L<"Returning Undef And Empty Lists">.
+
+The POSTCALL: block does not make a lot of sense when the C subroutine
+call is supplied by user by providing either CODE: or PPCODE: section.
+
=head2 The BOOT: Keyword
The BOOT: keyword is used to add code to the extension's bootstrap
bool_t
rpcb_gettime(timep, ...)
time_t timep = NO_INIT
- PROTOTYPE: $;$
- PREINIT:
+ PROTOTYPE: $;$
+ PREINIT:
char *host = "localhost";
STRLEN n_a;
- CODE:
+ CODE:
if( items > 1 )
host = (char *)SvPV(ST(1), n_a);
RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
+ OUTPUT:
timep
RETVAL
+If the prototypes are enabled, you can disable it locally for a given
+XSUB as in the following example:
+
+ void
+ rpcb_gettime_noproto()
+ PROTOTYPE: DISABLE
+ ...
+
=head2 The ALIAS: Keyword
The ALIAS: keyword allows an XSUB to have two or more unique Perl names
rpcb_gettime(host,timep)
char *host
time_t &timep
- ALIAS:
+ ALIAS:
FOO::gettime = 1
BAR::getit = 2
- INIT:
+ INIT:
printf("# ix = %d\n", ix );
- OUTPUT:
+ OUTPUT:
timep
+=head2 The OVERLOAD: Keyword
+
+Instead of writing an overloaded interface using pure Perl, you
+can also use the OVERLOAD keyword to define additional Perl names
+for your functions (like the ALIAS: keyword above). However, the
+overloaded functions must be defined with three parameters (except
+for the nomethod() function which needs four parameters). If any
+function has the OVERLOAD: keyword, several additional lines
+will be defined in the c file generated by xsubpp in order to
+register with the overload magic.
+
+Since blessed objects are actually stored as RV's, it is useful
+to use the typemap features to preprocess parameters and extract
+the actual SV stored within the blessed RV. See the sample for
+T_PTROBJ_SPECIAL below.
+
+To use the OVERLOAD: keyword, create an XS function which takes
+three input parameters ( or use the c style '...' definition) like
+this:
+
+ SV *
+ cmp (lobj, robj, swap)
+ My_Module_obj lobj
+ My_Module_obj robj
+ IV swap
+ OVERLOAD: cmp <=>
+ { /* function defined here */}
+
+In this case, the function will overload both of the three way
+comparison operators. For all overload operations using non-alpha
+characters, you must type the parameter without quoting, seperating
+multiple overloads with whitespace. Note that "" (the stringify
+overload) should be entered as \"\" (i.e. escaped).
+
+=head2 The FALLBACK: Keyword
+
+In addition to the OVERLOAD keyword, if you need to control how
+Perl autogenerates missing overloaded operators, you can set the
+FALLBACK keyword in the module header section, like this:
+
+ MODULE = RPC PACKAGE = RPC
+
+ FALLBACK: TRUE
+ ...
+
+where FALLBACK can take any of the three values TRUE, FALSE, or
+UNDEF. If you do not set any FALLBACK value when using OVERLOAD,
+it defaults to UNDEF. FALLBACK is not used except when one or
+more functions using OVERLOAD have been defined. Please see
+L<overload/Fallback> for more details.
+
=head2 The INTERFACE: Keyword
This keyword declares the current XSUB as a keeper of the given
calling signature. If some text follows this keyword, it is
considered as a list of functions which have this signature, and
-should be attached to XSUBs.
+should be attached to the current XSUB.
-Say, if you have 4 functions multiply(), divide(), add(), subtract() all
-having the signature
+For example, if you have 4 C functions multiply(), divide(), add(),
+subtract() all having the signature:
symbolic f(symbolic, symbolic);
-you code them all by using XSUB
+you can make them all to use the same XSUB using this:
symbolic
interface_s_ss(arg1, arg2)
multiply divide
add subtract
-The advantage of this approach comparing to ALIAS: keyword is that one
+(This is the complete XSUB code for 4 Perl functions!) Four generated
+Perl function share names with corresponding C functions.
+
+The advantage of this approach comparing to ALIAS: keyword is that there
+is no need to code a switch statement, each Perl function (which shares
+the same XSUB) knows which C function it should call. Additionally, one
can attach an extra function remainder() at runtime by using
-
+
CV *mycv = newXSproto("Symbolic::remainder",
XS_Symbolic_interface_s_ss, __FILE__, "$$");
XSINTERFACE_FUNC_SET(mycv, remainder);
-(This example supposes that there was no INTERFACE_MACRO: section,
-otherwise one needs to use something else instead of
-C<XSINTERFACE_FUNC_SET>.)
+say, from another XSUB. (This example supposes that there was no
+INTERFACE_MACRO: section, otherwise one needs to use something else instead of
+C<XSINTERFACE_FUNC_SET>, see the next section.)
=head2 The INTERFACE_MACRO: Keyword
interface_s_ss(arg1, arg2)
symbolic arg1
symbolic arg2
- INTERFACE_MACRO:
+ INTERFACE_MACRO:
XSINTERFACE_FUNC_BYOFFSET
XSINTERFACE_FUNC_BYOFFSET_set
- INTERFACE:
+ INTERFACE:
multiply divide
add subtract
rpcb_gettime(host,timep)
char *host
time_t &timep
- OUTPUT:
+ OUTPUT:
timep
The XS module can use INCLUDE: to pull that file into it.
long
rpcb_gettime(a,b)
CASE: ix == 1
- ALIAS:
+ ALIAS:
x_gettime = 1
- INPUT:
+ INPUT:
# 'a' is timep, 'b' is host
char *b
time_t a = NO_INIT
- CODE:
+ CODE:
RETVAL = rpcb_gettime( b, &a );
- OUTPUT:
+ OUTPUT:
a
RETVAL
CASE:
# 'a' is host, 'b' is timep
char *a
time_t &b = NO_INIT
- OUTPUT:
+ OUTPUT:
b
RETVAL
=head2 The & Unary Operator
-The & unary operator is used to tell the compiler that it should dereference
-the object when it calls the C function. This is used when a CODE: block is
-not used and the object is a not a pointer type (the object is an C<int> or
-C<long> but not a C<int*> or C<long*>).
+The C<&> unary operator in the INPUT: section is used to tell B<xsubpp>
+that it should convert a Perl value to/from C using the C type to the left
+of C<&>, but provide a pointer to this value when the C function is called.
+
+This is useful to avoid a CODE: block for a C function which takes a parameter
+by reference. Typically, the parameter should be not a pointer type (an
+C<int> or C<long> but not an C<int*> or C<long*>).
-The following XSUB will generate incorrect C code. The xsubpp compiler will
+The following XSUB will generate incorrect C code. The B<xsubpp> compiler will
turn this into code which calls C<rpcb_gettime()> with parameters C<(char
*host, time_t timep)>, but the real C<rpcb_gettime()> wants the C<timep>
parameter to be of type C<time_t*> rather than C<time_t>.
rpcb_gettime(host,timep)
char *host
time_t timep
- OUTPUT:
+ OUTPUT:
timep
-That problem is corrected by using the C<&> operator. The xsubpp compiler
+That problem is corrected by using the C<&> operator. The B<xsubpp> compiler
will now turn this into code which calls C<rpcb_gettime()> correctly with
parameters C<(char *host, time_t *timep)>. It does this by carrying the
C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>.
rpcb_gettime(host,timep)
char *host
time_t &timep
- OUTPUT:
+ OUTPUT:
timep
-=head2 Inserting Comments and C Preprocessor Directives
+=head2 Inserting POD, Comments and C Preprocessor Directives
-C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
-CODE:, PPCODE:, and CLEANUP: blocks, as well as outside the functions.
-Comments are allowed anywhere after the MODULE keyword. The compiler
-will pass the preprocessor directives through untouched and will remove
-the commented lines.
+C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:,
+PPCODE:, POSTCALL:, and CLEANUP: blocks, as well as outside the functions.
+Comments are allowed anywhere after the MODULE keyword. The compiler will
+pass the preprocessor directives through untouched and will remove the
+commented lines. POD documentation is allowed at any point, both in the
+C and XS language sections. POD must be terminated with a C<=cut> command;
+C<xsubpp> will exit with an error if it does not. It is very unlikely that
+human generated C code will be mistaken for POD, as most indenting styles
+result in whitespace in front of any line starting with C<=>. Machine
+generated XS files may fall into this trap unless care is taken to
+ensure that a space breaks the sequence "\n=".
Comments can be added to XSUBs by placing a C<#> as the first
non-whitespace of a line. Care should be taken to avoid making the
#if ... version2
#endif
-because otherwise xsubpp will believe that you made a duplicate
+because otherwise B<xsubpp> will believe that you made a duplicate
definition of the function. Also, put a blank line before the
#else/#endif so it will not be seen as part of the function body.
=head2 Using XS With C++
-If a function is defined as a C++ method then it will assume
+If an XSUB name contains C<::>, it is considered to be a C++ method.
+The generated Perl function will assume that
its first argument is an object pointer. The object pointer
will be stored in a variable called THIS. The object should
have been created by C++ with the new() function and should
blessing of the object by Perl can be handled by a typemap. An example
typemap is shown at the end of this section.
-If the method is defined as static it will call the C++
+If the return type of the XSUB includes C<static>, the method is considered
+to be a static method. It will call the C++
function using the class::method() syntax. If the method is not static
the function will be called using the THIS-E<gt>method() syntax.
color::set_blue( val )
int val
-Both functions will expect an object as the first parameter. The xsubpp
-compiler will call that object C<THIS> and will use it to call the specified
-method. So in the C++ code the blue() and set_blue() methods will be called
-in the following manner.
+Both Perl functions will expect an object as the first parameter. In the
+generated C++ code the object is called C<THIS>, and the method call will
+be performed on this object. So in the C++ code the blue() and set_blue()
+methods will be called as this:
RETVAL = THIS->blue();
THIS->set_blue( val );
+You could also write a single get/set method using an optional argument:
+
+ int
+ color::blue( val = NO_INIT )
+ int val
+ PROTOTYPE $;$
+ CODE:
+ if (items > 1)
+ THIS->set_blue( val );
+ RETVAL = THIS->blue();
+ OUTPUT:
+ RETVAL
+
If the function's name is B<DESTROY> then the C++ C<delete> function will be
-called and C<THIS> will be given as its parameter.
+called and C<THIS> will be given as its parameter. The generated C++ code for
void
color::DESTROY()
-The C++ code will call C<delete>.
+will look like this:
+
+ color *THIS = ...; // Initialized as in typemap
delete THIS;
color *
color::new()
-The C++ code will call C<new>.
+The generated C++ code will call C<new>.
- RETVAL = new color();
+ RETVAL = new color();
The following is an example of a typemap that could be used for this C++
example.
=head2 Interface Strategy
When designing an interface between Perl and a C library a straight
-translation from C to XS is often sufficient. The interface will often be
+translation from C to XS (such as created by C<h2xs -x>) is often sufficient.
+However, sometimes the interface will look
very C-like and occasionally nonintuitive, especially when the C function
-modifies one of its parameters. In cases where the programmer wishes to
+modifies one of its parameters, or returns failure inband (as in "negative
+return values mean failure"). In cases where the programmer wishes to
create a more Perl-like interface the following strategy may help to
identify the more critical parts of the interface.
-Identify the C functions which modify their parameters. The XSUBs for
-these functions may be able to return lists to Perl, or may be
-candidates to return undef or an empty list in case of failure.
+Identify the C functions with input/output or output parameters. The XSUBs for
+these functions may be able to return lists to Perl.
+
+Identify the C functions which use some inband info as an indication
+of failure. They may be
+candidates to return undef or an empty list in case of failure. If the
+failure may be detected without a call to the C function, you may want to use
+an INIT: section to report the failure. For failures detectable after the C
+function returns one may want to use a POSTCALL: section to process the
+failure. In more complicated cases use CODE: or PPCODE: sections.
+
+If many functions use the same failure indication based on the return value,
+you may want to create a special typedef to handle this situation. Put
+
+ typedef int negative_is_failure;
+
+near the beginning of XS file, and create an OUTPUT typemap entry
+for C<negative_is_failure> which converts negative values to C<undef>, or
+maybe croak()s. After this the return value of type C<negative_is_failure>
+will create more Perl-like interface.
Identify which values are used by only the C and XSUB functions
-themselves. If Perl does not need to access the contents of the value
+themselves, say, when a parameter to a function should be a contents of a
+global variable. If Perl does not need to access the contents of the value
then it may not be necessary to provide a translation for that value
from C to Perl.
Identify the pointers in the C function parameter lists and return
-values. Some pointers can be handled in XS with the & unary operator on
-the variable name while others will require the use of the * operator on
-the type name. In general it is easier to work with the & operator.
+values. Some pointers may be used to implement input/output or
+output parameters, they can be handled in XS with the C<&> unary operator,
+and, possibly, using the NO_INIT keyword.
+Some others will require handling of types like C<int *>, and one needs
+to decide what a useful Perl translation will do in such a case. When
+the semantic is clear, it is advisable to put the translation into a typemap
+file.
Identify the structures used by the C functions. In many
cases it may be helpful to use the T_PTROBJ typemap for
these structures so they can be manipulated by Perl as
-blessed objects.
+blessed objects. (This is handled automatically by C<h2xs -x>.)
+
+If the same C type is used in several different contexts which require
+different translations, C<typedef> several new types mapped to this C type,
+and create separate F<typemap> entries for these new types. Use these
+types in declarations of return type and parameters to XSUBs.
=head2 Perl Objects And C Structures
void
rpcb_DESTROY(netconf)
Netconfig *netconf
- CODE:
+ CODE:
printf("Now in NetconfigPtr::DESTROY\n");
free( netconf );
The typemap is a collection of code fragments which are used by the B<xsubpp>
compiler to map C function parameters and values to Perl values. The
-typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
-C<OUTPUT>. Any unlabelled initial section is assumed to be a C<TYPEMAP>
-section if a name is not explicitly specified. The INPUT section tells
+typemap file may consist of three sections labelled C<TYPEMAP>, C<INPUT>, and
+C<OUTPUT>. An unlabelled initial section is assumed to be a C<TYPEMAP>
+section. The INPUT section tells
the compiler how to translate Perl values
into variables of certain C types. The OUTPUT section tells the compiler
how to translate the values from certain C types into values Perl can
The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
in the first column on a line by themselves, and must be in uppercase.
-The default typemap in the C<ext> directory of the Perl source contains many
-useful types which can be used by Perl extensions. Some extensions define
-additional typemaps which they keep in their own directory. These
-additional typemaps may reference INPUT and OUTPUT maps in the main
+The default typemap in the C<lib/ExtUtils> directory of the Perl source
+contains many useful types which can be used by Perl extensions. Some
+extensions define additional typemaps which they keep in their own directory.
+These additional typemaps may reference INPUT and OUTPUT maps in the main
typemap. The B<xsubpp> compiler will allow the extension's own typemap to
override any mappings which are in the default typemap.
here. Note that the C type is separated from the XS type with a tab and
that the C unary operator C<*> is considered to be a part of the C type name.
- TYPEMAP
- Netconfig *<tab>T_PTROBJ
+ TYPEMAP
+ Netconfig *<tab>T_PTROBJ
Here's a more complicated example: suppose that you wanted C<struct
netconfig> to be blessed into the class C<Net::Config>. One way to do
on the fly, giving the desired effect. This example demonstrates some
of the power and versatility of the typemap facility.
+=head2 Safely Storing Static Data in XS
+
+Starting with Perl 5.8, a macro framework has been defined to allow
+static data to be safely stored in XS modules that will be accessed from
+a multi-threaded Perl.
+
+Although primarily designed for use with multi-threaded Perl, the macros
+have been designed so that they will work with non-threaded Perl as well.
+
+It is therefore strongly recommended that these macros be used by all
+XS modules that make use of static data.
+
+The easiest way to get a template set of macros to use is by specifying
+the C<-g> (C<--global>) option with h2xs (see L<h2xs>).
+
+Below is an example module that makes use of the macros.
+
+ #include "EXTERN.h"
+ #include "perl.h"
+ #include "XSUB.h"
+
+ /* Global Data */
+
+ #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION
+
+ typedef struct {
+ int count;
+ char name[3][100];
+ } my_cxt_t;
+
+ START_MY_CXT
+
+ MODULE = BlindMice PACKAGE = BlindMice
+
+ BOOT:
+ {
+ MY_CXT_INIT;
+ MY_CXT.count = 0;
+ strcpy(MY_CXT.name[0], "None");
+ strcpy(MY_CXT.name[1], "None");
+ strcpy(MY_CXT.name[2], "None");
+ }
+
+ int
+ newMouse(char * name)
+ char * name;
+ PREINIT:
+ dMY_CXT;
+ CODE:
+ if (MY_CXT.count >= 3) {
+ warn("Already have 3 blind mice") ;
+ RETVAL = 0;
+ }
+ else {
+ RETVAL = ++ MY_CXT.count;
+ strcpy(MY_CXT.name[MY_CXT.count - 1], name);
+ }
+
+ char *
+ get_mouse_name(index)
+ int index
+ CODE:
+ dMY_CXT;
+ RETVAL = MY_CXT.lives ++;
+ if (index > MY_CXT.count)
+ croak("There are only 3 blind mice.");
+ else
+ RETVAL = newSVpv(MY_CXT.name[index - 1]);
+
+
+B<REFERENCE>
+
+=over 5
+
+=item MY_CXT_KEY
+
+This macro is used to define a unique key to refer to the static data
+for an XS module. The suggested naming scheme, as used by h2xs, is to
+use a string that consists of the module name, the string "::_guts"
+and the module version number.
+
+ #define MY_CXT_KEY "MyModule::_guts" XS_VERSION
+
+=item typedef my_cxt_t
+
+This struct typedef I<must> always be called C<my_cxt_t> -- the other
+C<CXT*> macros assume the existence of the C<my_cxt_t> typedef name.
+
+Declare a typedef named C<my_cxt_t> that is a structure that contains
+all the data that needs to be interpreter-local.
+
+ typedef struct {
+ int some_value;
+ } my_cxt_t;
+
+=item START_MY_CXT
+
+Always place the START_MY_CXT macro directly after the declaration
+of C<my_cxt_t>.
+
+=item MY_CXT_INIT
+
+The MY_CXT_INIT macro initialises storage for the C<my_cxt_t> struct.
+
+It I<must> be called exactly once -- typically in a BOOT: section.
+
+=item dMY_CXT
+
+Use the dMY_CXT macro (a declaration) in all the functions that access
+MY_CXT.
+
+=item MY_CXT
+
+Use the MY_CXT macro to access members of the C<my_cxt_t> struct. For
+example, if C<my_cxt_t> is
+
+ typedef struct {
+ int index;
+ } my_cxt_t;
+
+then use this to access the C<index> member
+
+ dMY_CXT;
+ MY_CXT.index = 2;
+
+=back
+
=head1 EXAMPLES
File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
SV *
rpcb_gettime(host="localhost")
char *host
- PREINIT:
+ PREINIT:
time_t timep;
- CODE:
+ CODE:
ST(0) = sv_newmortal();
if( rpcb_gettime( host, &timep ) )
sv_setnv( ST(0), (double)timep );
void
rpcb_DESTROY(netconf)
Netconfig *netconf
- CODE:
+ CODE:
printf("NetconfigPtr::DESTROY\n");
free( netconf );
=head1 AUTHOR
-Dean Roehrich <F<roehrich@cray.com>>
-Jul 8, 1996
+Originally written by Dean Roehrich <F<roehrich@cray.com>>.
+
+Maintained since 1996 by The Perl Porters <F<perlbug@perl.org>>.
https://perl5.git.perl.org / perl5.git / blobdiff