=head2 On The Road
-Many of the examples which follow will concentrate on creating an
-interface between Perl and the ONC+ RPC bind library functions.
-Specifically, the rpcb_gettime() function will be used to demonstrate many
-features of the XS language. This function has two parameters; the first
-is an input parameter and the second is an output parameter. The function
-also returns a status value.
+Many of the examples which follow will concentrate on creating 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
+function 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);
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 may not be needed.
+the PPCODE: directive the RETVAL variable is not needed, unless used
+explicitly.
+
+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:
+directive is used which sets ST(0) explicitly.
+
+Older versions of this document recommended to use C<void> return
+value in such cases. It was discovered that this could lead to
+segfaults in cases when XSUB was I<truely> C<void>. This practice is
+now deprecated, and may be not supported at some future version. Use
+the return value C<SV *> in such cases. (Currently C<xsubpp> contains
+some heuristic code which tries to disambiguate between "truely-void"
+and "old-practice-declared-as-void" functions. Hence your code is at
+mercy of this heuristics unless you use C<SV *> as return value.)
=head2 The MODULE Keyword
timep
RETVAL
+=head2 The SCOPE: Keyword
+
+The SCOPE: keyword allows scoping to be enabled for a particular XSUB. If
+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.
+
+To enable scoping:
+
+ SCOPE: ENABLE
+
+To disable scoping:
+
+ SCOPE: DISABLE
+
=head2 The INPUT: Keyword
The XSUB's parameters are usually evaluated immediately after entering the
=head2 Returning Undef And Empty Lists
-Occasionally the programmer will want to simply return
+Occasionally the programmer will want to return simply
C<undef> or an empty list if a function fails rather than a
separate status value. The rpcb_gettime() function offers
just this situation. If the function succeeds we would like
$timep = rpcb_gettime( "localhost" );
-The following XSUB uses the C<void> return type to disable the generation of
-the RETVAL variable and uses a CODE: block to indicate to the compiler
+The following XSUB uses the C<SV *> return type as a mneumonic only,
+and uses a CODE: block to indicate to the compiler
that the programmer has supplied all the necessary code. The
sv_newmortal() call will initialize the return value to undef, making that
the default return value.
- void
+ SV *
rpcb_gettime(host)
char * host
PREINIT:
The next example demonstrates how one would place an explicit undef in the
return value, should the need arise.
- void
+ SV *
rpcb_gettime(host)
char * host
PREINIT:
/* list is implicitly returned. */
}
+Some people may be inclined to include an explicit C<return> in the above
+XSUB, rather than letting control fall through to the end. In those
+situations C<XSRETURN_EMPTY> should be used, instead. This will ensure that
+the XSUB stack is properly adjusted. Consult L<perlguts/"API LISTING"> for
+other C<XSRETURN> macros.
+
=head2 The REQUIRE: Keyword
The REQUIRE: keyword is used to indicate the minimum version of the
B<xsubpp> compiler needed to compile the XS module. An XS module which
-contains the following statement will only compile with B<xsubpp> version
+contains the following statement will compile with only B<xsubpp> version
1.922 or greater:
REQUIRE: 1.922
=head2 The VERSIONCHECK: Keyword
The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
-C<-noversioncheck> options. This keyword overrides the commandline
+C<-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.
=head2 The PROTOTYPES: Keyword
The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
-C<-noprototypes> options. This keyword overrides the commandline options.
+C<-noprototypes> options. This keyword overrides 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 different parts of the module.
B<default> case if it is not associated with a conditional. The following
example shows CASE switched via C<ix> with a function C<rpcb_gettime()>
having an alias C<x_gettime()>. When the function is called as
-C<rpcb_gettime()> it's parameters are the usual C<(char *host, time_t
-*timep)>, but when the function is called as C<x_gettime()> is parameters are
+C<rpcb_gettime()> its parameters are the usual C<(char *host, time_t *timep)>,
+but when the function is called as C<x_gettime()> its parameters are
reversed, C<(time_t *timep, char *host)>.
long
=head2 Inserting Comments and C Preprocessor Directives
-Comments and C preprocessor directives are allowed within
-CODE:, PPCODE:, BOOT:, and CLEANUP: blocks. The compiler
-will pass the preprocessor directives through untouched and
-will remove the commented lines. Comments can be added to
-XSUBs by placing a C<#> at the beginning of the line. Care
-should be taken to avoid making the comment look like a C
-preprocessor directive, lest it be interpreted as such.
+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.
+
+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
+comment look like a C preprocessor directive, lest it be interpreted as
+such. The simplest way to prevent this is to put whitespace in front of
+the C<#>.
+
+If you use preprocessor directives to choose one of two
+versions of a function, use
+
+ #if ... version1
+ #else /* ... version2 */
+ #endif
+
+and not
+
+ #if ... version1
+ #endif
+ #if ... version2
+ #endif
+
+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.
=head2 Using XS With C++
If the method is defined as static 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 function will be called using the THIS-E<gt>method() syntax.
The next examples will use the following C++ class.
- class colors {
+ class color {
public:
- colors();
- ~colors();
+ color();
+ ~color();
int blue();
void set_blue( int );
# char* having the name of the package for the blessing.
O_OBJECT
sv_setref_pv( $arg, CLASS, (void*)$var );
-
+
INPUT
O_OBJECT
if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
MODULE = RPC PACKAGE = RPC
- void
+ SV *
rpcb_gettime(host="localhost")
char *host
PREINIT:
=head1 XS VERSION
-This document covers features supported by C<xsubpp> 1.931.
+This document covers features supported by C<xsubpp> 1.935.
=head1 AUTHOR
Dean Roehrich F<E<lt>roehrich@cray.comE<gt>>
-Jan 25, 1996
+Jul 8, 1996
projects / p5sagit/p5-mst-13.2.git / blobdiff