perlapi.html
来自「perl教程」· HTML 代码 · 共 2,025 行 · 第 1/5 页
HTML
2,025 行
<?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>perlapi - autogenerated documentation for the perl public API</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>perlapi - autogenerated documentation for the perl public API</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>
<li><a href="#gimme_values">"Gimme" Values</a></li>
<li><a href="#array_manipulation_functions">Array Manipulation Functions</a></li>
<li><a href="#callback_functions">Callback Functions</a></li>
<li><a href="#character_classes">Character classes</a></li>
<li><a href="#cloning_an_interpreter">Cloning an interpreter</a></li>
<li><a href="#cv_manipulation_functions">CV Manipulation Functions</a></li>
<li><a href="#embedding_functions">Embedding Functions</a></li>
<li><a href="#functions_in_file_pp_pack_c">Functions in file pp_pack.c</a></li>
<li><a href="#global_variables">Global Variables</a></li>
<li><a href="#gv_functions">GV Functions</a></li>
<li><a href="#handy_values">Handy Values</a></li>
<li><a href="#hash_manipulation_functions">Hash Manipulation Functions</a></li>
<li><a href="#magical_functions">Magical Functions</a></li>
<li><a href="#memory_management">Memory Management</a></li>
<li><a href="#miscellaneous_functions">Miscellaneous Functions</a></li>
<li><a href="#numeric_functions">Numeric functions</a></li>
<li><a href="#optree_manipulation_functions">Optree Manipulation Functions</a></li>
<li><a href="#pad_data_structures">Pad Data Structures</a></li>
<li><a href="#stack_manipulation_macros">Stack Manipulation Macros</a></li>
<li><a href="#sv_flags">SV Flags</a></li>
<li><a href="#sv_manipulation_functions">SV Manipulation Functions</a></li>
<li><a href="#unicode_support">Unicode Support</a></li>
<li><a href="#variables_created_by_xsubpp_and_xsubpp_internal_functions">Variables created by <code>xsubpp</code> and <code>xsubpp</code> internal functions</a></li>
<li><a href="#warning_and_dieing">Warning and Dieing</a></li>
<li><a href="#authors">AUTHORS</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>perlapi - autogenerated documentation for the perl public API</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>This file contains the documentation of the perl public API generated by
embed.pl, specifically a listing of functions, macros, flags, and variables
that may be used by extension writers. The interfaces of any functions that
are not listed here are subject to change without notice. For this reason,
blindly using functions listed in proto.h is to be avoided when writing
extensions.</p>
<p>Note that all Perl API global variables must be referenced with the <code>PL_</code>
prefix. Some macros are provided for compatibility with the older,
unadorned names, but this support may be disabled in a future release.</p>
<p>The listing is alphabetical, case insensitive.</p>
<p>
</p>
<hr />
<h1><a name="gimme_values">"Gimme" Values</a></h1>
<dl>
<dt><strong><a name="item_gimme">GIMME</a></strong>
<dd>
<p>A backward-compatible version of <a href="#item_gimme_v"><code>GIMME_V</code></a> which can only return
<a href="#item_g_scalar"><code>G_SCALAR</code></a> or <a href="#item_g_array"><code>G_ARRAY</code></a>; in a void context, it returns <a href="#item_g_scalar"><code>G_SCALAR</code></a>.
Deprecated. Use <a href="#item_gimme_v"><code>GIMME_V</code></a> instead.</p>
</dd>
<dd>
<pre>
U32 GIMME</pre>
</dd>
</li>
<dt><strong><a name="item_gimme_v">GIMME_V</a></strong>
<dd>
<p>The XSUB-writer's equivalent to Perl's <a href="../../lib/Pod/perlfunc.html#item_wantarray"><code>wantarray</code></a>. Returns <a href="#item_g_void"><code>G_VOID</code></a>,
<a href="#item_g_scalar"><code>G_SCALAR</code></a> or <a href="#item_g_array"><code>G_ARRAY</code></a> for void, scalar or list context,
respectively.</p>
</dd>
<dd>
<pre>
U32 GIMME_V</pre>
</dd>
</li>
<dt><strong><a name="item_g_array">G_ARRAY</a></strong>
<dd>
<p>Used to indicate list context. See <a href="#item_gimme_v"><code>GIMME_V</code></a>, <a href="#item_gimme"><code>GIMME</code></a> and
<a href="../../lib/Pod/perlcall.html">the perlcall manpage</a>.</p>
</dd>
</li>
<dt><strong><a name="item_g_discard">G_DISCARD</a></strong>
<dd>
<p>Indicates that arguments returned from a callback should be discarded. See
<a href="../../lib/Pod/perlcall.html">the perlcall manpage</a>.</p>
</dd>
</li>
<dt><strong><a name="item_g_eval">G_EVAL</a></strong>
<dd>
<p>Used to force a Perl <a href="../../lib/Pod/perlfunc.html#item_eval"><code>eval</code></a> wrapper around a callback. See
<a href="../../lib/Pod/perlcall.html">the perlcall manpage</a>.</p>
</dd>
</li>
<dt><strong><a name="item_g_noargs">G_NOARGS</a></strong>
<dd>
<p>Indicates that no arguments are being sent to a callback. See
<a href="../../lib/Pod/perlcall.html">the perlcall manpage</a>.</p>
</dd>
</li>
<dt><strong><a name="item_g_scalar">G_SCALAR</a></strong>
<dd>
<p>Used to indicate scalar context. See <a href="#item_gimme_v"><code>GIMME_V</code></a>, <a href="#item_gimme"><code>GIMME</code></a>, and
<a href="../../lib/Pod/perlcall.html">the perlcall manpage</a>.</p>
</dd>
</li>
<dt><strong><a name="item_g_void">G_VOID</a></strong>
<dd>
<p>Used to indicate void context. See <a href="#item_gimme_v"><code>GIMME_V</code></a> and <a href="../../lib/Pod/perlcall.html">the perlcall manpage</a>.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="array_manipulation_functions">Array Manipulation Functions</a></h1>
<dl>
<dt><strong><a name="item_avfill">AvFILL</a></strong>
<dd>
<p>Same as <a href="#item_av_len"><code>av_len()</code></a>. Deprecated, use <a href="#item_av_len"><code>av_len()</code></a> instead.</p>
</dd>
<dd>
<pre>
int AvFILL(AV* av)</pre>
</dd>
</li>
<dt><strong><a name="item_av_clear">av_clear</a></strong>
<dd>
<p>Clears an array, making it empty. Does not free the memory used by the
array itself.</p>
</dd>
<dd>
<pre>
void av_clear(AV* ar)</pre>
</dd>
</li>
<dt><strong><a name="item_av_delete">av_delete</a></strong>
<dd>
<p>Deletes the element indexed by <code>key</code> from the array. Returns the
deleted element. If <a href="../../lib/Pod/perlfunc.html#item_flags"><code>flags</code></a> equals <a href="#item_g_discard"><code>G_DISCARD</code></a>, the element is freed
and null is returned.</p>
</dd>
<dd>
<pre>
SV* av_delete(AV* ar, I32 key, I32 flags)</pre>
</dd>
</li>
<dt><strong><a name="item_av_exists">av_exists</a></strong>
<dd>
<p>Returns true if the element indexed by <code>key</code> has been initialized.</p>
</dd>
<dd>
<p>This relies on the fact that uninitialized array elements are set to
<code>&PL_sv_undef</code>.</p>
</dd>
<dd>
<pre>
bool av_exists(AV* ar, I32 key)</pre>
</dd>
</li>
<dt><strong><a name="item_av_extend">av_extend</a></strong>
<dd>
<p>Pre-extend an array. The <code>key</code> is the index to which the array should be
extended.</p>
</dd>
<dd>
<pre>
void av_extend(AV* ar, I32 key)</pre>
</dd>
</li>
<dt><strong><a name="item_av_fetch">av_fetch</a></strong>
<dd>
<p>Returns the SV at the specified index in the array. The <code>key</code> is the
index. If <code>lval</code> is set then the fetch will be part of a store. Check
that the return value is non-null before dereferencing it to a <code>SV*</code>.</p>
</dd>
<dd>
<p>See <a href="../../lib/Pod/perlguts.html#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage</a> for
more information on how to use this function on tied arrays.</p>
</dd>
<dd>
<pre>
SV** av_fetch(AV* ar, I32 key, I32 lval)</pre>
</dd>
</li>
<dt><strong><a name="item_av_fill">av_fill</a></strong>
<dd>
<p>Ensure than an array has a given number of elements, equivalent to
Perl's <code>$#array = $fill;</code>.</p>
</dd>
<dd>
<pre>
void av_fill(AV* ar, I32 fill)</pre>
</dd>
</li>
<dt><strong><a name="item_av_len">av_len</a></strong>
<dd>
<p>Returns the highest index in the array. Returns -1 if the array is
empty.</p>
</dd>
<dd>
<pre>
I32 av_len(AV* ar)</pre>
</dd>
</li>
<dt><strong><a name="item_av_make">av_make</a></strong>
<dd>
<p>Creates a new AV and populates it with a list of SVs. The SVs are copied
into the array, so they may be freed after the call to av_make. The new AV
will have a reference count of 1.</p>
</dd>
<dd>
<pre>
AV* av_make(I32 size, SV** svp)</pre>
</dd>
</li>
<dt><strong><a name="item_av_pop">av_pop</a></strong>
<dd>
<p>Pops an SV off the end of the array. Returns <code>&PL_sv_undef</code> if the array
is empty.</p>
</dd>
<dd>
<pre>
SV* av_pop(AV* ar)</pre>
</dd>
</li>
<dt><strong><a name="item_av_push">av_push</a></strong>
<dd>
<p>Pushes an SV onto the end of the array. The array will grow automatically
to accommodate the addition.</p>
</dd>
<dd>
<pre>
void av_push(AV* ar, SV* val)</pre>
</dd>
</li>
<dt><strong><a name="item_av_shift">av_shift</a></strong>
<dd>
<p>Shifts an SV off the beginning of the array.</p>
</dd>
<dd>
<pre>
SV* av_shift(AV* ar)</pre>
</dd>
</li>
<dt><strong><a name="item_av_store">av_store</a></strong>
<dd>
<p>Stores an SV in an array. The array index is specified as <code>key</code>. The
return value will be NULL if the operation failed or if the value did not
need to be actually stored within the array (as in the case of tied
arrays). Otherwise it can be dereferenced to get the original <code>SV*</code>. Note
that the caller is responsible for suitably incrementing the reference
count of <code>val</code> before the call, and decrementing it if the function
returned NULL.</p>
</dd>
<dd>
<p>See <a href="../../lib/Pod/perlguts.html#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays in the perlguts manpage</a> for
more information on how to use this function on tied arrays.</p>
</dd>
<dd>
<pre>
SV** av_store(AV* ar, I32 key, SV* val)</pre>
</dd>
</li>
<dt><strong><a name="item_av_undef">av_undef</a></strong>
<dd>
<p>Undefines the array. Frees the memory used by the array itself.</p>
</dd>
<dd>
<pre>
void av_undef(AV* ar)</pre>
</dd>
</li>
<dt><strong><a name="item_av_unshift">av_unshift</a></strong>
<dd>
<p>Unshift the given number of <a href="../../lib/Pod/perlfunc.html#item_undef"><code>undef</code></a> values onto the beginning of the
array. The array will grow automatically to accommodate the addition. You
must then use <a href="#item_av_store"><code>av_store</code></a> to assign values to these new elements.</p>
</dd>
<dd>
<pre>
void av_unshift(AV* ar, I32 num)</pre>
</dd>
</li>
<dt><strong><a name="item_get_av">get_av</a></strong>
<dd>
<p>Returns the AV of the specified Perl array. If <code>create</code> is set and the
Perl variable does not exist then it will be created. If <code>create</code> is not
set and the variable does not exist then NULL is returned.</p>
</dd>
<dd>
<p>NOTE: the perl_ form of this function is deprecated.</p>
</dd>
<dd>
<pre>
AV* get_av(const char* name, I32 create)</pre>
</dd>
</li>
<dt><strong><a name="item_newav">newAV</a></strong>
<dd>
<p>Creates a new AV. The reference count is set to 1.</p>
</dd>
<dd>
<pre>
AV* newAV()</pre>
</dd>
</li>
<dt><strong><a name="item_sortsv">sortsv</a></strong>
<dd>
<p>Sort an array. Here is an example:</p>
</dd>
<dd>
<pre>
<span class="variable">sortsv</span><span class="operator">(</span><span class="variable">AvARRAY</span><span class="operator">(</span><span class="variable">av</span><span class="operator">),</span> <span class="variable">av_len</span><span class="operator">(</span><span class="variable">av</span><span class="operator">)+</span><span class="number">1</span><span class="operator">,</span> <span class="variable">Perl_sv_cmp_locale</span><span class="operator">);</span>
</pre>
</dd>
<dd>
<p>See lib/sort.pm for details about controlling the sorting algorithm.</p>
</dd>
<dd>
<pre>
void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)</pre>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="callback_functions">Callback Functions</a></h1>
<dl>
<dt><strong><a name="item_call_argv">call_argv</a></strong>
<dd>
<p>Performs a callback to the specified Perl sub. See <a href="../../lib/Pod/perlcall.html">the perlcall manpage</a>.</p>
</dd>
<dd>
<p>NOTE: the perl_ form of this function is deprecated.</p>
</dd>
<dd>
<pre>
I32 call_argv(const char* sub_name, I32 flags, char** argv)</pre>
</dd>
</li>
<dt><strong><a name="item_call_method">call_method</a></strong>
<dd>
<p>Performs a callback to the specified Perl method. The blessed object must
be on the stack. See <a href="../../lib/Pod/perlcall.html">the perlcall manpage</a>.</p>
</dd>
<dd>
<p>NOTE: the perl_ form of this function is deprecated.</p>
</dd>
<dd>
⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?