perlxs.html
来自「perl教程」· HTML 代码 · 共 945 行 · 第 1/5 页
HTML
945 行
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../../displayToc.js"></script>
<script language="JavaScript" src="../../tocParas.js"></script>
<script language="JavaScript" src="../../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../../scineplex.css">
<title>perlxs - XS language reference manual</title>
<link rel="stylesheet" href="../../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<script>writelinks('__top__',2);</script>
<h1><a>perlxs - XS language reference manual</a></h1>
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#on_the_road">On The Road</a></li>
<li><a href="#the_anatomy_of_an_xsub">The Anatomy of an XSUB</a></li>
<li><a href="#the_argument_stack">The Argument Stack</a></li>
<li><a href="#the_retval_variable">The RETVAL Variable</a></li>
<li><a href="#returning_svs__avs_and_hvs_through_retval">Returning SVs, AVs and HVs through RETVAL</a></li>
<li><a href="#the_module_keyword">The MODULE Keyword</a></li>
<li><a href="#the_package_keyword">The PACKAGE Keyword</a></li>
<li><a href="#the_prefix_keyword">The PREFIX Keyword</a></li>
<li><a href="#the_output__keyword">The OUTPUT: Keyword</a></li>
<li><a href="#the_no_output_keyword">The NO_OUTPUT Keyword</a></li>
<li><a href="#the_code__keyword">The CODE: Keyword</a></li>
<li><a href="#the_init__keyword">The INIT: Keyword</a></li>
<li><a href="#the_no_init_keyword">The NO_INIT Keyword</a></li>
<li><a href="#initializing_function_parameters">Initializing Function Parameters</a></li>
<li><a href="#default_parameter_values">Default Parameter Values</a></li>
<li><a href="#the_preinit__keyword">The PREINIT: Keyword</a></li>
<li><a href="#the_scope__keyword">The SCOPE: Keyword</a></li>
<li><a href="#the_input__keyword">The INPUT: Keyword</a></li>
<li><a href="#the_in_outlist_in_outlist_out_in_out_keywords">The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords</a></li>
<li><a href="#the_length_name__keyword">The <a href="../../lib/Pod/perlfunc.html#item_length"><code>length(NAME)</code></a> Keyword</a></li>
<li><a href="#variablelength_parameter_lists">Variable-length Parameter Lists</a></li>
<li><a href="#the_c_args__keyword">The C_ARGS: Keyword</a></li>
<li><a href="#the_ppcode__keyword">The PPCODE: Keyword</a></li>
<li><a href="#returning_undef_and_empty_lists">Returning Undef And Empty Lists</a></li>
<li><a href="#the_require__keyword">The REQUIRE: Keyword</a></li>
<li><a href="#the_cleanup__keyword">The CLEANUP: Keyword</a></li>
<li><a href="#the_postcall__keyword">The POSTCALL: Keyword</a></li>
<li><a href="#the_boot__keyword">The BOOT: Keyword</a></li>
<li><a href="#the_versioncheck__keyword">The VERSIONCHECK: Keyword</a></li>
<li><a href="#the_prototypes__keyword">The PROTOTYPES: Keyword</a></li>
<li><a href="#the_prototype__keyword">The PROTOTYPE: Keyword</a></li>
<li><a href="#the_alias__keyword">The ALIAS: Keyword</a></li>
<li><a href="#the_overload__keyword">The OVERLOAD: Keyword</a></li>
<li><a href="#the_fallback__keyword">The FALLBACK: Keyword</a></li>
<li><a href="#the_interface__keyword">The INTERFACE: Keyword</a></li>
<li><a href="#the_interface_macro__keyword">The INTERFACE_MACRO: Keyword</a></li>
<li><a href="#the_include__keyword">The INCLUDE: Keyword</a></li>
<li><a href="#the_case__keyword">The CASE: Keyword</a></li>
<li><a href="#the___unary_operator">The & Unary Operator</a></li>
<li><a href="#inserting_pod__comments_and_c_preprocessor_directives">Inserting POD, Comments and C Preprocessor Directives</a></li>
<li><a href="#using_xs_with_c__">Using XS With C++</a></li>
<li><a href="#interface_strategy">Interface Strategy</a></li>
<li><a href="#perl_objects_and_c_structures">Perl Objects And C Structures</a></li>
<li><a href="#the_typemap">The Typemap</a></li>
<li><a href="#safely_storing_static_data_in_xs">Safely Storing Static Data in XS</a></li>
</ul>
<li><a href="#examples">EXAMPLES</a></li>
<li><a href="#xs_version">XS VERSION</a></li>
<li><a href="#author">AUTHOR</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>perlxs - XS language reference manual</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>
</p>
<h2><a name="introduction">Introduction</a></h2>
<p>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.</p>
<p>An <strong>XSUB</strong> forms the basic unit of the XS interface. After compilation
by the <strong>xsubpp</strong> compiler, each XSUB amounts to a C function definition
which will provide the glue between Perl calling conventions and C
calling conventions.</p>
<p>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.</p>
<p>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.</p>
<p>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 <em>description</em> of what should be done by
the glue, and let the XS compiler <strong>xsubpp</strong> handle the rest.</p>
<p>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 <code>h2xs</code>
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.</p>
<p>The XS compiler is called <strong>xsubpp</strong>. 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 <strong>typemaps</strong> to determine how to map C function parameters
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.</p>
<p>A file in XS format starts with a C language section which goes until the
first <code>MODULE =</code> 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. <strong>xsubpp</strong> recognizes and
skips POD (see <a href="../../lib/Pod/perlpod.html">the perlpod manpage</a>) in both the C and XS language sections, which
allows the XS file to contain embedded documentation.</p>
<p>See <a href="../../lib/Pod/perlxstut.html">the perlxstut manpage</a> for a tutorial on the whole extension creation process.</p>
<p>Note: For some extensions, Dave Beazley's SWIG system may provide a
significantly more convenient mechanism for creating the extension
glue code. See <a href="http://www.swig.org/">http://www.swig.org/</a> for more information.</p>
<p>
</p>
<h2><a name="on_the_road">On The Road</a></h2>
<p>Many of the examples which follow will concentrate on creating an interface
between Perl and the ONC+ RPC bind library functions. The <code>rpcb_gettime()</code>
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.</p>
<pre>
<span class="variable">bool_t</span> <span class="variable">rpcb_gettime</span><span class="operator">(</span><span class="variable">const</span> <span class="variable">char</span> <span class="variable">*host</span><span class="operator">,</span> <span class="variable">time_t</span> <span class="variable">*timep</span><span class="operator">);</span>
</pre>
<p>From C this function will be called with the following
statements.</p>
<pre>
<span class="comment">#include <rpc/rpc.h></span>
<span class="variable">bool_t</span> <span class="variable">status</span><span class="operator">;</span>
<span class="variable">time_t</span> <span class="variable">timep</span><span class="operator">;</span>
<span class="variable">status</span> <span class="operator">=</span> <span class="variable">rpcb_gettime</span><span class="operator">(</span> <span class="string">"localhost"</span><span class="operator">,</span> <span class="operator">&</span><span class="variable">timep</span> <span class="operator">);</span>
</pre>
<p>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.</p>
<pre>
<span class="keyword">use</span> <span class="variable">RPC</span><span class="operator">;</span>
<span class="variable">$status</span> <span class="operator">=</span> <span class="variable">rpcb_gettime</span><span class="operator">(</span> <span class="string">"localhost"</span><span class="operator">,</span> <span class="variable">$timep</span> <span class="operator">);</span>
</pre>
<p>The following XS file shows an XS subroutine, or XSUB, which
demonstrates one possible interface to the <code>rpcb_gettime()</code>
function. This XSUB represents a direct translation between
C and Perl and so preserves the interface even from Perl.
This XSUB will be invoked from Perl with the usage shown
above. Note that the first three #include statements, for
<code>EXTERN.h</code>, <code>perl.h</code>, and <code>XSUB.h</code>, will always be present at the
beginning of an XS file. This approach and others will be
⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?