Welcome to Linux Knowledge Base and Tutorial
"The place where you learn linux"
GetNetWise: You
e One Click Away

 Create an AccountHome | Submit News | Your Account  

Tutorial Menu
Linux Tutorial Home
Table of Contents

· Introduction to Operating Systems
· Linux Basics
· Working with the System
· Shells and Utilities
· Editing Files
· Basic Administration
· The Operating System
· The X Windowing System
· The Computer Itself
· Networking
· System Monitoring
· Solving Problems
· Security
· Installing and Upgrading
· Linux and Windows

Man Pages
Linux Topics
Test Your Knowledge

Site Menu
Site Map
Copyright Info
Terms of Use
Privacy Info
Masthead / Impressum
Your Account

Private Messages

News Archive
Submit News
User Articles
Web Links


The Web

Who's Online
There are currently, 328 guest(s) and 0 member(s) that are online.

You are an Anonymous user. You can register for free by clicking here





       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 inter­
       face 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 XSUB forms the basic unit of the XS interface.  After
       compilation by the 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 val­
       ues 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 sup­
       plied from the Perl side.

       The above is a somewhat simplified view of what really
       happens.  Since Perl allows more flexible calling conven­
       tions than C, XSUBs may do much more in practice, such as
       checking input parameters for validity, throwing excep­
       tions (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 description of what should be done
       by the glue, and let the XS compiler xsubpp handle the

       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 dec­
       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 "MODULE =" 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.  xsubpp recognizes and
       skips POD (see perlpod) in both the C and XS language sec­
       tions, which allows the XS file to contain embedded docu­

       See perlxstut for a tutorial on the whole extension cre­
       ation process.

       Note: For some extensions, Dave Beazley's SWIG system may
       provide a significantly more convenient mechanism for cre­
       ating the extension glue code.  See http://www.swig.org/
       for more information.

       On The Road

       Many of the examples which follow will concentrate on cre­
       ating an interface between Perl and the ONC+ RPC bind
       library functions.  The rpcb_gettime() function is used to
       demonstrate many features of the XS language.  This func­
       tion has two parameters; the first is an input parameter
       and the second is an output parameter.  The function also
       returns a status value.

               bool_t rpcb_gettime(const char *host, time_t *timep);

       From C this function will be called with the following

            #include <rpc/rpc.h>
            bool_t status;
            time_t timep;
            status = rpcb_gettime( "localhost", &timep );

       If an XSUB is created to offer a direct translation
       between this function and Perl, then this XSUB will be
       used from Perl with the following code.  The $status and
       $timep variables will contain the output of the function.

            use RPC;
            $status = rpcb_gettime( "localhost", $timep );

       The following XS file shows an XS subroutine, or XSUB,
       which demonstrates one possible interface to the rpcb_get­
       time() function.  This XSUB represents a direct transla­
       tion between C and Perl and so preserves the interface
                 char *host
                 time_t &timep

       Any extension to Perl, including those containing XSUBs,
       should have a Perl module to serve as the bootstrap which
       pulls the extension into Perl.  This module will export
       the extension's functions and variables to the Perl pro­
       gram and will cause the extension's XSUBs to be linked
       into Perl.  The following module will be used for most of
       the examples in this document and should be used from Perl
       with the "use" command as shown earlier.  Perl modules are
       explained in more detail later in this document.

            package RPC;

            require Exporter;
            require DynaLoader;
            @ISA = qw(Exporter DynaLoader);
            @EXPORT = qw( rpcb_gettime );

            bootstrap RPC;

       Throughout this document a variety of interfaces to the
       rpcb_gettime() XSUB will be explored.  The XSUBs will take
       their parameters in different orders or will take differ­
       ent numbers of parameters.  In each case the XSUB is an
       abstraction between Perl and the real C rpcb_gettime()
       function, and the XSUB must always ensure that the real
       rpcb_gettime() function is called with the correct parame­
       ters.  This abstraction will allow the programmer to cre­
       ate a more Perl-like interface to the C function.

       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 for­
       mats 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.

              double x

       Parameters with C pointer types can have different seman­
       tic: 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 xsubpp like this:

            char *  s
            char    &c

       Both these XS declarations correspond to the "char*" C
       type, but they have different semantics, see "The & Unary

       It is convenient to think that the indirection operator
       "*" should be considered as a part of the type and the
       address operator "&" should be considered part of the
       variable.  See "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 and should be flush left-adjusted.

         INCORRECT                        CORRECT

         double sin(x)                    double
           double x                       sin(x)
                                            double x

       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.


         double x

       More complicated XSUBs may contain many other sections.
       Each section of an XSUB starts with the corresponding key­
       word, such as INIT: or CLEANUP:.  However, the first two
       lines of an XSUB always contain the same data: descrip­
       tions 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 "The INPUT: Keyword".)

       An XSUB section continues until another section-start key­
       where x refers to a position in this XSUB's part of the
       stack.  Position 0 for that function would be known to the
       XSUB as ST(0).  The XSUB's incoming parameters and outgo­
       ing return values always begin at ST(0).  For many simple
       cases the xsubpp compiler will generate the code necessary
       to handle the argument stack by embedding code fragments
       found in the typemaps.  In more complex cases the program­
       mer must supply the code.

       The RETVAL Variable

       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
       xsubpp compiler will declare this variable in each XSUB
       with non-"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 "void" then the compiler
       will 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, "void" return value
       should be used only for subroutines which do not return a
       value, even if CODE: directive is used which sets ST(0)

       Older versions of this document recommended to use "void"
       return value in such cases. It was discovered that this
       could lead to segfaults in cases when XSUB was truly
       "void". This practice is now deprecated, and may be not
       supported at some future version. Use the return value "SV
       *" in such cases. (Currently "xsubpp" contains some
       heuristic code which tries to disambiguate between
       "truly-void" and "old-practice-declared-as-void" func­
       tions. Hence your code is at mercy of this heuristics
       unless you use "SV *" as return value.)

       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 with
       POD stripped, but otherwise untouched.  Every XS module
       will have a bootstrap function which is used to hook the
       into packages the PACKAGE keyword should be used.  This
       keyword is used with the MODULE keyword and must follow
       immediately after it when used.

            MODULE = RPC  PACKAGE = RPC

            [ XS code in package RPC ]

            MODULE = RPC  PACKAGE = RPCB

            [ XS code in package RPCB ]

            MODULE = RPC  PACKAGE = 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 pro­
       vides redundant information it should always be used.
       This keyword will ensure that the XSUBs appear in the
       desired package.

       The PREFIX Keyword

       The PREFIX keyword designates prefixes which should be
       removed from the Perl function names.  If the C function
       is "rpcb_gettime()" and the PREFIX value is "rpcb_" then
       Perl will see this function as "gettime()".

       This keyword should follow the PACKAGE keyword when used.
       If PACKAGE is not used then PREFIX should follow the MOD­
       ULE keyword.

            MODULE = RPC  PREFIX = rpc_

            MODULE = RPC  PACKAGE = RPCB  PREFIX = rpcb_

       The OUTPUT: Keyword

       The OUTPUT: keyword indicates that certain function param­
       eters 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 func­
       tions 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 xsubpp compiler will need help to determine which
       variables are output variables.

                 char *host
                 time_t &timep

       The OUTPUT: keyword will also allow an output parameter to
       be mapped to a matching piece of code rather than to a

                 char *host
                 time_t &timep
                 timep sv_setnv(ST(1), (double)timep);

       xsubpp emits an automatic "SvSETMAGIC()" for all parame­
       ters in the OUTPUT section of the XSUB, except RETVAL.
       This is the usually desired behavior, as it takes care of
       properly invoking 'set' magic on output parameters (needed
       for hash or array element parameters that must be created
       if they didn't exist).  If for some reason, this behavior
       is not desired, the OUTPUT section may contain a "SET­
       MAGIC: DISABLE" line to disable it for the remainder of
       the parameters in the OUTPUT section.  Likewise,  "SET­
       MAGIC: ENABLE" can be used to reenable it for the remain­
       der of the OUTPUT section.  See perlguts for more details
       about 'set' magic.

       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-"void" return type,
       the return value of this C subroutine should not be
       returned from the generated Perl subroutine.

       With this keyword present "The RETVAL Variable" is cre­
       ated, 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 "RETVAL" is going to be
       accessed by the user-supplied code.  It is especially use­
       ful to make a function interface more Perl-like, espe­
       cially when the C return value is just an error condition
       indicator.  For example,

         NO_OUTPUT int
         delete_file(char *name)
             if (RETVAL != 0)

       The following XSUB is for a C function which requires spe­
       cial handling of its parameters.  The Perl usage is given

            $status = rpcb_gettime( "localhost", $timep );

       The XSUB follows.

                 char *host
                 time_t timep
                      RETVAL = rpcb_gettime( host, &timep );

       The INIT: Keyword

       The INIT: keyword allows initialization to be inserted
       into the XSUB before the compiler generates the call to
       the C function.  Unlike the CODE: keyword above, this key­
       word does not affect the way the compiler handles RETVAL.

                 char *host
                 time_t &timep
                 printf("# Host is %s\n", host );

       Another use for the INIT: section is to check for precon­
       ditions before making a call to the C function:

           long long
               long long a
               long long b
               if (a == 0 && b == 0)
               if (b == 0)
                   croak("lldiv: cannot divide by 0");

       The NO_INIT Keyword

       The NO_INIT keyword is used to indicate that a function
       parameter is being used only as an output value.  The
                 char *host
                 time_t &timep = NO_INIT

       Initializing Function Parameters

       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 pro­
       grammer, however, is allowed to override the typemaps and
       supply alternate (or additional) initialization code.
       Initialization code starts with the first "=", ";" or "+"
       on a line in the INPUT: section.  The only exception hap­
       pens if this ";" terminates the line, then this ";" is
       quietly ignored.

       The following code demonstrates how to supply initializa­
       tion code for function parameters.  The initialization
       code is eval'd within double quotes by the compiler before
       it is added to the output so anything which should be
       interpreted literally [mainly "$", "@", or "\\"] must be
       protected with backslashes.  The variables $var, $arg, and
       $type can be used as in typemaps.

                 char *host = (char *)SvPV($arg,PL_na);
                 time_t &timep = 0;

       This should not be used to supply default values for
       parameters.  One would normally use this when a function
       parameter must be processed by another library function
       before it can be used.  Default parameters are covered in
       the next section.

       If the initialization begins with "=", then it is output
       in the declaration for the input variable, replacing the
       initialization supplied by the typemap.  If the initial­
       ization begins with ";" or "+", then it is performed after
       all of the input variables have been declared.  In the ";"
       case the initialization normally supplied by the typemap
       is not performed.  For the "+" case, the declaration for
       the variable will include the initialization from the
       typemap.  A global variable, %v, is available for the
       truly rare case where information from one initialization
       is needed in another initialization.

       The construct "\$v{timep}=@{[$v{timep}=$arg]}" used in the
       above example has a two-fold purpose: first, when this
       line is processed by xsubpp, the Perl snippet
       "$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 "char
       *host" line, $arg will evaluate to ST(0), and $v{timep}
       will evaluate to ST(1).

       Default Parameter Values

       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 "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.  This XSUB can
       be called from Perl with either of the following state­

            $status = rpcb_gettime( $timep, $host );

            $status = rpcb_gettime( $timep );

       The XSUB will look like the code  which  follows.   A
       CODE: block  is used to call the real rpcb_gettime() func­
       tion with the parameters in the correct order for that

                 char *host
                 time_t timep = NO_INIT
                      RETVAL = rpcb_gettime( host, &timep );

       The PREINIT: Keyword

       The PREINIT: keyword allows extra variables to be declared
       immediately before or after the declarations of the param­
       eters 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

                 time_t timep = NO_INIT
                 char *host = "localhost";
                 RETVAL = rpcb_gettime( host, &timep );

       For this particular case an INIT: keyword would generate
       the same C code as the PREINIT: keyword.  Another correct,
       but error-prone example:

                 time_t timep = NO_INIT
                 char *host = "localhost";
                 RETVAL = rpcb_gettime( host, &timep );

       Another way to declare "host" is to use a C block in the
       CODE: section:

                 time_t timep = NO_INIT
                   char *host = "localhost";
                   RETVAL = rpcb_gettime( host, &timep );

       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:

                   MyState st = global_state;
                   MyObject o;

                 MyState st = global_state;
                 MyObject o;
                 reset_to(global_state, st);

       and the code for rpcb_gettime() can be rewritten as

                 time_t timep = NO_INIT
                 char *host = "localhost";
                 host, &timep

       The SCOPE: Keyword

       The SCOPE: keyword allows scoping to be enabled for a par­
       ticular XSUB. If enabled, the XSUB will invoke ENTER and
       LEAVE automatically.

       To support potentially complex type mappings, if a typemap
       entry used by an XSUB contains a comment like "/*scope*/"
       then scoping will be automatically enabled for that XSUB.

       To enable scoping:

           SCOPE: ENABLE

       To disable scoping:

           SCOPE: DISABLE

       The INPUT: Keyword

       The XSUB's parameters are usually evaluated immediately
       after entering the XSUB.  The INPUT: keyword can be used
       to force those parameters to be evaluated a little later.
       The INPUT: keyword can be used multiple times within an
       XSUB and can be used to list one or more input variables.
       This keyword is used with the PREINIT: keyword.

       The following example shows how the input parameter
       "timep" can be evaluated late, after a PREINIT.

                      RETVAL = rpcb_gettime( host, &tt );
                      timep = tt;

       The next example shows each input parameter evaluated

                 time_t tt;
                 char *host
                 char *h;
                 time_t timep
                      h = host;
                      RETVAL = rpcb_gettime( h, &tt );
                      timep = tt;

       Since INPUT sections allow declaration of C variables
       which do not appear in the parameter list of a subroutine,
       this may be shortened to:

                 time_t tt;
                 char *host;
                 char *h = host;
                 time_t timep;
                 RETVAL = rpcb_gettime( h, &tt );
                 timep = tt;

       (We used our knowledge that input conversion for "char *"
       is a "simple" one, thus "host" is initialized on the dec­
       laration line, and our assignment "h = host" is not per­
       formed too early.  Otherwise one would need to have the
       assignment "h = host" in a CODE: or INIT: section.)

       Parameters preceded by "OUTLIST" keyword do not appear in
       the usage signature of the generated Perl function.

       Parameters preceded by "IN_OUTLIST"/"IN_OUT"/"OUT" do
       appear as parameters to the Perl function.  With the
       exception of "OUT"-parameters, these parameters are con­
       verted 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

       The return list of the generated Perl function consists of
       the C return value from the function (unless the XSUB is
       of "void" return type or "The NO_OUTPUT Keyword" was used)
       followed by all the "OUTLIST" and "IN_OUTLIST" parameters
       (in the order of appearance).  On the return from the XSUB
       the "IN_OUT"/"OUT" Perl parameter will be modified to have
       the values written by the C function.

       For example, an XSUB

         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 "IN"/"OUTLIST"/"IN_OUTLIST"/"IN_OUT"/"OUT" keywords
       can be mixed with ANSI-style declarations, as in

         day_month(OUTLIST int day, int unix_time, OUTLIST int month)

       (here the optional "IN" keyword is omitted).

       The "IN_OUT" parameters are identical with parameters
       introduced with "The & Unary Operator" and put into the
       "OUTPUT:" section (see "The OUTPUT: Keyword").  The
       "IN_OUTLIST" parameters are very similar, the only differ­
       ence being that the value C function writes through the
       pointer would not modify the Perl parameter, but is put in
       the output list.

       The "OUTLIST"/"OUT" parameter differ from "IN_OUT­
             int &month = NO_INIT

       However, the generated Perl function is called in very
       C-ish style:

         my ($day, $month);
         day_month($day, time, $month);

       The "length(NAME)" Keyword

       If one of the input arguments to the C function is the
       length of a string argument "NAME", one can substitute the
       name of the length-argument by "length(NAME)" in the XSUB
       declaration.  This argument must be omited when the gener­
       ated Perl function is called.  E.g.,

         dump_chars(char *s, short l)
           short n = 0;
           while (n < l) {
               printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]);

         MODULE = x            PACKAGE = x

         void dump_chars(char *s, short length(s))

       should be called as "dump_chars($string)".

       This directive is supported with ANSI-type function decla­
       rations only.

       Variable-length Parameter Lists

       XSUBs can have variable-length parameter lists by specify­
       ing an ellipsis "(...)" in the parameter list.  This use
       of the ellipsis is similar to that found in ANSI C.  The
       programmer is able to determine the number of arguments
       passed to the XSUB by examining the "items" variable which
       the xsubpp compiler supplies for all XSUBs.  By using this
       mechanism one can create an XSUB which accepts a list of
       parameters of unknown length.

       The host parameter for the rpcb_gettime() XSUB can be
       optional so the ellipsis can be used to indicate that the
       XSUB will take a variable number of parameters.  Perl
                 STRLEN n_a;
                 if( items > 1 )
                      host = (char *)SvPV(ST(1), n_a);
                 RETVAL = rpcb_gettime( host, &timep );

       The C_ARGS: Keyword

       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 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 a C function is declared as

           symbolic nth_derivative(int n, symbolic function, int flags);

       and that the default flags are kept in a global C variable
       "default_flags".  Suppose that you want to create an
       interface which is called as

           $second_deriv = $function->nth_derivative(2);

       To do this, declare the XSUB as

           nth_derivative(function, n)
               symbolic        function
               int             n
               n, function, default_flags

       The PPCODE: Keyword

       The PPCODE: keyword is an alternate form of the CODE: key­
       word and is used to tell the xsubpp compiler that the pro­
       grammer is supplying the code to control the argument
       stack for the XSUBs return values.  Occasionally one will
       want an XSUB to return a list of values rather than a sin­
       gle value.  In these cases one must use PPCODE: and then
       explicitly push the list of 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 "SP" macro (which stands for
       the current Perl stack pointer), and in the handling of
       data on the stack when returning from an XSUB.  In CODE:

       Note that macros ST(i), "XST_m*()" and "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.

                 char *host
                 time_t  timep;
                 bool_t  status;
                 status = rpcb_gettime( host, &timep );
                 EXTEND(SP, 2);

       Notice that the programmer must supply the C code neces­
       sary to have the real rpcb_gettime() function called and
       to have the return values properly placed on the argument

       The "void" return type for this function tells the xsubpp
       compiler that the RETVAL variable is not needed or used
       and that it should not be created.  In most scenarios the
       void return type should be used with the PPCODE: direc­

       The EXTEND() macro is used to make room on the argument
       stack for 2 return values.  The PPCODE: directive causes
       the xsubpp compiler to create a stack pointer available as
       "SP", and it is this pointer which is being used in the
       EXTEND() macro.  The values are then pushed onto the stack
       with the PUSHs() macro.

       Now the rpcb_gettime() function can be used from Perl with
       the following statement.

            ($status, $timep) = rpcb_gettime("localhost");

       When handling output parameters with a PPCODE section, be
       sure to handle 'set' magic properly.  See perlguts for
       details about 'set' magic.

       Returning Undef And Empty Lists

       Occasionally the programmer will want to return simply
       "undef" or an empty list if a function fails rather than a
       separate status value.  The rpcb_gettime() function offers

            SV *
                 char *  host
                 time_t  timep;
                 bool_t x;
                 ST(0) = sv_newmortal();
                 if( rpcb_gettime( host, &timep ) )
                      sv_setnv( ST(0), (double)timep);

       The next example demonstrates how one would place an
       explicit undef in the return value, should the need arise.

            SV *
                 char *  host
                 time_t  timep;
                 bool_t x;
                 ST(0) = sv_newmortal();
                 if( rpcb_gettime( host, &timep ) ){
                      sv_setnv( ST(0), (double)timep);
                      ST(0) = &PL_sv_undef;

       To return an empty list one must use a PPCODE: block and
       then not push return values on the stack.

                 char *host
                 time_t  timep;
                 if( rpcb_gettime( host, &timep ) )
                     /* Nothing pushed on stack, so an empty
                      * list is implicitly returned. */

       Some people may be inclined to include an explicit
       "return" in the above XSUB, rather than letting control
       fall through to the end.  In those situations "XSRE­
       TURN_EMPTY" should be used, instead.  This will ensure
       that the XSUB stack is properly adjusted.  Consult perlapi
       for other "XSRETURN" macros.
                 if (RETVAL == 0)

       In fact, one can put this check into a POSTCALL: section
       as well.  Together with PREINIT: simplifications, this
       leads to:

                 char *host
                 time_t  timep;
                 if (RETVAL == 0)

       The REQUIRE: Keyword

       The REQUIRE: keyword is used to indicate the minimum ver­
       sion of the xsubpp compiler needed to compile the XS mod­
       ule.  An XS module which contains the following statement
       will compile with only xsubpp version 1.922 or greater:

               REQUIRE: 1.922

       The CLEANUP: Keyword

       This keyword can be used when an XSUB requires special
       cleanup procedures before it terminates.  When the
       CLEANUP:  keyword is used it must follow any CODE:,
       PPCODE:, or OUTPUT: blocks which are present in the XSUB.
       The code specified for the cleanup block will be added as
       the last statements in the XSUB.

       The POSTCALL: Keyword

       This keyword can be used when an XSUB requires special
       procedures executed after the C subroutine call is per­
       formed.  When the POSTCALL: keyword is used it must pre­
       cede OUTPUT: and CLEANUP: blocks which are present in the

       See examples in "The NO_OUTPUT Keyword" and "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.

       The BOOT: Keyword

            # bootstrap function executes.
            printf("Hello from the bootstrap!\n");

       The VERSIONCHECK: Keyword

       The VERSIONCHECK: keyword corresponds to xsubpp's "-ver­
       sioncheck" and "-noversioncheck" options.  This keyword
       overrides the command line options.  Version checking is
       enabled by default.  When version checking is enabled the
       XS module will attempt to verify that its version matches
       the version of the PM module.

       To enable version checking:


       To disable version checking:


       The PROTOTYPES: Keyword

       The PROTOTYPES: keyword corresponds to xsubpp's "-proto­
       types" and "-noprototypes" options.  This keyword over­
       rides the command line options.  Prototypes are enabled by
       default.  When prototypes are enabled XSUBs will be given
       Perl prototypes.  This keyword may be used multiple times
       in an XS module to enable and disable prototypes for dif­
       ferent parts of the module.

       To enable prototypes:


       To disable prototypes:


       The PROTOTYPE: Keyword

       This keyword is similar to the PROTOTYPES: keyword above
       but can be used to force xsubpp to use a specific proto­
       type for the XSUB.  This keyword overrides all other pro­
       totype options and keywords but affects only the current
       XSUB.  Consult "Prototypes" in perlsub for information
       about Perl prototypes.

                         if( items > 1 )
                              host = (char *)SvPV(ST(1), n_a);
                         RETVAL = rpcb_gettime( host, &timep );

       If the prototypes are enabled, you can disable it locally
       for a given XSUB as in the following example:

               PROTOTYPE: DISABLE

       The ALIAS: Keyword

       The ALIAS: keyword allows an XSUB to have two or more
       unique Perl names and to know which of those names was
       used when it was invoked.  The Perl names may be fully-
       qualified with package names.  Each alias is given an
       index.  The compiler will setup a variable called "ix"
       which contain the index of the alias which was used.  When
       the XSUB is called with its declared name "ix" will be 0.

       The following example will create aliases "FOO::gettime()"
       and "BAR::getit()" for this function.

                 char *host
                 time_t &timep
                   FOO::gettime = 1
                   BAR::getit = 2
                 printf("# ix = %d\n", ix );

       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.
           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).

       The FALLBACK: Keyword

       In addition to the OVERLOAD keyword, if you need to con­
       trol how Perl autogenerates missing overloaded operators,
       you can set the FALLBACK keyword in the module header sec­
       tion, 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 "Fallback" in overload for
       more details.

       The INTERFACE: Keyword

       This keyword declares the current XSUB as a keeper of the
       given calling signature.  If some text follows this key­
       word, it is considered as a list of functions which have
       this signature, and should be attached to the current

       For example, if you have 4 C functions multiply(),
       divide(), add(), subtract() all having the signature:

           symbolic f(symbolic, symbolic);

       you can make them all to use the same XSUB using this:

           interface_s_ss(arg1, arg2)
               symbolic        arg1
               symbolic        arg2
               multiply divide
               add subtract

       say, from another XSUB.  (This example supposes that there
       was no INTERFACE_MACRO: section, otherwise one needs to
       use something else instead of "XSINTERFACE_FUNC_SET", see
       the next section.)

       The INTERFACE_MACRO: Keyword

       This keyword allows one to define an INTERFACE using a
       different way to extract a function pointer from an XSUB.
       The text which follows this keyword should give the name
       of macros which would extract/set a function pointer.  The
       extractor macro is given return type, "CV*", and
       "XSANY.any_dptr" for this "CV*".  The setter macro is
       given cv, and the function pointer.

       The default value is "XSINTERFACE_FUNC" and "XSINTER­
       FACE_FUNC_SET".  An INTERFACE keyword with an empty list
       of functions can be omitted if INTERFACE_MACRO keyword is

       Suppose that in the previous example functions pointers
       for multiply(), divide(), add(), subtract() are kept in a
       global C array "fp[]" with offsets being "multiply_off",
       "divide_off", "add_off", "subtract_off".  Then one can use

           #define XSINTERFACE_FUNC_BYOFFSET(ret,cv,f) \
           #define XSINTERFACE_FUNC_BYOFFSET_set(cv,f) \
               CvXSUBANY(cv).any_i32 = CAT2( f, _off )

       in C section,

           interface_s_ss(arg1, arg2)
               symbolic        arg1
               symbolic        arg2
               multiply divide
               add subtract

       in XSUB section.

       The INCLUDE: Keyword

       This keyword can be used to pull other files into the XS
       module.  The other files may have XS code.  INCLUDE: can
       also be used to run a command to generate the XS code to
       be pulled into the module.
       The XS module can use INCLUDE: to pull that file into it.

           INCLUDE: Rpcb1.xsh

       If the parameters to the INCLUDE: keyword are followed by
       a pipe ("|") then the compiler will interpret the parame­
       ters as a command.

           INCLUDE: cat Rpcb1.xsh |

       The CASE: Keyword

       The CASE: keyword allows an XSUB to have multiple distinct
       parts with each part acting as a virtual XSUB.  CASE: is
       greedy and if it is used then all other XS keywords must
       be contained within a CASE:.  This means nothing may pre­
       cede the first CASE: in the XSUB and anything following
       the last CASE: is included in that case.

       A CASE: might switch via a parameter of the XSUB, via the
       "ix" ALIAS: variable (see "The ALIAS: Keyword"), or maybe
       via the "items" variable (see "Variable-length Parameter
       Lists").  The last CASE: becomes the default case if it is
       not associated with a conditional.  The following example
       shows CASE switched via "ix" with a function "rpcb_get­
       time()" having an alias "x_gettime()".  When the function
       is called as "rpcb_gettime()" its parameters are the usual
       "(char *host, time_t *timep)", but when the function is
       called as "x_gettime()" its parameters are reversed,
       "(time_t *timep, char *host)".

             CASE: ix == 1
                 x_gettime = 1
                 # 'a' is timep, 'b' is host
                 char *b
                 time_t a = NO_INIT
                      RETVAL = rpcb_gettime( b, &a );
                 # 'a' is host, 'b' is timep
                 char *a
                 time_t &b = NO_INIT

       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 "int" or "long"
       but not an "int*" or "long*").

       The following XSUB will generate incorrect C code.  The
       xsubpp compiler will turn this into code which calls
       "rpcb_gettime()" with parameters "(char *host, time_t
       timep)", but the real "rpcb_gettime()" wants the "timep"
       parameter to be of type "time_t*" rather than "time_t".

                 char *host
                 time_t timep

       That problem is corrected by using the "&" operator.  The
       xsubpp compiler will now turn this into code which calls
       "rpcb_gettime()" correctly with parameters "(char *host,
       time_t *timep)".  It does this by carrying the "&"
       through, so the function call looks like "rpcb_get­
       time(host, &timep)".

                 char *host
                 time_t &timep

       Inserting POD, Comments and C Preprocessor Directives

       C preprocessor directives are allowed within BOOT:,
       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 sec­
       tions. POD must be terminated with a "=cut" command;
       "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 "=". 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 "#" as the
       first non-whitespace of a line.  Care should be taken to
           #if ... version2

       because otherwise 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.

       Using XS With C++

       If an XSUB name contains "::", 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 be blessed by Perl with the
       sv_setref_pv() macro.  The 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 return type of the XSUB includes "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->method() syntax.

       The next examples will use the following C++ class.

            class color {
                 int blue();
                 void set_blue( int );

                 int c_blue;

       The XSUBs for the blue() and set_blue() methods are
       defined with the class name but the parameter for the
       object (THIS, or "self") is implicit and is not listed.


            color::set_blue( val )
                 int val

       Both Perl functions will expect an object as the first
                int val
                PROTOTYPE $;$
                    if (items > 1)
                        THIS->set_blue( val );
                    RETVAL = THIS->blue();

       If the function's name is DESTROY then the C++ "delete"
       function will be called and "THIS" will be given as its
       parameter.  The generated C++ code for


       will look like this:

            color *THIS = ...; // Initialized as in typemap

            delete THIS;

       If the function's name is new then the C++ "new" function
       will be called to create a dynamic C++ object.  The XSUB
       will expect the class name, which will be kept in a vari­
       able called "CLASS", to be given as the first argument.

            color *

       The generated C++ code will call "new".

            RETVAL = new color();

       The following is an example of a typemap that could be
       used for this C++ example.

           color *             O_OBJECT

           # The Perl object is blessed into 'CLASS', which should be a
           # char* having the name of the package for the blessing.
               sv_setref_pv( $arg, CLASS, (void*)$var );

               if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
                       $var = ($type)SvIV((SV*)SvRV( $arg ));
                       warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );

       parts of the interface.

       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 "negative_is_failure" which converts
       negative values to "undef", or maybe croak()s.  After this
       the return value of type "negative_is_failure" will create
       more Perl-like interface.

       Identify which values are used by only the C and XSUB
       functions 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 may be used to implement
       input/output or output parameters, they can be handled in
       XS with the "&" unary operator, and, possibly, using the
       NO_INIT keyword.  Some others will require handling of
       types like "int *", and one needs to decide what a useful
       Perl translation will do in such a case.  When the seman­
       tic 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.  (This is handled automatically by "h2xs

       If the same C type is used in several different contexts
       which require different translations, "typedef" several
       while the T_PTROBJ type requires that the object be
       blessed.  By using T_PTROBJ one can achieve a form of
       type-checking because the XSUB will attempt to verify that
       the Perl object is of the expected type.

       The following XS code shows the getnetconfigent() function
       which is used with ONC+ TIRPC.  The getnetconfigent()
       function will return a pointer to a C structure and has
       the C prototype shown below.  The example will demonstrate
       how the C pointer will become a Perl reference.  Perl will
       consider this reference to be a pointer to a blessed
       object and will attempt to call a destructor for the
       object.  A destructor will be provided in the XS source to
       free the memory used by getnetconfigent().  Destructors in
       XS can be created by specifying an XSUB function whose
       name ends with the word DESTROY.  XS destructors can be
       used to free memory which may have been malloc'd by
       another XSUB.

            struct netconfig *getnetconfigent(const char *netid);

       A "typedef" will be created for "struct netconfig".  The
       Perl object will be blessed in a class matching the name
       of the C type, with the tag "Ptr" appended, and the name
       should not have embedded spaces if it will be a Perl pack­
       age name.  The destructor will be placed in a class corre­
       sponding to the class of the object and the PREFIX keyword
       will be used to trim the name to the word DESTROY as Perl
       will expect.

            typedef struct netconfig Netconfig;

            MODULE = RPC  PACKAGE = RPC

            Netconfig *
                 char *netid

            MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_

                 Netconfig *netconf
                 printf("Now in NetconfigPtr::DESTROY\n");
                 free( netconf );

       This example requires the following typemap entry.  Con­
       sult the typemap section for more information about adding
       new typemaps for an extension.


       normal Perl subroutine.

       The Typemap

       The typemap is a collection of code fragments which are
       used by the xsubpp compiler to map C function parameters
       and values to Perl values.  The typemap file may consist
       of three sections labelled "TYPEMAP", "INPUT", and "OUT­
       PUT".  An unlabelled initial section is assumed to be a
       "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 understand.  The TYPEMAP section tells the compiler
       which of the INPUT and OUTPUT code fragments should be
       used to map a given C type to a Perl value.  The section
       labels "TYPEMAP", "INPUT", or "OUTPUT" must begin in the
       first column on a line by themselves, and must be in

       The default typemap in the "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 xsubpp compiler will allow the
       extension's own typemap to override any mappings which are
       in the default typemap.

       Most extensions which require a custom typemap will need
       only the TYPEMAP section of the typemap file.  The custom
       typemap used in the getnetconfigent() example shown ear­
       lier demonstrates what may be the typical use of extension
       typemaps.  That typemap is used to equate a C structure
       with the T_PTROBJ typemap.  The typemap used by getnetcon­
       figent() is shown here.  Note that the C type is separated
       from the XS type with a tab and that the C unary operator
       "*" is considered to be a part of the C type name.

               Netconfig *<tab>T_PTROBJ

       Here's a more complicated example: suppose that you wanted
       "struct netconfig" to be blessed into the class "Net::Con­
       fig".  One way to do this is to use underscores (_) to
       separate package names, as follows:

               typedef struct netconfig * Net_Config;

       And then provide a typemap entry "T_PTROBJ_SPECIAL" that
       maps underscores to double-colons (::), and declare
       "Net_Config" to be of that type:
                               croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")

                       sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",

       The INPUT and OUTPUT sections substitute underscores for
       double-colons on the fly, giving the desired effect.  This
       example demonstrates some of the power and versatility of
       the typemap facility.

       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 "-g" ("--global") option with h2xs (see

       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;


           MODULE = BlindMice           PACKAGE = BlindMice

               MY_CXT.count = 0;
                     warn("Already have 3 blind mice") ;
                     RETVAL = 0;
                 else {
                     RETVAL = ++ MY_CXT.count;
                     strcpy(MY_CXT.name[MY_CXT.count - 1], name);

           char *
             int index
               RETVAL = MY_CXT.lives ++;
               if (index > MY_CXT.count)
                 croak("There are only 3 blind mice.");
                 RETVAL = newSVpv(MY_CXT.name[index - 1]);


            This macro is used to define a unique key to refer to
            the static data for an XS module. The suggested nam­
            ing 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

       typedef my_cxt_t
            This struct typedef must always be called "my_cxt_t"
            -- the other "CXT*" macros assume the existence of
            the "my_cxt_t" typedef name.

            Declare a typedef named "my_cxt_t" that is a struc­
            ture that contains all the data that needs to be

                typedef struct {
                    int some_value;
                } my_cxt_t;

            Always place the START_MY_CXT macro directly after
            the declaration of "my_cxt_t".

            The MY_CXT_INIT macro initialises storage for the
            "my_cxt_t" struct.

            It must be called exactly once -- typically in a
            then use this to access the "index" member

                MY_CXT.index = 2;


       File "RPC.xs": Interface to some ONC+ RPC bind library

            #include "EXTERN.h"
            #include "perl.h"
            #include "XSUB.h"

            #include <rpc/rpc.h>

            typedef struct netconfig Netconfig;

            MODULE = RPC  PACKAGE = RPC

            SV *
                 char *host
                 time_t  timep;
                 ST(0) = sv_newmortal();
                 if( rpcb_gettime( host, &timep ) )
                      sv_setnv( ST(0), (double)timep );

            Netconfig *
                 char *netid

            MODULE = RPC  PACKAGE = NetconfigPtr  PREFIX = rpcb_

                 Netconfig *netconf
                 free( netconf );

       File "typemap": Custom typemap for RPC.xs.

            Netconfig *  T_PTROBJ

       File "RPC.pm": Perl module for the RPC extension.

            package RPC;

            require Exporter;
            print "time = $a\n";
            print "netconf = $netconf\n";

            $netconf = getnetconfigent("tcp");
            $a = rpcb_gettime("poplar");
            print "time = $a\n";
            print "netconf = $netconf\n";


       This document covers features supported by "xsubpp" 1.935.


       Originally written by Dean Roehrich <roehrich@cray.com>.

       Maintained since 1996 by The Perl Porters <perl­

perl v5.8.1                 2003-09-02                  PERLXS(1)

An undefined database error occurred. SELECT distinct pages.pagepath,pages.pageid FROM pages, page2command WHERE pages.pageid = page2command.pageid AND commandid =

Show your Support for the Linux Tutorial

Purchase one of the products from our new online shop. For each product you purchase, the Linux Tutorial gets a portion of the proceeds to help keep us going.



Security Code
Security Code
Type Security Code

Don't have an account yet? You can create one. As a registered user you have some advantages like theme manager, comments configuration and post comments with your name.

Help if you can!

Amazon Wish List

Did You Know?
The Linux Tutorial can use your help.


Tell a Friend About Us

Bookmark and Share

Web site powered by PHP-Nuke

Is this information useful? At the very least you can help by spreading the word to your favorite newsgroups, mailing lists and forums.
All logos and trademarks in this site are property of their respective owner. The comments are property of their posters. Articles are the property of their respective owners. Unless otherwise stated in the body of the article, article content (C) 1994-2013 by James Mohr. All rights reserved. The stylized page/paper, as well as the terms "The Linux Tutorial", "The Linux Server Tutorial", "The Linux Knowledge Base and Tutorial" and "The place where you learn Linux" are service marks of James Mohr. All rights reserved.
The Linux Knowledge Base and Tutorial may contain links to sites on the Internet, which are owned and operated by third parties. The Linux Tutorial is not responsible for the content of any such third-party site. By viewing/utilizing this web site, you have agreed to our disclaimer, terms of use and privacy policy. Use of automated download software ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and are therefore expressly prohibited. For more details on this, take a look here

PHP-Nuke Copyright © 2004 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 0.23 Seconds