written in the XS language and is the core component of the Perl
extension interface.
+Before writing XS, read the L</CAVEATS> section below.
+
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
above. Note that the first three #include statements, for
C<EXTERN.h>, C<perl.h>, and C<XSUB.h>, will always be present at the
beginning of an XS file. This approach and others will be
-expanded later in this document.
+expanded later in this document. A #define for C<PERL_NO_GET_CONTEXT>
+should be present to fetch the interpreter context more efficiently,
+see L<perlguts|perlguts/How multiple interpreters and concurrency are
+supported> for details.
+ #define PERL_NO_GET_CONTEXT
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
the B<xsubpp> compiler will need help to determine which variables are output
variables.
-This keyword will normally be used to complement the CODE: keyword.
+This keyword will normally be used to complement the CODE: keyword.
The RETVAL variable is not recognized as an output variable when the
-CODE: keyword is present. The OUTPUT: keyword is used in this
+CODE: keyword is present. The OUTPUT: keyword is used in this
situation to tell the compiler that RETVAL really is an output
variable.
created if they didn't exist). If for some reason, this behavior is
not desired, the OUTPUT section may contain a C<SETMAGIC: DISABLE> line
to disable it for the remainder of the parameters in the OUTPUT section.
-Likewise, C<SETMAGIC: ENABLE> can be used to reenable it for the
+Likewise, C<SETMAGIC: ENABLE> can be used to reenable it for the
remainder of the OUTPUT section. See L<perlguts> for more details
about 'set' magic.
$status = rpcb_gettime( $timep );
-The XSUB will look like the code which follows. A CODE:
-block is used to call the real rpcb_gettime() function with
+The XSUB will look like the code which follows. A CODE:
+block is used to call the real rpcb_gettime() function with
the parameters in the correct order for that function.
bool_t
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 should not be 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
=head2 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.
+before it terminates. When the CLEANUP: keyword is used it must follow
+any CODE:, 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.
=head2 The POSTCALL: Keyword
The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
C<-noprototypes> options. This keyword overrides the command line options.
-Prototypes are enabled by default. When prototypes are enabled XSUBs will
+Prototypes are disabled 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 different parts of the module.
+Note that B<xsubpp> will nag you if you don't explicitly enable or disable
+prototypes, with:
+
+ Please specify prototyping behavior for Foo.xs (see perlxs manual)
To enable prototypes:
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
+overloaded functions must be defined in such a way as to accept the number
+of parameters supplied by perl's overload system. For most overload
+methods, it will be three parameters; for the C<nomethod> function it will
+be four. However, the bitwise operators C<&>, C<|>, C<^>, and C<~> may be
+called with three I<or> five arguments (see L<overload>).
+
+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.
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
+three input parameters (or use the C-style '...' definition) like
this:
SV *
multiple overloads with whitespace. Note that "" (the stringify
overload) should be entered as \"\" (i.e. escaped).
+Since, as mentioned above, bitwise operators may take extra arguments, you
+may want to use something like C<(lobj, robj, swap, ...)> (with
+literal C<...>) as your parameter list.
+
=head2 The FALLBACK: Keyword
In addition to the OVERLOAD keyword, if you need to control how
Below is an example module that makes use of the macros.
+ #define PERL_NO_GET_CONTEXT
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
This wrapping happens always when compiling Perl core source
(PERL_CORE is defined) or the Perl core extensions (PERL_EXT is
-defined). When compiling XS code outside of Perl core the wrapping
-does not take place. Note, however, that intermixing the _r-forms
-(as Perl compiled for multithreaded operation will do) and the _r-less
-forms is neither well-defined (inconsistent results, data corruption,
-or even crashes become more likely), nor is it very portable.
+defined). When compiling XS code outside of the Perl core, the wrapping
+does not take place before Perl 5.28. Starting in that release you can
+
+ #define PERL_REENTRANT
+
+in your code to enable the wrapping. It is advisable to do so if you
+are using such functions, as intermixing the C<_r>-forms (as Perl compiled
+for multithreaded operation will do) and the C<_r>-less forms is neither
+well-defined (inconsistent results, data corruption, or even crashes
+become more likely), nor is it very portable. Unfortunately, not all
+systems have all the C<_r> forms, but using this C<#define> gives you
+whatever protection that Perl is aware is available on each system.
=head1 EXAMPLES
File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
+ #define PERL_NO_GET_CONTEXT
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
print "time = $a\n";
print "netconf = $netconf\n";
+=head1 CAVEATS
+
+XS code has full access to system calls including C library functions.
+It thus has the capability of interfering with things that the Perl core
+or other modules have set up, such as signal handlers or file handles.
+It could mess with the memory, or any number of harmful things. Don't.
+
+Some modules have an event loop, waiting for user-input. It is highly
+unlikely that two such modules would work adequately together in a
+single Perl application.
+
+In general, the perl interpreter views itself as the center of the
+universe as far as the Perl program goes. XS code is viewed as a
+help-mate, to accomplish things that perl doesn't do, or doesn't do fast
+enough, but always subservient to perl. The closer XS code adheres to
+this model, the less likely conflicts will occur.
+
+One area where there has been conflict is in regards to C locales. (See
+L<perllocale>.) perl, with one exception and unless told otherwise,
+sets up the underlying locale the program is running in to the locale
+passed
+into it from the environment. This is an important difference from a
+generic C language program, where the underlying locale is the "C"
+locale unless the program changes it. As of v5.20, this underlying
+locale is completely hidden from pure Perl code outside the lexical
+scope of C<S<use locale>> except for a couple of function calls in the
+POSIX module which of necessity use it. But the underlying locale, with
+that
+one exception is exposed to XS code, affecting all C library routines
+whose behavior is locale-dependent. Your XS code better not assume that
+the underlying locale is "C". The exception is the
+L<C<LC_NUMERIC>|perllocale/Category LC_NUMERIC: Numeric Formatting>
+locale category, and the reason it is an exception is that experience
+has shown that it can be problematic for XS code, whereas we have not
+had reports of problems with the
+L<other locale categories|perllocale/WHAT IS A LOCALE>. And the reason
+for this one category being problematic is that the character used as a
+decimal point can vary. Many European languages use a comma, whereas
+English, and hence Perl are expecting a dot (U+002E: FULL STOP). Many
+modules can handle only the radix character being a dot, and so perl
+attempts to make it so. Up through Perl v5.20, the attempt was merely
+to set C<LC_NUMERIC> upon startup to the C<"C"> locale. Any
+L<setlocale()|perllocale/The setlocale function> otherwise would change
+it; this caused some failures. Therefore, starting in v5.22, perl tries
+to keep C<LC_NUMERIC> always set to C<"C"> for XS code.
+
+To summarize, here's what to expect and how to handle locales in XS code:
+
+=over
+
+=item Non-locale-aware XS code
+
+Keep in mind that even if you think your code is not locale-aware, it
+may call a C library function that is. Hopefully the man page for such
+a function will indicate that dependency, but the documentation is
+imperfect.
+
+The current locale is exposed to XS code except possibly C<LC_NUMERIC>
+(explained in the next paragraph).
+There have not been reports of problems with the other categories.
+Perl initializes things on start-up so that the current locale is the
+one which is indicated by the user's environment in effect at that time.
+See L<perllocale/ENVIRONMENT>.
+
+However, up through v5.20, Perl initialized things on start-up so that
+C<LC_NUMERIC> was set to the "C" locale. But if any code anywhere
+changed it, it would stay changed. This means that your module can't
+count on C<LC_NUMERIC> being something in particular, and you can't
+expect floating point numbers (including version strings) to have dots
+in them. If you don't allow for a non-dot, your code could break if
+anyone anywhere changed the locale. For this reason, v5.22 changed
+the behavior so that Perl tries to keep C<LC_NUMERIC> in the "C" locale
+except around the operations internally where it should be something
+else. Misbehaving XS code will always be able to change the locale
+anyway, but the most common instance of this is checked for and
+handled.
+
+=item Locale-aware XS code
+
+If the locale from the user's environment is desired, there should be no
+need for XS code to set the locale except for C<LC_NUMERIC>, as perl has
+already set the others up. XS code should avoid changing the locale, as
+it can adversely affect other, unrelated, code and may not be
+thread-safe. To minimize problems, the macros
+L<perlapi/STORE_LC_NUMERIC_SET_TO_NEEDED>,
+L<perlapi/STORE_LC_NUMERIC_FORCE_TO_UNDERLYING>, and
+L<perlapi/RESTORE_LC_NUMERIC> should be used to affect any needed
+change.
+
+However, some alien libraries that may be called do set it, such as
+C<Gtk>. This can cause problems for the perl core and other modules.
+Starting in v5.20.1, calling the function
+L<sync_locale()|perlapi/sync_locale> from XS should be sufficient to
+avoid most of these problems. Prior to this, you need a pure Perl
+statement that does this:
+
+ POSIX::setlocale(LC_ALL, POSIX::setlocale(LC_ALL));
+
+or use the methods given in L<perlcall>.
+
+=back
=head1 XS VERSION
https://perl5.git.perl.org / perl5.git / blobdiff