=head1 NAME
-perlapi - Perl 5 application programming interface for C extensions
+perlapi - autogenerated documentation for the perl public API
=head1 DESCRIPTION
-=head2 Introduction
-
-XS is a language used to create an extension interface
-between Perl and some C library which one wishes to use with
-Perl. The XS interface is combined with the library to
-create a new library which can be linked to Perl. An B<XSUB>
-is a function in the XS language and is the core component
-of the Perl application interface.
-
-The XS compiler is called B<xsubpp>. This compiler will embed
-the constructs necessary to let an XSUB, which is really a C
-function in disguise, manipulate Perl values and creates the
-glue necessary to let Perl access the XSUB. The compiler
-uses B<typemaps> to determine how to map C function parameters
-and variables to Perl values. The default typemap handles
-many common C types. A supplement typemap must be created
-to handle special structures and types for the library being
-linked.
-
-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.
-
- bool_t rpcb_gettime(const char *host, time_t *timep);
-
-From C this function will be called with the following
-statements.
-
- #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_gettime()
-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
-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.
-
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
- #include <rpc/rpc.h>
-
- MODULE = RPC PACKAGE = RPC
-
- bool_t
- rpcb_gettime(host,timep)
- char * host
- time_t &timep
- OUTPUT:
- 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 program 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 C<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;
- 1;
-
-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 different 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 parameters. This abstraction will
-allow the programmer to create a more Perl-like interface to the C
-function.
-
-It is recommended that the B<h2xs> tool be used when creating new
-extensions. This tool will generate template source files and Makefiles.
-This is discussed in more detail in the section titled "Creating A New
-Extension" and in the B<h2xs> manpage.
-
-=head2 The Anatomy of an XSUB
-
-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
- sin(x)
- double<tab>x
-
-The compiler expects a tab between the parameter name and its type, and
-any or no whitespace before the type. When using C pointers the
-indirection operator C<*> should be considered part of the type and the
-address operator C<&> should be considered part of the variable, as is
-demonstrated in the rpcb_gettime() function above. See the section on
-typemaps for more about handling qualifiers and unary operators in C
-types.
-
-The parameter list of a function must not have whitespace
-after the open-parenthesis or before the close-parenthesis.
-
- INCORRECT CORRECT
+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.
- double double
- sin( x ) sin(x)
- double x double x
+Note that all Perl API global variables must be referenced with the C<PL_>
+prefix. Some macros are provided for compatibility with the older,
+unadorned names, but this support may be disabled in a future release.
-The function name and the return type must be placed on
-separate lines.
-
- INCORRECT CORRECT
-
- double sin(x) double
- double x sin(x)
- double x
-
-=head2 The Argument Stack
-
-The argument stack is used to store the values which are
-sent as parameters to the XSUB and to store the XSUB's
-return value. In reality all Perl functions keep their
-values on this stack at the same time, each limited to its
-own range of positions on the stack. In this document the
-first position on that stack which belongs to the active
-function will be referred to as position 0 for that function.
-
-XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<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 outgoing return values always begin at ST(0). For many
-simple cases the B<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 programmer must supply the code.
-
-=head2 The RETVAL Variable
-
-The RETVAL variable is a magic variable which always matches
-the return type of the C library function. The B<xsubpp> compiler will
-supply this variable in each XSUB and by default will use it 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 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.
-
-=head2 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
-untouched. Every XS module will have a bootstrap function
-which is used to hook the XSUBs into Perl. The package name
-of this bootstrap function will match the value of the last
-MODULE statement in the XS source files. The value of
-MODULE should always remain constant within the same XS
-file, though this is not required.
+The listing is alphabetical, case insensitive.
-The following example will start the XS code and will place
-all functions in a package named RPC.
+=over 8
- MODULE = RPC
-
-=head2 The PACKAGE Keyword
-
-When functions within an XS source file must be separated 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
+=item AvFILL
- [ XS code in package RPC ]
+Same as C<av_len()>. Deprecated, use C<av_len()> instead.
- MODULE = RPC PACKAGE = RPCB
+ int AvFILL(AV* av)
- [ XS code in package RPCB ]
+=for hackers
+Found in file av.h
- MODULE = RPC PACKAGE = RPC
-
- [ XS code in package RPC ]
-
-Although this keyword is optional and in some cases provides redundant
-information it should always be used. This keyword will ensure that the
-XSUBs appear in the desired package.
-
-=head2 The PREFIX Keyword
-
-The PREFIX keyword designates prefixes which should be
-removed from the Perl function names. If the C function is
-C<rpcb_gettime()> and the PREFIX value is C<rpcb_> then Perl will
-see this function as C<gettime()>.
-
-This keyword should follow the PACKAGE keyword when used.
-If PACKAGE is not used then PREFIX should follow the MODULE
-keyword.
+=item av_clear
- MODULE = RPC PREFIX = rpc_
-
- MODULE = RPC PACKAGE = RPCB PREFIX = rpcb_
-
-=head2 The OUTPUT: Keyword
-
-The OUTPUT: keyword indicates that certain function parameters 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 functions, such as the sin() function above, the RETVAL variable is
-automatically designated as an output value. In more complex functions
-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.
-The RETVAL variable is not recognized as an output variable when the
-CODE: keyword is present. The OUTPUT: keyword is used in this
-situation to tell the compiler that RETVAL really is an output
-variable.
-
-The OUTPUT: keyword can also be used to indicate that function parameters
-are output variables. This may be necessary when a parameter has been
-modified within the function and the programmer would like the update to
-be seen by Perl. If function parameters are listed under OUTPUT: along
-with the RETVAL variable then the RETVAL variable must be the last one
-listed.
-
- bool_t
- rpcb_gettime(host,timep)
- char * host
- time_t &timep
- OUTPUT:
- timep
-
-The OUTPUT: keyword will also allow an output parameter to
-be mapped to a matching piece of code rather than to a
-typemap.
-
- bool_t
- rpcb_gettime(host,timep)
- char * host
- time_t &timep
- OUTPUT:
- timep<tab>sv_setnv(ST(1), (double)timep);
-
-=head2 The CODE: Keyword
-
-This keyword is used in more complicated XSUBs which require
-special handling for the C function. The RETVAL variable is
-available but will not be returned unless it is specified
-under the OUTPUT: keyword.
-
-The following XSUB is for a C function which requires special handling of
-its parameters. The Perl usage is given first.
-
- $status = rpcb_gettime( "localhost", $timep );
-
-The XSUB follows.
-
- bool_t
- rpcb_gettime(host,timep)
- char * host
- time_t timep
- CODE:
- RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
- timep
- RETVAL
-
-In many of the examples shown here the CODE: block (and
-other blocks) will often be contained within braces ( C<{> and
-C<}> ). This protects the CODE: block from complex INPUT
-typemaps and ensures the resulting C code is legal.
-
-=head2 The NO_INIT Keyword
-
-The NO_INIT keyword is used to indicate that a function
-parameter is being used as only an output value. The B<xsubpp>
-compiler will normally generate code to read the values of
-all function parameters from the argument stack and assign
-them to C variables upon entry to the function. NO_INIT
-will tell the compiler that some parameters will be used for
-output rather than for input and that they will be handled
-before the function terminates.
-
-The following example shows a variation of the rpcb_gettime() function.
-This function uses the timep variable as only an output variable and does
-not care about its initial contents.
-
- bool_t
- rpcb_gettime(host,timep)
- char * host
- time_t &timep = NO_INIT
- OUTPUT:
- timep
-
-=head2 Initializing Function Parameters
-
-Function parameters are normally initialized with their
-values from the argument stack. The typemaps contain the
-code segments which are used to transfer the Perl values to
-the C parameters. The programmer, however, is allowed to
-override the typemaps and supply alternate initialization
-code.
-
-The following code demonstrates how to supply initialization code for
-function parameters. The initialization code is eval'd by the compiler
-before it is added to the output so anything which should be interpreted
-literally, such as double quotes, must be protected with backslashes.
-
- bool_t
- rpcb_gettime(host,timep)
- char * host = (char *)SvPV(ST(0),na);
- time_t &timep = 0;
- OUTPUT:
- timep
-
-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.
-
-=head2 Default Parameter Values
-
-Default values can be specified for function parameters by
-placing an assignment statement in the parameter list. The
-default value may be a number or a string. 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. Perl will call this
-XSUB with either of the following statements.
-
- $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() function with
-the parameters in the correct order for that function.
-
- bool_t
- rpcb_gettime(timep,host="localhost")
- char * host
- time_t timep = NO_INIT
- CODE:
- RETVAL = rpcb_gettime( host, &timep );
- OUTPUT:
- timep
- RETVAL
-
-=head2 Variable-length Parameter Lists
-
-XSUBs can have variable-length parameter lists by specifying an ellipsis
-C<(...)> 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 C<items> variable which the
-B<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 I<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 should
-be able to call this XSUB with either of the following statements.
-
- $status = rpcb_gettime( $timep, $host );
-
- $status = rpcb_gettime( $timep );
-
-The XS code, with ellipsis, follows.
-
- bool_t
- rpcb_gettime(timep, ...)
- time_t timep = NO_INIT
- CODE:
- {
- char *host = "localhost";
-
- if( items > 1 )
- host = (char *)SvPV(ST(1), na);
- RETVAL = rpcb_gettime( host, &timep );
- }
- OUTPUT:
- timep
- RETVAL
-
-=head2 The PPCODE: Keyword
-
-The PPCODE: keyword is an alternate form of the CODE: keyword and is used
-to tell the B<xsubpp> compiler that the programmer 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 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 are not used
-together within the same XSUB.
-
-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.
-
- void
- rpcb_gettime(host)
- char * host
- PPCODE:
- {
- time_t timep;
- bool_t status;
- status = rpcb_gettime( host, &timep );
- EXTEND(sp, 2);
- PUSHs(sv_2mortal(newSVnv(status)));
- PUSHs(sv_2mortal(newSVnv(timep)));
- }
-
-Notice that the programmer must supply the C code necessary
-to have the real rpcb_gettime() function called and to have
-the return values properly placed on the argument stack.
-
-The C<void> return type for this function tells the B<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:
-directive.
-
-The EXTEND() macro is used to make room on the argument
-stack for 2 return values. The PPCODE: directive causes the
-B<xsubpp> compiler to create a stack pointer called C<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");
-
-=head2 Returning Undef And Empty Lists
-
-Occasionally the programmer will want to simply return
-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
-to have it return the time and if it fails we would like to
-have undef returned. In the following Perl code the value
-of $timep will either be undef or it will be a valid time.
-
- $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
-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
- rpcb_gettime(host)
- char * host
- CODE:
- {
- 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.
-
- void
- rpcb_gettime(host)
- char * host
- CODE:
- {
- time_t timep;
- bool_t x;
- ST(0) = sv_newmortal();
- if( rpcb_gettime( host, &timep ) ){
- sv_setnv( ST(0), (double)timep);
- }
- else{
- ST(0) = &sv_undef;
- }
- }
-
-To return an empty list one must use a PPCODE: block and
-then not push return values on the stack.
-
- void
- rpcb_gettime(host)
- char * host
- PPCODE:
- {
- time_t timep;
- if( rpcb_gettime( host, &timep ) )
- PUSHs(sv_2mortal(newSVnv(timep)));
- else{
- /* Nothing pushed on stack, so an empty */
- /* list is implicitly returned. */
- }
- }
-
-=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.
-
-=head2 The BOOT: Keyword
-
-The BOOT: keyword is used to add code to the extension's bootstrap
-function. The bootstrap function is generated by the B<xsubpp> compiler and
-normally holds the statements necessary to register any XSUBs with Perl.
-With the BOOT: keyword the programmer can tell the compiler to add extra
-statements to the bootstrap function.
-
-This keyword may be used any time after the first MODULE keyword and should
-appear on a line by itself. The first blank line after the keyword will
-terminate the code block.
-
- BOOT:
- # The following message will be printed when the
- # bootstrap function executes.
- printf("Hello from the bootstrap!\n");
-
-=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.
-
-=head2 Using XS With C++
-
-If a function is defined as a C++ method then it will assume
-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_setptrobj() macro. The
-blessing of the object by Perl can be handled by the
-T_PTROBJ typemap.
-
-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.
-
-=head2 Perl Variables
-
-The following demonstrates how the Perl variable $host can
-be accessed from an XSUB. The function B<perl_get_sv()> is
-used to obtain a pointer to the variable, known as an B<SV>
-(Scalar Variable) internally. The package name C<RPC> will be
-added to the name of the variable so perl_get_sv() will know
-in which package $host can be found. If the package name is
-not supplied then perl_get_sv() will search package C<main> for
-the variable. The macro B<SvPVX()> is then used to dereference
-the SV to obtain a C<char*> pointer to its contents.
-
- void
- rpcb_gettime()
- PPCODE:
- {
- char *host;
- SV *hostsv;
- time_t timep;
-
- hostsv = perl_get_sv( "RPC::host", FALSE );
- if( hostsv != NULL ){
- host = SvPVX( hostsv );
- if( rpcb_gettime( host, &timep ) )
- PUSHs(sv_2mortal(newSVnv(timep)));
- }
- }
-
-This Perl code can be used to call that XSUB.
-
- $RPC::host = "localhost";
- $timep = rpcb_gettime();
-
-In the above example the SV contained a C C<char*> but a Perl
-scalar variable may also contain numbers and references. If
-the SV is expected to have a C C<int> then the macro B<SvIVX()>
-should be used to dereference the SV. When the SV contains
-a C double then B<SvNVX()> should be used.
-
-The macro B<SvRV()> can be used to dereference an SV when it is a Perl
-reference. The result will be another SV which points to the actual Perl
-variable. This can then be dereferenced with SvPVX(), SvNVX(), or
-SvIVX(). The following XSUB will use SvRV().
-
- void
- rpcb_gettime()
- PPCODE:
- {
- char *host;
- SV *rv;
- SV *hostsv;
- time_t timep;
-
- rv = perl_get_sv( "RPC::host", FALSE );
- if( rv != NULL ){
- hostsv = SvRV( rv );
- host = SvPVX( hostsv );
- if( rpcb_gettime( host, &timep ) )
- PUSHs(sv_2mortal(newSVnv(timep)));
- }
- }
-
-This Perl code will create a variable $RPC::host which is a
-reference to $MY::host. The variable $MY::host contains the
-hostname which will be used.
-
- $MY::host = "localhost";
- $RPC::host = \$MY::host;
- $timep = rpcb_gettime();
-
-The second argument to perl_get_sv() will normally be B<FALSE>
-as shown in the above examples. An argument of B<TRUE> will
-cause variables to be created if they do not already exist.
-One should not use TRUE unless steps are taken to deal with
-a possibly empty SV.
-
-XSUBs may use B<perl_get_av()>, B<perl_get_hv()>, and B<perl_get_cv()> to
-access Perl arrays, hashes, and code values.
-
-=head2 Interface Strategy
-
-When designing an interface between Perl and a C library a straight
-translation from C to XS is often sufficient. The interface will often be
-very C-like and occasionally nonintuitive, especially when the C function
-modifies one of its parameters. In cases where the programmer wishes to
-create a more Perl-like interface the following strategy may help to
-identify the more critical parts of the interface.
-
-Identify the C functions which modify their parameters. The XSUBs for
-these functions may be able to return lists to Perl, or may be
-candidates to return undef or an empty list in case of failure.
-
-Identify which values are used by only the C and XSUB functions
-themselves. 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 can be handled in XS with the & unary operator on
-the variable name while others will require the use of the * operator on
-the type name. In general it is easier to work with the & operator.
-
-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.
-
-=head2 The Perl Module
-
-The Perl module is the link between the extension library,
-which was generated from XS code, and the Perl interpreter.
-The module is used to tell Perl what the extension library
-contains. The name and package of the module should match
-the name of the library.
-
-The following is a Perl module for an extension containing
-some ONC+ RPC bind library functions.
-
- package RPC;
-
- require Exporter;
- require DynaLoader;
- @ISA = qw(Exporter DynaLoader);
- @EXPORT = qw( rpcb_gettime rpcb_getmaps rpcb_getaddr
- rpcb_rmtcall rpcb_set rpcb_unset );
-
- bootstrap RPC;
- 1;
-
-The RPC extension contains the functions found in the
-@EXPORT list. By using the C<Exporter> module the RPC module
-can make these function names visible to the rest of the
-Perl program. The C<DynaLoader> module will allow the RPC
-module to bootstrap the extension library. To load this
-extension and make the functions available, the following
-Perl statement should be used.
-
- use RPC;
-
-For more information about the DynaLoader consult its documentation in the
-ext/DynaLoader directory in the Perl source.
-
-=head2 Perl Objects And C Structures
-
-When dealing with C structures one should select either
-B<T_PTROBJ> or B<T_PTRREF> for the XS type. Both types are
-designed to handle pointers to complex objects. The
-T_PTRREF type will allow the Perl object to be unblessed
-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 B<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 C<typedef> will be created for C<struct netconfig>. The Perl
-object will be blessed in a class matching the name of the C
-type, with the tag C<Ptr> appended, and the name should not
-have embedded spaces if it will be a Perl package name. The
-destructor will be placed in a class corresponding 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 *
- getnetconfigent(netid)
- char * netid
-
- MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
-
- void
- rpcb_DESTROY(netconf)
- Netconfig * netconf
- CODE:
- printf("Now in NetconfigPtr::DESTROY\n");
- free( netconf );
-
-This example requires the following typemap entry. Consult the typemap
-section for more information about adding new typemaps for an extension.
-
- TYPEMAP
- Netconfig * T_PTROBJ
-
-This example will be used with the following Perl statements.
-
- use RPC;
- $netconf = getnetconfigent("udp");
-
-When Perl destroys the object referenced by $netconf it will send the
-object to the supplied XSUB DESTROY function. Perl cannot determine, and
-does not care, that this object is a C struct and not a Perl object. In
-this sense, there is no difference between the object created by the
-getnetconfigent() XSUB and an object created by a normal Perl subroutine.
-
-=head2 C Headers and Perl
-
-The B<h2xs> compiler is designed to convert C header files in
-/usr/include into Perl extensions. This compiler will
-create a directory under the C<ext> directory of the Perl
-source and will populate it with a Makefile, a Perl Module,
-an XS source file, and a MANIFEST file.
-
-The following command will create an extension called C<Rusers>
-from the <rpcsvc/rusers.h> header.
-
- h2xs rpcsvc/rusers
-
-When the Rusers extension has been compiled and installed
-Perl can use it to retrieve any C<#define> statements which
-were in the C header.
-
- use Rusers;
- print "RPC program number for rusers service: ";
- print &RUSERSPROG, "\n";
-
-=head2 Creating A New Extension
-
-The B<h2xs> compiler can generate template source files and
-Makefiles. These templates offer a suitable starting point
-for most extensions. The following example demonstrates how
-one might use B<h2xs> to create an extension containing the RPC
-functions in this document.
-
-The extension will not use autoloaded functions and will not define
-constants, so the B<-A> option will be given to B<h2xs>. When run from the
-Perl source directory, the B<h2xs> compiler will create the directory
-ext/RPC and will populate it with files called RPC.xs, RPC.pm, Makefile.PL,
-and MANIFEST. The XS code for the RPC functions should be added to the
-RPC.xs file. The @EXPORT list in RPC.pm should be updated to include the
-functions from RPC.xs.
-
- h2xs -An RPC
-
-To compile the extension for dynamic loading the following
-command should be executed from the ext/RPC directory.
-
- make dynamic
-
-If the extension will be statically linked into the Perl
-binary then the makefile (use C<makefile>, not C<Makefile>) in the
-Perl source directory should be edited to add C<ext/RPC/RPC.a>
-to the C<static_ext> variable. Before making this change Perl
-should have already been built. After the makefile has been
-updated the following command should be executed from the
-Perl source directory.
-
- make
-
-Perl's B<Configure> script can also be used to add extensions. The extension
-should be placed in the C<ext> directory under the Perl source before Perl
-has been built and prior to running Configure. When Configure is run it
-will find the extension along with the other extensions in the C<ext>
-directory and will add it to the list of extensions to be built. When make
-is run the extension will be built along with the other extensions.
+Clears an array, making it empty. Does not free the memory used by the
+array itself.
-Configure recognizes extensions if they have an XS source
-file which matches the name of the extension directory. If
-the extension directory includes a MANIFEST file Configure
-will search that file for any B<.SH> files and extract them
-after it extracts all the other .SH files listed in the main
-MANIFEST. The main Perl Makefile will then run B<make> in the
-extension's directory if it finds an XS file matching the
-name of the extension's directory.
+ void av_clear(AV* ar)
-=head2 The Typemap
+=for hackers
+Found in file av.c
-The typemap is a collection of code fragments which are used by the B<xsubpp>
-compiler to map C function parameters and values to Perl values. The
-typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and
-C<OUTPUT>. 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.
-Each of the sections of the typemap must be preceded by one of the TYPEMAP,
-INPUT, or OUTPUT keywords.
+=item av_delete
-The default typemap in the C<ext> 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 B<xsubpp> compiler will allow the extension's own typemap to
-override any mappings which are in the default typemap.
+Deletes the element indexed by C<key> from the array. Returns the
+deleted element. C<flags> is currently ignored.
-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 earlier 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 getnetconfigent() is shown
-here. Note that the C type is separated from the XS type with a tab and
-that the C unary operator C<*> is considered to be a part of the C type name.
+ SV* av_delete(AV* ar, I32 key, I32 flags)
- TYPEMAP
- Netconfig *<tab>T_PTROBJ
+=for hackers
+Found in file av.c
-=head1 EXAMPLES
-
-File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
+=item av_exists
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
+Returns true if the element indexed by C<key> has been initialized.
- #include <rpc/rpc.h>
+This relies on the fact that uninitialized array elements are set to
+C<&PL_sv_undef>.
- typedef struct netconfig Netconfig;
+ bool av_exists(AV* ar, I32 key)
- MODULE = RPC PACKAGE = RPC
-
- void
- rpcb_gettime(host="localhost")
- char * host
- CODE:
- {
- time_t timep;
- ST(0) = sv_newmortal();
- if( rpcb_gettime( host, &timep ) )
- sv_setnv( ST(0), (double)timep );
- }
-
- Netconfig *
- getnetconfigent(netid="udp")
- char * netid
-
- MODULE = RPC PACKAGE = NetconfigPtr PREFIX = rpcb_
-
- void
- rpcb_DESTROY(netconf)
- Netconfig * netconf
- CODE:
- printf("NetconfigPtr::DESTROY\n");
- free( netconf );
+=for hackers
+Found in file av.c
-File C<typemap>: Custom typemap for RPC.xs.
+=item av_extend
- TYPEMAP
- Netconfig * T_PTROBJ
-
-File C<RPC.pm>: Perl module for the RPC extension.
-
- package RPC;
-
- require Exporter;
- require DynaLoader;
- @ISA = qw(Exporter DynaLoader);
- @EXPORT = qw(rpcb_gettime getnetconfigent);
+Pre-extend an array. The C<key> is the index to which the array should be
+extended.
- bootstrap RPC;
- 1;
-
-File C<rpctest.pl>: Perl test program for the RPC extension.
+ void av_extend(AV* ar, I32 key)
- use RPC;
+=for hackers
+Found in file av.c
- $netconf = getnetconfigent();
- $a = rpcb_gettime();
- print "time = $a\n";
- print "netconf = $netconf\n";
+=item av_fetch
- $netconf = getnetconfigent("tcp");
- $a = rpcb_gettime("poplar");
- print "time = $a\n";
- print "netconf = $netconf\n";
+Returns the SV at the specified index in the array. The C<key> is the
+index. If C<lval> is set then the fetch will be part of a store. Check
+that the return value is non-null before dereferencing it to a C<SV*>.
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
+more information on how to use this function on tied arrays.
-=head1 AUTHOR
+ SV** av_fetch(AV* ar, I32 key, I32 lval)
+
+=for hackers
+Found in file av.c
+
+=item av_fill
+
+Ensure than an array has a given number of elements, equivalent to
+Perl's C<$#array = $fill;>.
+
+ void av_fill(AV* ar, I32 fill)
+
+=for hackers
+Found in file av.c
+
+=item av_len
+
+Returns the highest index in the array. Returns -1 if the array is
+empty.
+
+ I32 av_len(AV* ar)
+
+=for hackers
+Found in file av.c
+
+=item av_make
+
+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.
+
+ AV* av_make(I32 size, SV** svp)
+
+=for hackers
+Found in file av.c
+
+=item av_pop
+
+Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
+is empty.
+
+ SV* av_pop(AV* ar)
+
+=for hackers
+Found in file av.c
+
+=item av_push
+
+Pushes an SV onto the end of the array. The array will grow automatically
+to accommodate the addition.
+
+ void av_push(AV* ar, SV* val)
+
+=for hackers
+Found in file av.c
+
+=item av_shift
+
+Shifts an SV off the beginning of the array.
+
+ SV* av_shift(AV* ar)
+
+=for hackers
+Found in file av.c
+
+=item av_store
+
+Stores an SV in an array. The array index is specified as C<key>. 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 C<SV*>. Note
+that the caller is responsible for suitably incrementing the reference
+count of C<val> before the call, and decrementing it if the function
+returned NULL.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
+more information on how to use this function on tied arrays.
+
+ SV** av_store(AV* ar, I32 key, SV* val)
+
+=for hackers
+Found in file av.c
+
+=item av_undef
+
+Undefines the array. Frees the memory used by the array itself.
+
+ void av_undef(AV* ar)
+
+=for hackers
+Found in file av.c
+
+=item av_unshift
+
+Unshift the given number of C<undef> values onto the beginning of the
+array. The array will grow automatically to accommodate the addition. You
+must then use C<av_store> to assign values to these new elements.
+
+ void av_unshift(AV* ar, I32 num)
+
+=for hackers
+Found in file av.c
+
+=item bytes_to_utf8
+
+Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
+Returns a pointer to the newly-created string, and sets C<len> to
+reflect the new length.
+
+ U8 * bytes_to_utf8(U8 *s, STRLEN *len)
+
+=for hackers
+Found in file utf8.c
+
+=item call_argv
+
+Performs a callback to the specified Perl sub. See L<perlcall>.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ I32 call_argv(const char* sub_name, I32 flags, char** argv)
+
+=for hackers
+Found in file perl.c
+
+=item call_method
+
+Performs a callback to the specified Perl method. The blessed object must
+be on the stack. See L<perlcall>.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ I32 call_method(const char* methname, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item call_pv
+
+Performs a callback to the specified Perl sub. See L<perlcall>.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ I32 call_pv(const char* sub_name, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item call_sv
+
+Performs a callback to the Perl sub whose name is in the SV. See
+L<perlcall>.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ I32 call_sv(SV* sv, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item CLASS
+
+Variable which is setup by C<xsubpp> to indicate the
+class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
+
+ char* CLASS
+
+=for hackers
+Found in file XSUB.h
+
+=item Copy
+
+The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
+source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
+the type. May fail on overlapping copies. See also C<Move>.
+
+ void Copy(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item croak
+
+This is the XSUB-writer's interface to Perl's C<die> function.
+Normally use this function the same way you use the C C<printf>
+function. See C<warn>.
+
+If you want to throw an exception object, assign the object to
+C<$@> and then pass C<Nullch> to croak():
+
+ errsv = get_sv("@", TRUE);
+ sv_setsv(errsv, exception_object);
+ croak(Nullch);
+
+ void croak(const char* pat, ...)
+
+=for hackers
+Found in file util.c
+
+=item CvSTASH
+
+Returns the stash of the CV.
+
+ HV* CvSTASH(CV* cv)
+
+=for hackers
+Found in file cv.h
+
+=item dMARK
+
+Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
+C<dORIGMARK>.
+
+ dMARK;
+
+=for hackers
+Found in file pp.h
+
+=item dORIGMARK
+
+Saves the original stack mark for the XSUB. See C<ORIGMARK>.
+
+ dORIGMARK;
+
+=for hackers
+Found in file pp.h
+
+=item dSP
+
+Declares a local copy of perl's stack pointer for the XSUB, available via
+the C<SP> macro. See C<SP>.
+
+ dSP;
+
+=for hackers
+Found in file pp.h
+
+=item dXSARGS
+
+Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This
+is usually handled automatically by C<xsubpp>. Declares the C<items>
+variable to indicate the number of items on the stack.
+
+ dXSARGS;
+
+=for hackers
+Found in file XSUB.h
+
+=item dXSI32
+
+Sets up the C<ix> variable for an XSUB which has aliases. This is usually
+handled automatically by C<xsubpp>.
+
+ dXSI32;
+
+=for hackers
+Found in file XSUB.h
+
+=item ENTER
+
+Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
+
+ ENTER;
+
+=for hackers
+Found in file scope.h
+
+=item eval_pv
+
+Tells Perl to C<eval> the given string and return an SV* result.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ SV* eval_pv(const char* p, I32 croak_on_error)
+
+=for hackers
+Found in file perl.c
+
+=item eval_sv
+
+Tells Perl to C<eval> the string in the SV.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ I32 eval_sv(SV* sv, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item EXTEND
+
+Used to extend the argument stack for an XSUB's return values. Once
+used, guarantees that there is room for at least C<nitems> to be pushed
+onto the stack.
+
+ void EXTEND(SP, int nitems)
+
+=for hackers
+Found in file pp.h
+
+=item fbm_compile
+
+Analyses the string in order to make fast searches on it using fbm_instr()
+-- the Boyer-Moore algorithm.
+
+ void fbm_compile(SV* sv, U32 flags)
+
+=for hackers
+Found in file util.c
+
+=item fbm_instr
+
+Returns the location of the SV in the string delimited by C<str> and
+C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
+does not have to be fbm_compiled, but the search will not be as fast
+then.
+
+ char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
+
+=for hackers
+Found in file util.c
+
+=item FREETMPS
+
+Closing bracket for temporaries on a callback. See C<SAVETMPS> and
+L<perlcall>.
+
+ FREETMPS;
+
+=for hackers
+Found in file scope.h
+
+=item get_av
+
+Returns the AV of the specified Perl array. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ AV* get_av(const char* name, I32 create)
+
+=for hackers
+Found in file perl.c
+
+=item get_cv
+
+Returns the CV of the specified Perl subroutine. If C<create> is set and
+the Perl subroutine does not exist then it will be declared (which has the
+same effect as saying C<sub name;>). If C<create> is not set and the
+subroutine does not exist then NULL is returned.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ CV* get_cv(const char* name, I32 create)
+
+=for hackers
+Found in file perl.c
+
+=item get_hv
+
+Returns the HV of the specified Perl hash. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ HV* get_hv(const char* name, I32 create)
+
+=for hackers
+Found in file perl.c
+
+=item get_sv
+
+Returns the SV of the specified Perl scalar. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ SV* get_sv(const char* name, I32 create)
+
+=for hackers
+Found in file perl.c
+
+=item GIMME
+
+A backward-compatible version of C<GIMME_V> which can only return
+C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
+Deprecated. Use C<GIMME_V> instead.
+
+ U32 GIMME
+
+=for hackers
+Found in file op.h
+
+=item GIMME_V
+
+The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
+C<G_SCALAR> or C<G_ARRAY> for void, scalar or array context,
+respectively.
+
+ U32 GIMME_V
+
+=for hackers
+Found in file op.h
+
+=item GvSV
+
+Return the SV from the GV.
+
+ SV* GvSV(GV* gv)
+
+=for hackers
+Found in file gv.h
+
+=item gv_fetchmeth
+
+Returns the glob with the given C<name> and a defined subroutine or
+C<NULL>. The glob lives in the given C<stash>, or in the stashes
+accessible via @ISA and @UNIVERSAL.
+
+The argument C<level> should be either 0 or -1. If C<level==0>, as a
+side-effect creates a glob with the given C<name> in the given C<stash>
+which in the case of success contains an alias for the subroutine, and sets
+up caching info for this glob. Similarly for all the searched stashes.
+
+This function grants C<"SUPER"> token as a postfix of the stash name. The
+GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
+visible to Perl code. So when calling C<call_sv>, you should not use
+the GV directly; instead, you should use the method's CV, which can be
+obtained from the GV with the C<GvCV> macro.
+
+ GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
+
+=for hackers
+Found in file gv.c
+
+=item gv_fetchmethod
+
+See L<gv_fetchmethod_autoload>.
+
+ GV* gv_fetchmethod(HV* stash, const char* name)
+
+=for hackers
+Found in file gv.c
+
+=item gv_fetchmethod_autoload
+
+Returns the glob which contains the subroutine to call to invoke the method
+on the C<stash>. In fact in the presence of autoloading this may be the
+glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
+already setup.
+
+The third parameter of C<gv_fetchmethod_autoload> determines whether
+AUTOLOAD lookup is performed if the given method is not present: non-zero
+means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
+Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
+with a non-zero C<autoload> parameter.
+
+These functions grant C<"SUPER"> token as a prefix of the method name. Note
+that if you want to keep the returned glob for a long time, you need to
+check for it being "AUTOLOAD", since at the later time the call may load a
+different subroutine due to $AUTOLOAD changing its value. Use the glob
+created via a side effect to do this.
+
+These functions have the same side-effects and as C<gv_fetchmeth> with
+C<level==0>. C<name> should be writable if contains C<':'> or C<'
+''>. The warning against passing the GV returned by C<gv_fetchmeth> to
+C<call_sv> apply equally to these functions.
+
+ GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
+
+=for hackers
+Found in file gv.c
+
+=item gv_stashpv
+
+Returns a pointer to the stash for a specified package. C<name> should
+be a valid UTF-8 string. If C<create> is set then the package will be
+created if it does not already exist. If C<create> is not set and the
+package does not exist then NULL is returned.
+
+ HV* gv_stashpv(const char* name, I32 create)
+
+=for hackers
+Found in file gv.c
+
+=item gv_stashsv
+
+Returns a pointer to the stash for a specified package, which must be a
+valid UTF-8 string. See C<gv_stashpv>.
+
+ HV* gv_stashsv(SV* sv, I32 create)
+
+=for hackers
+Found in file gv.c
+
+=item G_ARRAY
+
+Used to indicate array context. See C<GIMME_V>, C<GIMME> and
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_DISCARD
+
+Indicates that arguments returned from a callback should be discarded. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_EVAL
+
+Used to force a Perl C<eval> wrapper around a callback. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_NOARGS
+
+Indicates that no arguments are being sent to a callback. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_SCALAR
+
+Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_VOID
+
+Used to indicate void context. See C<GIMME_V> and L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item HEf_SVKEY
+
+This flag, used in the length slot of hash entries and magic structures,
+specifies the structure contains a C<SV*> pointer where a C<char*> pointer
+is to be expected. (For information only--not to be used).
+
+=for hackers
+Found in file hv.h
+
+=item HeHASH
+
+Returns the computed hash stored in the hash entry.
+
+ U32 HeHASH(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeKEY
+
+Returns the actual pointer stored in the key slot of the hash entry. The
+pointer may be either C<char*> or C<SV*>, depending on the value of
+C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
+usually preferable for finding the value of a key.
+
+ void* HeKEY(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeKLEN
+
+If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
+holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
+be assigned to. The C<HePV()> macro is usually preferable for finding key
+lengths.
+
+ STRLEN HeKLEN(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HePV
+
+Returns the key slot of the hash entry as a C<char*> value, doing any
+necessary dereferencing of possibly C<SV*> keys. The length of the string
+is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
+not care about what the length of the key is, you may use the global
+variable C<PL_na>, though this is rather less efficient than using a local
+variable. Remember though, that hash keys in perl are free to contain
+embedded nulls, so using C<strlen()> or similar is not a good way to find
+the length of hash keys. This is very similar to the C<SvPV()> macro
+described elsewhere in this document.
+
+ char* HePV(HE* he, STRLEN len)
+
+=for hackers
+Found in file hv.h
+
+=item HeSVKEY
+
+Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
+contain an C<SV*> key.
+
+ SV* HeSVKEY(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeSVKEY_force
+
+Returns the key as an C<SV*>. Will create and return a temporary mortal
+C<SV*> if the hash entry contains only a C<char*> key.
+
+ SV* HeSVKEY_force(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeSVKEY_set
+
+Sets the key to a given C<SV*>, taking care to set the appropriate flags to
+indicate the presence of an C<SV*> key, and returns the same
+C<SV*>.
+
+ SV* HeSVKEY_set(HE* he, SV* sv)
+
+=for hackers
+Found in file hv.h
+
+=item HeVAL
+
+Returns the value slot (type C<SV*>) stored in the hash entry.
+
+ SV* HeVAL(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HvNAME
+
+Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
+
+ char* HvNAME(HV* stash)
+
+=for hackers
+Found in file hv.h
+
+=item hv_clear
+
+Clears a hash, making it empty.
+
+ void hv_clear(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_delete
+
+Deletes a key/value pair in the hash. The value SV is removed from the
+hash and returned to the caller. The C<klen> is the length of the key.
+The C<flags> value will normally be zero; if set to G_DISCARD then NULL
+will be returned.
+
+ SV* hv_delete(HV* tb, const char* key, U32 klen, I32 flags)
+
+=for hackers
+Found in file hv.c
+
+=item hv_delete_ent
+
+Deletes a key/value pair in the hash. The value SV is removed from the
+hash and returned to the caller. The C<flags> value will normally be zero;
+if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
+precomputed hash value, or 0 to ask for it to be computed.
+
+ SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_exists
+
+Returns a boolean indicating whether the specified hash key exists. The
+C<klen> is the length of the key.
+
+ bool hv_exists(HV* tb, const char* key, U32 klen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_exists_ent
+
+Returns a boolean indicating whether the specified hash key exists. C<hash>
+can be a valid precomputed hash value, or 0 to ask for it to be
+computed.
+
+ bool hv_exists_ent(HV* tb, SV* key, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_fetch
+
+Returns the SV which corresponds to the specified key in the hash. The
+C<klen> is the length of the key. If C<lval> is set then the fetch will be
+part of a store. Check that the return value is non-null before
+dereferencing it to a C<SV*>.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ SV** hv_fetch(HV* tb, const char* key, U32 klen, I32 lval)
+
+=for hackers
+Found in file hv.c
+
+=item hv_fetch_ent
+
+Returns the hash entry which corresponds to the specified key in the hash.
+C<hash> must be a valid precomputed hash number for the given C<key>, or 0
+if you want the function to compute it. IF C<lval> is set then the fetch
+will be part of a store. Make sure the return value is non-null before
+accessing it. The return value when C<tb> is a tied hash is a pointer to a
+static location, so be sure to make a copy of the structure if you need to
+store it somewhere.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterinit
+
+Prepares a starting point to traverse a hash table. Returns the number of
+keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
+currently only meaningful for hashes without tie magic.
+
+NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
+hash buckets that happen to be in use. If you still need that esoteric
+value, you can get it through the macro C<HvFILL(tb)>.
+
+ I32 hv_iterinit(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterkey
+
+Returns the key from the current position of the hash iterator. See
+C<hv_iterinit>.
+
+ char* hv_iterkey(HE* entry, I32* retlen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterkeysv
+
+Returns the key as an C<SV*> from the current position of the hash
+iterator. The return value will always be a mortal copy of the key. Also
+see C<hv_iterinit>.
+
+ SV* hv_iterkeysv(HE* entry)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternext
+
+Returns entries from a hash iterator. See C<hv_iterinit>.
+
+ HE* hv_iternext(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternextsv
+
+Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
+operation.
+
+ SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterval
+
+Returns the value from the current position of the hash iterator. See
+C<hv_iterkey>.
+
+ SV* hv_iterval(HV* tb, HE* entry)
+
+=for hackers
+Found in file hv.c
+
+=item hv_magic
+
+Adds magic to a hash. See C<sv_magic>.
+
+ void hv_magic(HV* hv, GV* gv, int how)
+
+=for hackers
+Found in file hv.c
+
+=item hv_store
+
+Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
+the length of the key. The C<hash> parameter is the precomputed hash
+value; if it is zero then Perl will compute it. The return value will be
+NULL if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes). Otherwise it can
+be dereferenced to get the original C<SV*>. Note that the caller is
+responsible for suitably incrementing the reference count of C<val> before
+the call, and decrementing it if the function returned NULL.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ SV** hv_store(HV* tb, const char* key, U32 klen, SV* val, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_store_ent
+
+Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
+parameter is the precomputed hash value; if it is zero then Perl will
+compute it. The return value is the new hash entry so created. It will be
+NULL if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes). Otherwise the
+contents of the return value can be accessed using the C<He???> macros
+described here. Note that the caller is responsible for suitably
+incrementing the reference count of C<val> before the call, and
+decrementing it if the function returned NULL.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_undef
+
+Undefines the hash.
+
+ void hv_undef(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item isALNUM
+
+Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
+character (including underscore) or digit.
+
+ bool isALNUM(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item isALPHA
+
+Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
+character.
+
+ bool isALPHA(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item isDIGIT
+
+Returns a boolean indicating whether the C C<char> is an ASCII
+digit.
+
+ bool isDIGIT(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item isLOWER
+
+Returns a boolean indicating whether the C C<char> is a lowercase
+character.
+
+ bool isLOWER(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item isSPACE
+
+Returns a boolean indicating whether the C C<char> is whitespace.
+
+ bool isSPACE(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item isUPPER
+
+Returns a boolean indicating whether the C C<char> is an uppercase
+character.
+
+ bool isUPPER(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item items
+
+Variable which is setup by C<xsubpp> to indicate the number of
+items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
+
+ I32 items
+
+=for hackers
+Found in file XSUB.h
+
+=item ix
+
+Variable which is setup by C<xsubpp> to indicate which of an
+XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
+
+ I32 ix
+
+=for hackers
+Found in file XSUB.h
+
+=item LEAVE
+
+Closing bracket on a callback. See C<ENTER> and L<perlcall>.
+
+ LEAVE;
+
+=for hackers
+Found in file scope.h
+
+=item looks_like_number
+
+Test if an the content of an SV looks like a number (or is a
+number).
+
+ I32 looks_like_number(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item MARK
+
+Stack marker variable for the XSUB. See C<dMARK>.
+
+=for hackers
+Found in file pp.h
+
+=item mg_clear
+
+Clear something magical that the SV represents. See C<sv_magic>.
+
+ int mg_clear(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_copy
+
+Copies the magic from one SV to another. See C<sv_magic>.
+
+ int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
+
+=for hackers
+Found in file mg.c
+
+=item mg_find
+
+Finds the magic pointer for type matching the SV. See C<sv_magic>.
+
+ MAGIC* mg_find(SV* sv, int type)
+
+=for hackers
+Found in file mg.c
+
+=item mg_free
+
+Free any magic storage used by the SV. See C<sv_magic>.
+
+ int mg_free(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_get
+
+Do magic after a value is retrieved from the SV. See C<sv_magic>.
+
+ int mg_get(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_length
+
+Report on the SV's length. See C<sv_magic>.
+
+ U32 mg_length(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_magical
+
+Turns on the magical status of an SV. See C<sv_magic>.
+
+ void mg_magical(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_set
+
+Do magic after a value is assigned to the SV. See C<sv_magic>.
+
+ int mg_set(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item Move
+
+The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
+source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
+the type. Can do overlapping moves. See also C<Copy>.
+
+ void Move(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item New
+
+The XSUB-writer's interface to the C C<malloc> function.
+
+ void New(int id, void* ptr, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item newAV
+
+Creates a new AV. The reference count is set to 1.
+
+ AV* newAV()
+
+=for hackers
+Found in file av.c
+
+=item Newc
+
+The XSUB-writer's interface to the C C<malloc> function, with
+cast.
+
+ void Newc(int id, void* ptr, int nitems, type, cast)
+
+=for hackers
+Found in file handy.h
+
+=item newCONSTSUB
+
+Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
+eligible for inlining at compile-time.
+
+ void newCONSTSUB(HV* stash, char* name, SV* sv)
+
+=for hackers
+Found in file op.c
+
+=item newHV
+
+Creates a new HV. The reference count is set to 1.
+
+ HV* newHV()
+
+=for hackers
+Found in file hv.c
+
+=item newRV_inc
+
+Creates an RV wrapper for an SV. The reference count for the original SV is
+incremented.
+
+ SV* newRV_inc(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item newRV_noinc
+
+Creates an RV wrapper for an SV. The reference count for the original
+SV is B<not> incremented.
+
+ SV* newRV_noinc(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item NEWSV
+
+Creates a new SV. A non-zero C<len> parameter indicates the number of
+bytes of preallocated string space the SV should have. An extra byte for a
+tailing NUL is also reserved. (SvPOK is not set for the SV even if string
+space is allocated.) The reference count for the new SV is set to 1.
+C<id> is an integer id between 0 and 1299 (used to identify leaks).
+
+ SV* NEWSV(int id, STRLEN len)
+
+=for hackers
+Found in file handy.h
+
+=item newSViv
+
+Creates a new SV and copies an integer into it. The reference count for the
+SV is set to 1.
+
+ SV* newSViv(IV i)
+
+=for hackers
+Found in file sv.c
+
+=item newSVnv
+
+Creates a new SV and copies a floating point value into it.
+The reference count for the SV is set to 1.
+
+ SV* newSVnv(NV n)
+
+=for hackers
+Found in file sv.c
+
+=item newSVpv
+
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. If C<len> is zero, Perl will compute the length using
+strlen(). For efficiency, consider using C<newSVpvn> instead.
+
+ SV* newSVpv(const char* s, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item newSVpvf
+
+Creates a new SV an initialize it with the string formatted like
+C<sprintf>.
+
+ SV* newSVpvf(const char* pat, ...)
+
+=for hackers
+Found in file sv.c
+
+=item newSVpvn
+
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
+string. You are responsible for ensuring that the source string is at least
+C<len> bytes long.
+
+ SV* newSVpvn(const char* s, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item newSVrv
+
+Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
+it will be upgraded to one. If C<classname> is non-null then the new SV will
+be blessed in the specified package. The new SV is returned and its
+reference count is 1.
+
+ SV* newSVrv(SV* rv, const char* classname)
+
+=for hackers
+Found in file sv.c
+
+=item newSVsv
+
+Creates a new SV which is an exact duplicate of the original SV.
+
+ SV* newSVsv(SV* old)
+
+=for hackers
+Found in file sv.c
+
+=item newSVuv
+
+Creates a new SV and copies an unsigned integer into it.
+The reference count for the SV is set to 1.
+
+ SV* newSVuv(UV u)
+
+=for hackers
+Found in file sv.c
+
+=item newXS
+
+Used by C<xsubpp> to hook up XSUBs as Perl subs.
+
+=for hackers
+Found in file op.c
+
+=item newXSproto
+
+Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
+the subs.
+
+=for hackers
+Found in file XSUB.h
+
+=item Newz
+
+The XSUB-writer's interface to the C C<malloc> function. The allocated
+memory is zeroed with C<memzero>.
+
+ void Newz(int id, void* ptr, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item Nullav
+
+Null AV pointer.
+
+=for hackers
+Found in file av.h
+
+=item Nullch
+
+Null character pointer.
+
+=for hackers
+Found in file handy.h
+
+=item Nullcv
+
+Null CV pointer.
+
+=for hackers
+Found in file cv.h
+
+=item Nullhv
+
+Null HV pointer.
+
+=for hackers
+Found in file hv.h
+
+=item Nullsv
+
+Null SV pointer.
+
+=for hackers
+Found in file handy.h
+
+=item ORIGMARK
+
+The original stack mark for the XSUB. See C<dORIGMARK>.
+
+=for hackers
+Found in file pp.h
+
+=item perl_alloc
+
+Allocates a new Perl interpreter. See L<perlembed>.
+
+ PerlInterpreter* perl_alloc()
+
+=for hackers
+Found in file perl.c
+
+=item perl_construct
+
+Initializes a new Perl interpreter. See L<perlembed>.
+
+ void perl_construct(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item perl_destruct
+
+Shuts down a Perl interpreter. See L<perlembed>.
+
+ void perl_destruct(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item perl_free
+
+Releases a Perl interpreter. See L<perlembed>.
+
+ void perl_free(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item perl_parse
+
+Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
+
+ int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
+
+=for hackers
+Found in file perl.c
+
+=item perl_run
+
+Tells a Perl interpreter to run. See L<perlembed>.
+
+ int perl_run(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item PL_DBsingle
+
+When Perl is run in debugging mode, with the B<-d> switch, this SV is a
+boolean which indicates whether subs are being single-stepped.
+Single-stepping is automatically turned on after every step. This is the C
+variable which corresponds to Perl's $DB::single variable. See
+C<PL_DBsub>.
+
+ SV * PL_DBsingle
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_DBsub
+
+When Perl is run in debugging mode, with the B<-d> switch, this GV contains
+the SV which holds the name of the sub being debugged. This is the C
+variable which corresponds to Perl's $DB::sub variable. See
+C<PL_DBsingle>.
+
+ GV * PL_DBsub
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_DBtrace
+
+Trace variable used when Perl is run in debugging mode, with the B<-d>
+switch. This is the C variable which corresponds to Perl's $DB::trace
+variable. See C<PL_DBsingle>.
+
+ SV * PL_DBtrace
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_dowarn
+
+The C variable which corresponds to Perl's $^W warning variable.
+
+ bool PL_dowarn
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_modglobal
+
+C<PL_modglobal> is a general purpose, interpreter global HV for use by
+extensions that need to keep information on a per-interpreter basis.
+In a pinch, it can also be used as a symbol table for extensions
+to share data among each other. It is a good idea to use keys
+prefixed by the package name of the extension that owns the data.
+
+ HV* PL_modglobal
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_na
+
+A convenience variable which is typically used with C<SvPV> when one
+doesn't care about the length of the string. It is usually more efficient
+to either declare a local variable and use that instead or to use the
+C<SvPV_nolen> macro.
+
+ STRLEN PL_na
+
+=for hackers
+Found in file thrdvar.h
+
+=item PL_sv_no
+
+This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
+C<&PL_sv_no>.
+
+ SV PL_sv_no
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_undef
+
+This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
+
+ SV PL_sv_undef
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_yes
+
+This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
+C<&PL_sv_yes>.
+
+ SV PL_sv_yes
+
+=for hackers
+Found in file intrpvar.h
+
+=item POPi
+
+Pops an integer off the stack.
+
+ IV POPi
+
+=for hackers
+Found in file pp.h
+
+=item POPl
+
+Pops a long off the stack.
+
+ long POPl
+
+=for hackers
+Found in file pp.h
+
+=item POPn
+
+Pops a double off the stack.
+
+ NV POPn
+
+=for hackers
+Found in file pp.h
+
+=item POPp
+
+Pops a string off the stack.
+
+ char* POPp
+
+=for hackers
+Found in file pp.h
+
+=item POPs
+
+Pops an SV off the stack.
+
+ SV* POPs
+
+=for hackers
+Found in file pp.h
+
+=item PUSHi
+
+Push an integer onto the stack. The stack must have room for this element.
+Handles 'set' magic. See C<XPUSHi>.
+
+ void PUSHi(IV iv)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHMARK
+
+Opening bracket for arguments on a callback. See C<PUTBACK> and
+L<perlcall>.
+
+ PUSHMARK;
+
+=for hackers
+Found in file pp.h
+
+=item PUSHn
+
+Push a double onto the stack. The stack must have room for this element.
+Handles 'set' magic. See C<XPUSHn>.
+
+ void PUSHn(NV nv)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHp
+
+Push a string onto the stack. The stack must have room for this element.
+The C<len> indicates the length of the string. Handles 'set' magic. See
+C<XPUSHp>.
+
+ void PUSHp(char* str, STRLEN len)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHs
+
+Push an SV onto the stack. The stack must have room for this element.
+Does not handle 'set' magic. See C<XPUSHs>.
+
+ void PUSHs(SV* sv)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHu
+
+Push an unsigned integer onto the stack. The stack must have room for this
+element. See C<XPUSHu>.
+
+ void PUSHu(UV uv)
+
+=for hackers
+Found in file pp.h
+
+=item PUTBACK
+
+Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
+See C<PUSHMARK> and L<perlcall> for other uses.
+
+ PUTBACK;
+
+=for hackers
+Found in file pp.h
+
+=item Renew
+
+The XSUB-writer's interface to the C C<realloc> function.
+
+ void Renew(void* ptr, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item Renewc
+
+The XSUB-writer's interface to the C C<realloc> function, with
+cast.
+
+ void Renewc(void* ptr, int nitems, type, cast)
+
+=for hackers
+Found in file handy.h
+
+=item require_pv
+
+Tells Perl to C<require> a module.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ void require_pv(const char* pv)
+
+=for hackers
+Found in file perl.c
+
+=item RETVAL
+
+Variable which is setup by C<xsubpp> to hold the return value for an
+XSUB. This is always the proper type for the XSUB. See
+L<perlxs/"The RETVAL Variable">.
+
+ (whatever) RETVAL
+
+=for hackers
+Found in file XSUB.h
+
+=item Safefree
+
+The XSUB-writer's interface to the C C<free> function.
+
+ void Safefree(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item savepv
+
+Copy a string to a safe spot. This does not use an SV.
+
+ char* savepv(const char* sv)
+
+=for hackers
+Found in file util.c
+
+=item savepvn
+
+Copy a string to a safe spot. The C<len> indicates number of bytes to
+copy. This does not use an SV.
+
+ char* savepvn(const char* sv, I32 len)
+
+=for hackers
+Found in file util.c
+
+=item SAVETMPS
+
+Opening bracket for temporaries on a callback. See C<FREETMPS> and
+L<perlcall>.
+
+ SAVETMPS;
+
+=for hackers
+Found in file scope.h
+
+=item SP
+
+Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
+C<SPAGAIN>.
+
+=for hackers
+Found in file pp.h
+
+=item SPAGAIN
+
+Refetch the stack pointer. Used after a callback. See L<perlcall>.
+
+ SPAGAIN;
+
+=for hackers
+Found in file pp.h
+
+=item ST
+
+Used to access elements on the XSUB's stack.
+
+ SV* ST(int ix)
+
+=for hackers
+Found in file XSUB.h
+
+=item strEQ
+
+Test two strings to see if they are equal. Returns true or false.
+
+ bool strEQ(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strGE
+
+Test two strings to see if the first, C<s1>, is greater than or equal to
+the second, C<s2>. Returns true or false.
+
+ bool strGE(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strGT
+
+Test two strings to see if the first, C<s1>, is greater than the second,
+C<s2>. Returns true or false.
+
+ bool strGT(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strLE
+
+Test two strings to see if the first, C<s1>, is less than or equal to the
+second, C<s2>. Returns true or false.
+
+ bool strLE(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strLT
+
+Test two strings to see if the first, C<s1>, is less than the second,
+C<s2>. Returns true or false.
+
+ bool strLT(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strNE
+
+Test two strings to see if they are different. Returns true or
+false.
+
+ bool strNE(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strnEQ
+
+Test two strings to see if they are equal. The C<len> parameter indicates
+the number of bytes to compare. Returns true or false. (A wrapper for
+C<strncmp>).
+
+ bool strnEQ(char* s1, char* s2, STRLEN len)
+
+=for hackers
+Found in file handy.h
+
+=item strnNE
+
+Test two strings to see if they are different. The C<len> parameter
+indicates the number of bytes to compare. Returns true or false. (A
+wrapper for C<strncmp>).
+
+ bool strnNE(char* s1, char* s2, STRLEN len)
+
+=for hackers
+Found in file handy.h
+
+=item StructCopy
+
+This is an architecture-independent macro to copy one structure to another.
+
+ void StructCopy(type src, type dest, type)
+
+=for hackers
+Found in file handy.h
+
+=item SvCUR
+
+Returns the length of the string which is in the SV. See C<SvLEN>.
+
+ STRLEN SvCUR(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvCUR_set
+
+Set the length of the string which is in the SV. See C<SvCUR>.
+
+ void SvCUR_set(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvEND
+
+Returns a pointer to the last character in the string which is in the SV.
+See C<SvCUR>. Access the character as *(SvEND(sv)).
+
+ char* SvEND(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvGETMAGIC
+
+Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
+argument more than once.
+
+ void SvGETMAGIC(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvGROW
+
+Expands the character buffer in the SV so that it has room for the
+indicated number of bytes (remember to reserve space for an extra trailing
+NUL character). Calls C<sv_grow> to perform the expansion if necessary.
+Returns a pointer to the character buffer.
+
+ void SvGROW(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK
+
+Returns a boolean indicating whether the SV contains an integer.
+
+ bool SvIOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOKp
+
+Returns a boolean indicating whether the SV contains an integer. Checks
+the B<private> setting. Use C<SvIOK>.
+
+ bool SvIOKp(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK_off
+
+Unsets the IV status of an SV.
+
+ void SvIOK_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK_on
+
+Tells an SV that it is an integer.
+
+ void SvIOK_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK_only
+
+Tells an SV that it is an integer and disables all other OK bits.
+
+ void SvIOK_only(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIV
+
+Coerces the given SV to an integer and returns it.
+
+ IV SvIV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIVX
+
+Returns the integer which is stored in the SV, assuming SvIOK is
+true.
+
+ IV SvIVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvLEN
+
+Returns the size of the string buffer in the SV. See C<SvCUR>.
+
+ STRLEN SvLEN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNIOK
+
+Returns a boolean indicating whether the SV contains a number, integer or
+double.
+
+ bool SvNIOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNIOKp
+
+Returns a boolean indicating whether the SV contains a number, integer or
+double. Checks the B<private> setting. Use C<SvNIOK>.
+
+ bool SvNIOKp(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNIOK_off
+
+Unsets the NV/IV status of an SV.
+
+ void SvNIOK_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNOK
+
+Returns a boolean indicating whether the SV contains a double.
+
+ bool SvNOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNOKp
+
+Returns a boolean indicating whether the SV contains a double. Checks the
+B<private> setting. Use C<SvNOK>.
+
+ bool SvNOKp(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNOK_off
+
+Unsets the NV status of an SV.
+
+ void SvNOK_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNOK_on
+
+Tells an SV that it is a double.
+
+ void SvNOK_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNOK_only
+
+Tells an SV that it is a double and disables all other OK bits.
+
+ void SvNOK_only(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNV
+
+Coerce the given SV to a double and return it.
+
+ NV SvNV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNVX
+
+Returns the double which is stored in the SV, assuming SvNOK is
+true.
+
+ NV SvNVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvOK
+
+Returns a boolean indicating whether the value is an SV.
+
+ bool SvOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvOOK
+
+Returns a boolean indicating whether the SvIVX is a valid offset value for
+the SvPVX. This hack is used internally to speed up removal of characters
+from the beginning of a SvPV. When SvOOK is true, then the start of the
+allocated string buffer is really (SvPVX - SvIVX).
+
+ bool SvOOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOK
+
+Returns a boolean indicating whether the SV contains a character
+string.
+
+ bool SvPOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOKp
+
+Returns a boolean indicating whether the SV contains a character string.
+Checks the B<private> setting. Use C<SvPOK>.
+
+ bool SvPOKp(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOK_off
+
+Unsets the PV status of an SV.
+
+ void SvPOK_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOK_on
+
+Tells an SV that it is a string.
+
+ void SvPOK_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOK_only
+
+Tells an SV that it is a string and disables all other OK bits.
+
+ void SvPOK_only(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPV
+
+Returns a pointer to the string in the SV, or a stringified form of the SV
+if the SV does not contain a string. Handles 'get' magic.
+
+ char* SvPV(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVX
+
+Returns a pointer to the string in the SV. The SV must contain a
+string.
+
+ char* SvPVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPV_force
+
+Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
+force if you are going to update the SvPVX directly.
+
+ char* SvPV_force(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPV_nolen
+
+Returns a pointer to the string in the SV, or a stringified form of the SV
+if the SV does not contain a string. Handles 'get' magic.
+
+ char* SvPV_nolen(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT
+
+Returns the value of the object's reference count.
+
+ U32 SvREFCNT(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_dec
+
+Decrements the reference count of the given SV.
+
+ void SvREFCNT_dec(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc
+
+Increments the reference count of the given SV.
+
+ SV* SvREFCNT_inc(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvROK
+
+Tests if the SV is an RV.
+
+ bool SvROK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvROK_off
+
+Unsets the RV status of an SV.
+
+ void SvROK_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvROK_on
+
+Tells an SV that it is an RV.
+
+ void SvROK_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvRV
+
+Dereferences an RV to return the SV.
+
+ SV* SvRV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSETMAGIC
+
+Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
+argument more than once.
+
+ void SvSETMAGIC(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSetSV
+
+Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
+more than once.
+
+ void SvSetSV(SV* dsb, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSetSV_nosteal
+
+Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
+ssv. May evaluate arguments more than once.
+
+ void SvSetSV_nosteal(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSTASH
+
+Returns the stash of the SV.
+
+ HV* SvSTASH(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINT
+
+Taints an SV if tainting is enabled
+
+ void SvTAINT(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINTED
+
+Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
+not.
+
+ bool SvTAINTED(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINTED_off
+
+Untaints an SV. Be I<very> careful with this routine, as it short-circuits
+some of Perl's fundamental security features. XS module authors should not
+use this function unless they fully understand all the implications of
+unconditionally untainting the value. Untainting should be done in the
+standard perl fashion, via a carefully crafted regexp, rather than directly
+untainting variables.
+
+ void SvTAINTED_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINTED_on
+
+Marks an SV as tainted.
+
+ void SvTAINTED_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTRUE
+
+Returns a boolean indicating whether Perl would evaluate the SV as true or
+false, defined or undefined. Does not handle 'get' magic.
+
+ bool SvTRUE(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item svtype
+
+An enum of flags for Perl types. These are found in the file B<sv.h>
+in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
+
+=for hackers
+Found in file sv.h
+
+=item SvTYPE
+
+Returns the type of the SV. See C<svtype>.
+
+ svtype SvTYPE(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SVt_IV
+
+Integer type flag for scalars. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_NV
+
+Double type flag for scalars. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_PV
+
+Pointer type flag for scalars. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_PVAV
+
+Type flag for arrays. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_PVCV
+
+Type flag for code refs. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_PVHV
+
+Type flag for hashes. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_PVMG
+
+Type flag for blessed scalars. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SvUPGRADE
+
+Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
+perform the upgrade if necessary. See C<svtype>.
+
+ void SvUPGRADE(SV* sv, svtype type)
+
+=for hackers
+Found in file sv.h
+
+=item SvUV
+
+Coerces the given SV to an unsigned integer and returns it.
+
+ UV SvUV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUVX
+
+Returns the unsigned integer which is stored in the SV, assuming SvIOK is
+true.
+
+ UV SvUVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item sv_2mortal
+
+Marks an SV as mortal. The SV will be destroyed when the current context
+ends.
+
+ SV* sv_2mortal(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_bless
+
+Blesses an SV into a specified package. The SV must be an RV. The package
+must be designated by its stash (see C<gv_stashpv()>). The reference count
+of the SV is unaffected.
+
+ SV* sv_bless(SV* sv, HV* stash)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpv
+
+Concatenates the string onto the end of the string which is in the SV.
+Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
+
+ void sv_catpv(SV* sv, const char* ptr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpvf
+
+Processes its arguments like C<sprintf> and appends the formatted output
+to an SV. Handles 'get' magic, but not 'set' magic. C<SvSETMAGIC()> must
+typically be called after calling this function to handle 'set' magic.
+
+ void sv_catpvf(SV* sv, const char* pat, ...)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpvf_mg
+
+Like C<sv_catpvf>, but also handles 'set' magic.
+
+ void sv_catpvf_mg(SV *sv, const char* pat, ...)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpvn
+
+Concatenates the string onto the end of the string which is in the SV. The
+C<len> indicates number of bytes to copy. Handles 'get' magic, but not
+'set' magic. See C<sv_catpvn_mg>.
+
+ void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpvn_mg
+
+Like C<sv_catpvn>, but also handles 'set' magic.
+
+ void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpv_mg
+
+Like C<sv_catpv>, but also handles 'set' magic.
+
+ void sv_catpv_mg(SV *sv, const char *ptr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catsv
+
+Concatenates the string from SV C<ssv> onto the end of the string in SV
+C<dsv>. Handles 'get' magic, but not 'set' magic. See C<sv_catsv_mg>.
+
+ void sv_catsv(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catsv_mg
+
+Like C<sv_catsv>, but also handles 'set' magic.
+
+ void sv_catsv_mg(SV *dstr, SV *sstr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_chop
+
+Efficient removal of characters from the beginning of the string buffer.
+SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
+the string buffer. The C<ptr> becomes the first character of the adjusted
+string.
+
+ void sv_chop(SV* sv, char* ptr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_clear
+
+Clear an SV, making it empty. Does not free the memory used by the SV
+itself.
+
+ void sv_clear(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_cmp
+
+Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
+string in C<sv1> is less than, equal to, or greater than the string in
+C<sv2>.
+
+ I32 sv_cmp(SV* sv1, SV* sv2)
+
+=for hackers
+Found in file sv.c
+
+=item sv_cmp_locale
+
+Compares the strings in two SVs in a locale-aware manner. See
+L</sv_cmp_locale>
+
+ I32 sv_cmp_locale(SV* sv1, SV* sv2)
+
+=for hackers
+Found in file sv.c
+
+=item sv_dec
+
+Auto-decrement of the value in the SV.
+
+ void sv_dec(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_derived_from
+
+Returns a boolean indicating whether the SV is derived from the specified
+class. This is the function that implements C<UNIVERSAL::isa>. It works
+for class names as well as for objects.
+
+ bool sv_derived_from(SV* sv, const char* name)
+
+=for hackers
+Found in file universal.c
+
+=item sv_eq
+
+Returns a boolean indicating whether the strings in the two SVs are
+identical.
+
+ I32 sv_eq(SV* sv1, SV* sv2)
+
+=for hackers
+Found in file sv.c
+
+=item sv_free
+
+Free the memory used by an SV.
+
+ void sv_free(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_gets
+
+Get a line from the filehandle and store it into the SV, optionally
+appending to the currently-stored string.
+
+ char* sv_gets(SV* sv, PerlIO* fp, I32 append)
+
+=for hackers
+Found in file sv.c
+
+=item sv_grow
+
+Expands the character buffer in the SV. This will use C<sv_unref> and will
+upgrade the SV to C<SVt_PV>. Returns a pointer to the character buffer.
+Use C<SvGROW>.
+
+ char* sv_grow(SV* sv, STRLEN newlen)
+
+=for hackers
+Found in file sv.c
+
+=item sv_inc
+
+Auto-increment of the value in the SV.
+
+ void sv_inc(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_insert
+
+Inserts a string at the specified offset/length within the SV. Similar to
+the Perl substr() function.
+
+ void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
+
+=for hackers
+Found in file sv.c
+
+=item sv_isa
+
+Returns a boolean indicating whether the SV is blessed into the specified
+class. This does not check for subtypes; use C<sv_derived_from> to verify
+an inheritance relationship.
+
+ int sv_isa(SV* sv, const char* name)
+
+=for hackers
+Found in file sv.c
+
+=item sv_isobject
+
+Returns a boolean indicating whether the SV is an RV pointing to a blessed
+object. If the SV is not an RV, or if the object is not blessed, then this
+will return false.
+
+ int sv_isobject(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_len
+
+Returns the length of the string in the SV. See also C<SvCUR>.
+
+ STRLEN sv_len(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_len_utf8
+
+Returns the number of characters in the string in an SV, counting wide
+UTF8 bytes as a single character.
+
+ STRLEN sv_len_utf8(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_magic
+
+Adds magic to an SV.
+
+ void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
+
+=for hackers
+Found in file sv.c
+
+=item sv_mortalcopy
+
+Creates a new SV which is a copy of the original SV. The new SV is marked
+as mortal.
+
+ SV* sv_mortalcopy(SV* oldsv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_newmortal
+
+Creates a new SV which is mortal. The reference count of the SV is set to 1.
+
+ SV* sv_newmortal()
+
+=for hackers
+Found in file sv.c
+
+=item sv_pvn_force
+
+Get a sensible string out of the SV somehow.
+
+ char* sv_pvn_force(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pvutf8n_force
+
+Get a sensible UTF8-encoded string out of the SV somehow. See
+L</sv_pvn_force>.
+
+ char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_reftype
+
+Returns a string describing what the SV is a reference to.
+
+ char* sv_reftype(SV* sv, int ob)
+
+=for hackers
+Found in file sv.c
+
+=item sv_replace
+
+Make the first argument a copy of the second, then delete the original.
+
+ void sv_replace(SV* sv, SV* nsv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_rvweaken
+
+Weaken a reference.
+
+ SV* sv_rvweaken(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setiv
+
+Copies an integer into the given SV. Does not handle 'set' magic. See
+C<sv_setiv_mg>.
+
+ void sv_setiv(SV* sv, IV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setiv_mg
+
+Like C<sv_setiv>, but also handles 'set' magic.
+
+ void sv_setiv_mg(SV *sv, IV i)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setnv
+
+Copies a double into the given SV. Does not handle 'set' magic. See
+C<sv_setnv_mg>.
+
+ void sv_setnv(SV* sv, NV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setnv_mg
+
+Like C<sv_setnv>, but also handles 'set' magic.
+
+ void sv_setnv_mg(SV *sv, NV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpv
+
+Copies a string into an SV. The string must be null-terminated. Does not
+handle 'set' magic. See C<sv_setpv_mg>.
+
+ void sv_setpv(SV* sv, const char* ptr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpvf
+
+Processes its arguments like C<sprintf> and sets an SV to the formatted
+output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
+
+ void sv_setpvf(SV* sv, const char* pat, ...)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpvf_mg
+
+Like C<sv_setpvf>, but also handles 'set' magic.
+
+ void sv_setpvf_mg(SV *sv, const char* pat, ...)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpviv
+
+Copies an integer into the given SV, also updating its string value.
+Does not handle 'set' magic. See C<sv_setpviv_mg>.
+
+ void sv_setpviv(SV* sv, IV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpviv_mg
+
+Like C<sv_setpviv>, but also handles 'set' magic.
+
+ void sv_setpviv_mg(SV *sv, IV iv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpvn
+
+Copies a string into an SV. The C<len> parameter indicates the number of
+bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
+
+ void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpvn_mg
+
+Like C<sv_setpvn>, but also handles 'set' magic.
+
+ void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpv_mg
+
+Like C<sv_setpv>, but also handles 'set' magic.
+
+ void sv_setpv_mg(SV *sv, const char *ptr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setref_iv
+
+Copies an integer into a new SV, optionally blessing the SV. The C<rv>
+argument will be upgraded to an RV. That RV will be modified to point to
+the new SV. The C<classname> argument indicates the package for the
+blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
+will be returned and will have a reference count of 1.
+
+ SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setref_nv
+
+Copies a double into a new SV, optionally blessing the SV. The C<rv>
+argument will be upgraded to an RV. That RV will be modified to point to
+the new SV. The C<classname> argument indicates the package for the
+blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
+will be returned and will have a reference count of 1.
+
+ SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setref_pv
+
+Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
+argument will be upgraded to an RV. That RV will be modified to point to
+the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
+into the SV. The C<classname> argument indicates the package for the
+blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
+will be returned and will have a reference count of 1.
+
+Do not use with other Perl types such as HV, AV, SV, CV, because those
+objects will become corrupted by the pointer copy process.
+
+Note that C<sv_setref_pvn> copies the string while this copies the pointer.
+
+ SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setref_pvn
+
+Copies a string into a new SV, optionally blessing the SV. The length of the
+string must be specified with C<n>. The C<rv> argument will be upgraded to
+an RV. That RV will be modified to point to the new SV. The C<classname>
+argument indicates the package for the blessing. Set C<classname> to
+C<Nullch> to avoid the blessing. The new SV will be returned and will have
+a reference count of 1.
+
+Note that C<sv_setref_pv> copies the pointer while this copies the string.
+
+ SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setsv
+
+Copies the contents of the source SV C<ssv> into the destination SV C<dsv>.
+The source SV may be destroyed if it is mortal. Does not handle 'set'
+magic. See the macro forms C<SvSetSV>, C<SvSetSV_nosteal> and
+C<sv_setsv_mg>.
+
+ void sv_setsv(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setsv_mg
+
+Like C<sv_setsv>, but also handles 'set' magic.
+
+ void sv_setsv_mg(SV *dstr, SV *sstr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setuv
+
+Copies an unsigned integer into the given SV. Does not handle 'set' magic.
+See C<sv_setuv_mg>.
+
+ void sv_setuv(SV* sv, UV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setuv_mg
+
+Like C<sv_setuv>, but also handles 'set' magic.
+
+ void sv_setuv_mg(SV *sv, UV u)
+
+=for hackers
+Found in file sv.c
+
+=item sv_true
+
+Returns true if the SV has a true value by Perl's rules.
+
+ I32 sv_true(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_unmagic
+
+Removes magic from an SV.
+
+ int sv_unmagic(SV* sv, int type)
+
+=for hackers
+Found in file sv.c
+
+=item sv_unref
+
+Unsets the RV status of the SV, and decrements the reference count of
+whatever was being referenced by the RV. This can almost be thought of
+as a reversal of C<newSVrv>. See C<SvROK_off>.
+
+ void sv_unref(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_upgrade
+
+Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See
+C<svtype>.
+
+ bool sv_upgrade(SV* sv, U32 mt)
+
+=for hackers
+Found in file sv.c
+
+=item sv_usepvn
+
+Tells an SV to use C<ptr> to find its string value. Normally the string is
+stored inside the SV but sv_usepvn allows the SV to use an outside string.
+The C<ptr> should point to memory that was allocated by C<malloc>. The
+string length, C<len>, must be supplied. This function will realloc the
+memory pointed to by C<ptr>, so that pointer should not be freed or used by
+the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
+See C<sv_usepvn_mg>.
+
+ void sv_usepvn(SV* sv, char* ptr, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item sv_usepvn_mg
+
+Like C<sv_usepvn>, but also handles 'set' magic.
+
+ void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_downgrade
+
+Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
+This may not be possible if the PV contains non-byte encoding characters;
+if this is the case, either returns false or, if C<fail_ok> is not
+true, croaks.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ bool sv_utf8_downgrade(SV *sv, bool fail_ok)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_encode
+
+Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
+flag so that it looks like bytes again. Nothing calls this.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ void sv_utf8_encode(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_upgrade
+
+Convert the PV of an SV to its UTF8-encoded form.
+
+ void sv_utf8_upgrade(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vcatpvfn
+
+Processes its arguments like C<vsprintf> and appends the formatted output
+to an SV. Uses an array of SVs if the C style variable argument list is
+missing (NULL). When running with taint checks enabled, indicates via
+C<maybe_tainted> if results are untrustworthy (often due to the use of
+locales).
+
+ void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vsetpvfn
+
+Works like C<vcatpvfn> but copies the text into the SV instead of
+appending it.
+
+ void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+
+=for hackers
+Found in file sv.c
+
+=item THIS
+
+Variable which is setup by C<xsubpp> to designate the object in a C++
+XSUB. This is always the proper type for the C++ object. See C<CLASS> and
+L<perlxs/"Using XS With C++">.
+
+ (whatever) THIS
+
+=for hackers
+Found in file XSUB.h
+
+=item toLOWER
+
+Converts the specified character to lowercase.
+
+ char toLOWER(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item toUPPER
+
+Converts the specified character to uppercase.
+
+ char toUPPER(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item U8 *s
+
+Returns true if first C<len> bytes of the given string form valid a UTF8
+string, false otherwise.
+
+ bool_utf8_string U8 *s(STRLEN len)
+
+=for hackers
+Found in file utf8.c
+
+=item utf8_to_bytes
+
+Converts a string C<s> of length C<len> from UTF8 into ASCII encoding.
+Unlike C<bytes_to_utf8>, this over-writes the original string.
+Returns zero on failure after converting as much as possible.
+
+ U8 * utf8_to_bytes(U8 *s, STRLEN len)
+
+=for hackers
+Found in file utf8.c
+
+=item warn
+
+This is the XSUB-writer's interface to Perl's C<warn> function. Use this
+function the same way you use the C C<printf> function. See
+C<croak>.
+
+ void warn(const char* pat, ...)
+
+=for hackers
+Found in file util.c
+
+=item XPUSHi
+
+Push an integer onto the stack, extending the stack if necessary. Handles
+'set' magic. See C<PUSHi>.
+
+ void XPUSHi(IV iv)
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHn
+
+Push a double onto the stack, extending the stack if necessary. Handles
+'set' magic. See C<PUSHn>.
+
+ void XPUSHn(NV nv)
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHp
+
+Push a string onto the stack, extending the stack if necessary. The C<len>
+indicates the length of the string. Handles 'set' magic. See
+C<PUSHp>.
+
+ void XPUSHp(char* str, STRLEN len)
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHs
+
+Push an SV onto the stack, extending the stack if necessary. Does not
+handle 'set' magic. See C<PUSHs>.
+
+ void XPUSHs(SV* sv)
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHu
+
+Push an unsigned integer onto the stack, extending the stack if necessary.
+See C<PUSHu>.
+
+ void XPUSHu(UV uv)
+
+=for hackers
+Found in file pp.h
+
+=item XS
+
+Macro to declare an XSUB and its C parameter list. This is handled by
+C<xsubpp>.
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN
+
+Return from XSUB, indicating number of items on the stack. This is usually
+handled by C<xsubpp>.
+
+ void XSRETURN(int nitems)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_EMPTY
+
+Return an empty list from an XSUB immediately.
+
+ XSRETURN_EMPTY;
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_IV
+
+Return an integer from an XSUB immediately. Uses C<XST_mIV>.
+
+ void XSRETURN_IV(IV iv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_NO
+
+Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
+
+ XSRETURN_NO;
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_NV
+
+Return an double from an XSUB immediately. Uses C<XST_mNV>.
+
+ void XSRETURN_NV(NV nv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_PV
+
+Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
+
+ void XSRETURN_PV(char* str)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_UNDEF
+
+Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
+
+ XSRETURN_UNDEF;
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_YES
+
+Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
+
+ XSRETURN_YES;
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mIV
+
+Place an integer into the specified position C<pos> on the stack. The
+value is stored in a new mortal SV.
+
+ void XST_mIV(int pos, IV iv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mNO
+
+Place C<&PL_sv_no> into the specified position C<pos> on the
+stack.
+
+ void XST_mNO(int pos)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mNV
+
+Place a double into the specified position C<pos> on the stack. The value
+is stored in a new mortal SV.
+
+ void XST_mNV(int pos, NV nv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mPV
+
+Place a copy of a string into the specified position C<pos> on the stack.
+The value is stored in a new mortal SV.
+
+ void XST_mPV(int pos, char* str)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mUNDEF
+
+Place C<&PL_sv_undef> into the specified position C<pos> on the
+stack.
+
+ void XST_mUNDEF(int pos)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mYES
+
+Place C<&PL_sv_yes> into the specified position C<pos> on the
+stack.
+
+ void XST_mYES(int pos)
+
+=for hackers
+Found in file XSUB.h
+
+=item XS_VERSION
+
+The version identifier for an XS module. This is usually
+handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
+
+=for hackers
+Found in file XSUB.h
+
+=item XS_VERSION_BOOTCHECK
+
+Macro to verify that a PM module's $VERSION variable matches the XS
+module's C<XS_VERSION> variable. This is usually handled automatically by
+C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
+
+ XS_VERSION_BOOTCHECK;
+
+=for hackers
+Found in file XSUB.h
+
+=item Zero
+
+The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
+destination, C<nitems> is the number of items, and C<type> is the type.
+
+ void Zero(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=back
+
+=head1 AUTHORS
+
+Until May 1997, this document was maintained by Jeff Okamoto
+<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
+
+With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
+Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
+Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
+Stephen McCamant, and Gurusamy Sarathy.
+
+API Listing originally by Dean Roehrich <roehrich@cray.com>.
+
+Updated to be autogenerated from comments in the source by Benjamin Stuhl.
+
+=head1 SEE ALSO
+
+perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
-Dean Roehrich F<E<lt>roehrich@cray.comE<gt>>
-May 3, 1995
projects / p5sagit/p5-mst-13.2.git / blobdiff