X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=98abdc1d0766671f976baf19f4c12bc3f5154267;hb=4b3603a49f6eac34b6cdb154bf3bd8a8f5240085;hp=22df2e2011131a5d3d9d1b1f8e514c6c7dbffd72;hpb=d1b918924020f633640d8b8cc8294856a82ddc04;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 22df2e2..98abdc1 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -1,959 +1,3489 @@ =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 -is a function in the XS language and is the core component -of the Perl application interface. - -The XS compiler is called B. 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 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 - 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, C, and C, 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 - - 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 -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 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 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) - doublex - -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 +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, where I 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 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 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 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. Deprecated, use C 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 and the PREFIX value is C then Perl will -see this function as C. - -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 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: - timepsv_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 -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 variable which the -B 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 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 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 return type for this function tells the B 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 compiler to create a stack pointer called C, 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 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 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 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 is -used to obtain a pointer to the variable, known as an B -(Scalar Variable) internally. The package name C 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
for -the variable. The macro B is then used to dereference -the SV to obtain a C 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 but a Perl -scalar variable may also contain numbers and references. If -the SV is expected to have a C C then the macro B -should be used to dereference the SV. When the SV contains -a C double then B should be used. - -The macro B 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 -as shown in the above examples. An argument of B 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, B, and B 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 module the RPC module -can make these function names visible to the rest of the -Perl program. The C 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 or B 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. 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 will be created for C. The Perl -object will be blessed in a class matching the name of the C -type, with the tag C 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 compiler is designed to convert C header files in -/usr/include into Perl extensions. This compiler will -create a directory under the C 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 -from the 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 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 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. When run from the -Perl source directory, the B 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, not C) in the -Perl source directory should be edited to add C -to the C 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 script can also be used to add extensions. The extension -should be placed in the C 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 -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 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 -compiler to map C function parameters and values to Perl values. The -typemap file may consist of three sections labeled C, C, and -C. 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 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 compiler will allow the extension's own typemap to -override any mappings which are in the default typemap. +Deletes the element indexed by C from the array. Returns the +deleted element. C 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 *T_PTROBJ +=for hackers +Found in file av.c -=head1 EXAMPLES - -File C: 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 has been initialized. - #include +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: Custom typemap for RPC.xs. +=item av_extend - TYPEMAP - Netconfig * T_PTROBJ - -File C: 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 is the index to which the array should be +extended. - bootstrap RPC; - 1; - -File C: 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 is the +index. If C 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. +See L 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. 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. Note +that the caller is responsible for suitably incrementing the reference +count of C before the call, and decrementing it if the function +returned NULL. + +See L 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 values onto the beginning of the +array. The array will grow automatically to accommodate the addition. You +must then use C 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 of length C from ASCII into UTF8 encoding. +Returns a pointer to the newly-created string, and sets C 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. + +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. + +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. + +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. + +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 to indicate the +class name for a C++ XS constructor. This is always a C. See C. + + char* CLASS + +=for hackers +Found in file XSUB.h + +=item Copy + +The XSUB-writer's interface to the C C function. The C is the +source, C is the destination, C is the number of items, and C is +the type. May fail on overlapping copies. See also C. + + 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 function. +Normally use this function the same way you use the C C +function. See C. + +If you want to throw an exception object, assign the object to +C<$@> and then pass C 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, for the XSUB. See C and +C. + + dMARK; + +=for hackers +Found in file pp.h + +=item dORIGMARK + +Saves the original stack mark for the XSUB. See C. + + 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 macro. See C. + + 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. Declares the C +variable to indicate the number of items on the stack. + + dXSARGS; + +=for hackers +Found in file XSUB.h + +=item dXSI32 + +Sets up the C variable for an XSUB which has aliases. This is usually +handled automatically by C. + + dXSI32; + +=for hackers +Found in file XSUB.h + +=item ENTER + +Opening bracket on a callback. See C and L. + + ENTER; + +=for hackers +Found in file scope.h + +=item eval_pv + +Tells Perl to C 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 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 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 and +C. It returns C if the string can't be found. The C +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 and +L. + + FREETMPS; + +=for hackers +Found in file scope.h + +=item get_av + +Returns the AV of the specified Perl array. If C is set and the +Perl variable does not exist then it will be created. If C 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 is set and +the Perl subroutine does not exist then it will be declared (which has the +same effect as saying C). If C 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 is set and the +Perl variable does not exist then it will be created. If C 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 is set and the +Perl variable does not exist then it will be created. If C 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 which can only return +C or C; in a void context, it returns C. +Deprecated. Use C instead. + + U32 GIMME + +=for hackers +Found in file op.h + +=item GIMME_V + +The XSUB-writer's equivalent to Perl's C. Returns C, +C or C for void, scalar or list 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 and a defined subroutine or +C. The glob lives in the given C, or in the stashes +accessible via @ISA and @UNIVERSAL. + +The argument C should be either 0 or -1. If C, as a +side-effect creates a glob with the given C in the given C +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 may be a method cache entry, which is not +visible to Perl code. So when calling C, 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 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* 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. 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 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 is equivalent to calling C +with a non-zero C 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 with +C. C should be writable if contains C<':'> or C<' +''>. The warning against passing the GV returned by C to +C 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 should +be a valid UTF-8 string. If C is set then the package will be +created if it does not already exist. If C 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. + + HV* gv_stashsv(SV* sv, I32 create) + +=for hackers +Found in file gv.c + +=item G_ARRAY + +Used to indicate list context. See C, C and +L. + +=for hackers +Found in file cop.h + +=item G_DISCARD + +Indicates that arguments returned from a callback should be discarded. See +L. + +=for hackers +Found in file cop.h + +=item G_EVAL + +Used to force a Perl C wrapper around a callback. See +L. + +=for hackers +Found in file cop.h + +=item G_NOARGS + +Indicates that no arguments are being sent to a callback. See +L. + +=for hackers +Found in file cop.h + +=item G_SCALAR + +Used to indicate scalar context. See C, C, and +L. + +=for hackers +Found in file cop.h + +=item G_VOID + +Used to indicate void context. See C and L. + +=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 pointer where a C 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 or C, depending on the value of +C. Can be assigned to. The C or C 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, it indicates the entry +holds an C key. Otherwise, holds the actual length of the key. Can +be assigned to. The C 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 value, doing any +necessary dereferencing of possibly C keys. The length of the string +is placed in C (this is a macro, so do I use C<&len>). If you do +not care about what the length of the key is, you may use the global +variable C, 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 or similar is not a good way to find +the length of hash keys. This is very similar to the C 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, or C if the hash entry does not +contain an C key. + + SV* HeSVKEY(HE* he) + +=for hackers +Found in file hv.h + +=item HeSVKEY_force + +Returns the key as an C. Will create and return a temporary mortal +C if the hash entry contains only a C key. + + SV* HeSVKEY_force(HE* he) + +=for hackers +Found in file hv.h + +=item HeSVKEY_set + +Sets the key to a given C, taking care to set the appropriate flags to +indicate the presence of an C key, and returns the same +C. + + SV* HeSVKEY_set(HE* he, SV* sv) + +=for hackers +Found in file hv.h + +=item HeVAL + +Returns the value slot (type C) 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, C. + + 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 is the length of the key. +The C 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 value will normally be zero; +if set to G_DISCARD then NULL will be returned. C 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 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 +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 is the length of the key. If C 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. + +See L 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 must be a valid precomputed hash number for the given C, or 0 +if you want the function to compute it. IF C 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 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 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). The return value is +currently only meaningful for hashes without tie magic. + +NOTE: Before version 5.004_65, C 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. + + 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. + + char* hv_iterkey(HE* entry, I32* retlen) + +=for hackers +Found in file hv.c + +=item hv_iterkeysv + +Returns the key as an C from the current position of the hash +iterator. The return value will always be a mortal copy of the key. Also +see C. + + SV* hv_iterkeysv(HE* entry) + +=for hackers +Found in file hv.c + +=item hv_iternext + +Returns entries from a hash iterator. See C. + + HE* hv_iternext(HV* tb) + +=for hackers +Found in file hv.c + +=item hv_iternextsv + +Performs an C, C, and C 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. + + SV* hv_iterval(HV* tb, HE* entry) + +=for hackers +Found in file hv.c + +=item hv_magic + +Adds magic to a hash. See C. + + 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 and C is +the length of the key. The C 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. Note that the caller is +responsible for suitably incrementing the reference count of C before +the call, and decrementing it if the function returned NULL. + +See L 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 in a hash. The hash key is specified as C. The C +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 macros +described here. Note that the caller is responsible for suitably +incrementing the reference count of C before the call, and +decrementing it if the function returned NULL. + +See L 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 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 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 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 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 is whitespace. + + bool isSPACE(char ch) + +=for hackers +Found in file handy.h + +=item isUPPER + +Returns a boolean indicating whether the C C is an uppercase +character. + + bool isUPPER(char ch) + +=for hackers +Found in file handy.h + +=item items + +Variable which is setup by C to indicate the number of +items on the stack. See L. + + I32 items + +=for hackers +Found in file XSUB.h + +=item ix + +Variable which is setup by C to indicate which of an +XSUB's aliases was used to invoke it. See L. + + I32 ix + +=for hackers +Found in file XSUB.h + +=item LEAVE + +Closing bracket on a callback. See C and L. + + 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. + +=for hackers +Found in file pp.h + +=item mg_clear + +Clear something magical that the SV represents. See C. + + 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. + + 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. + + 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. + + 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. + + int mg_get(SV* sv) + +=for hackers +Found in file mg.c + +=item mg_length + +Report on the SV's length. See C. + + 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. + + 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. + + int mg_set(SV* sv) + +=for hackers +Found in file mg.c + +=item Move + +The XSUB-writer's interface to the C C function. The C is the +source, C is the destination, C is the number of items, and C is +the type. Can do overlapping moves. See also C. + + 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 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 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 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 incremented. + + SV* newRV_noinc(SV *sv) + +=for hackers +Found in file sv.c + +=item NEWSV + +Creates a new SV. A non-zero C 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 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 is zero, Perl will compute the length using +strlen(). For efficiency, consider using C 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. + + 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 is zero, Perl will create a zero length +string. You are responsible for ensuring that the source string is at least +C bytes long. + + SV* newSVpvn(const char* s, STRLEN len) + +=for hackers +Found in file sv.c + +=item newSVpvn_share + +Creates a new SV and populates it with a string from +the string table. Turns on READONLY and FAKE. +The idea here is that as string table is used for shared hash +keys these strings will have SvPVX == HeKEY and hash lookup +will avoid string compare. + + SV* newSVpvn_share(const char* s, STRLEN len, U32 hash) + +=for hackers +Found in file sv.c + +=item newSVrv + +Creates a new SV for the RV, C, to point to. If C is not an RV then +it will be upgraded to one. If C 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 to hook up XSUBs as Perl subs. + +=for hackers +Found in file op.c + +=item newXSproto + +Used by C 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 function. The allocated +memory is zeroed with C. + + 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. + +=for hackers +Found in file pp.h + +=item perl_alloc + +Allocates a new Perl interpreter. See L. + + PerlInterpreter* perl_alloc() + +=for hackers +Found in file perl.c + +=item perl_construct + +Initializes a new Perl interpreter. See L. + + void perl_construct(PerlInterpreter* interp) + +=for hackers +Found in file perl.c + +=item perl_destruct + +Shuts down a Perl interpreter. See L. + + void perl_destruct(PerlInterpreter* interp) + +=for hackers +Found in file perl.c + +=item perl_free + +Releases a Perl interpreter. See L. + + 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. + + 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. + + 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. + + 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. + + 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. + + 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 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 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 macro. + + STRLEN PL_na + +=for hackers +Found in file thrdvar.h + +=item PL_sv_no + +This is the C SV. See C. 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 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 SV. See C. 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. + + void PUSHi(IV iv) + +=for hackers +Found in file pp.h + +=item PUSHMARK + +Opening bracket for arguments on a callback. See C and +L. + + 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. + + 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 indicates the length of the string. Handles 'set' magic. See +C. + + 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. + + 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. + + void PUSHu(UV uv) + +=for hackers +Found in file pp.h + +=item PUTBACK + +Closing bracket for XSUB arguments. This is usually handled by C. +See C and L for other uses. + + PUTBACK; + +=for hackers +Found in file pp.h + +=item Renew + +The XSUB-writer's interface to the C C 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 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 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 to hold the return value for an +XSUB. This is always the proper type for the XSUB. See +L. + + (whatever) RETVAL + +=for hackers +Found in file XSUB.h + +=item Safefree + +The XSUB-writer's interface to the C C function. + + void Safefree(void* ptr) + +=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 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 and +L. + + SAVETMPS; + +=for hackers +Found in file scope.h + +=item SP + +Stack pointer. This is usually handled by C. See C and +C. + +=for hackers +Found in file pp.h + +=item SPAGAIN + +Refetch the stack pointer. Used after a callback. See L. + + 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, is greater than or equal to +the second, C. 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, is greater than the second, +C. 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, is less than or equal to the +second, C. 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, is less than the second, +C. 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 parameter indicates +the number of bytes to compare. Returns true or false. (A wrapper for +C). + + 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 parameter +indicates the number of bytes to compare. Returns true or false. (A +wrapper for C). + + 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. + + 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. + + 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. Access the character as *(SvEND(sv)). + + char* SvEND(SV* sv) + +=for hackers +Found in file sv.h + +=item SvGETMAGIC + +Invokes C 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 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 setting. Use C. + + bool SvIOKp(SV* sv) + +=for hackers +Found in file sv.h + +=item SvIOK_notUV + +Returns a boolean indicating whether the SV contains an signed integer. + + void SvIOK_notUV(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 SvIOK_only_UV + +Tells and SV that it is an unsigned integer and disables all other OK bits. + + void SvIOK_only_UV(SV* sv) + +=for hackers +Found in file sv.h + +=item SvIOK_UV + +Returns a boolean indicating whether the SV contains an unsigned integer. + + void SvIOK_UV(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, not including any part +attributable to C. See C. + + 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 setting. Use C. + + 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 setting. Use C. + + 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 setting. Use C. + + 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 SvPOK_only_UTF8 + +Tells an SV that it is a UTF8 string (do not use frivolously) +and disables all other OK bits. + + void SvPOK_only_UTF8(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 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 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 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 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 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 +in the C enum. Test these flags with the C macro. + +=for hackers +Found in file sv.h + +=item SvTYPE + +Returns the type of the SV. See C. + + svtype SvTYPE(SV* sv) + +=for hackers +Found in file sv.h + +=item SVt_IV + +Integer type flag for scalars. See C. + +=for hackers +Found in file sv.h + +=item SVt_NV + +Double type flag for scalars. See C. + +=for hackers +Found in file sv.h + +=item SVt_PV + +Pointer type flag for scalars. See C. + +=for hackers +Found in file sv.h + +=item SVt_PVAV + +Type flag for arrays. See C. + +=for hackers +Found in file sv.h + +=item SVt_PVCV + +Type flag for code refs. See C. + +=for hackers +Found in file sv.h + +=item SVt_PVHV + +Type flag for hashes. See C. + +=for hackers +Found in file sv.h + +=item SVt_PVMG + +Type flag for blessed scalars. See C. + +=for hackers +Found in file sv.h + +=item SvUPGRADE + +Used to upgrade an SV to a more complex form. Uses C to +perform the upgrade if necessary. See C. + + void SvUPGRADE(SV* sv, svtype type) + +=for hackers +Found in file sv.h + +=item SvUTF8 + +Returns a boolean indicating whether the SV contains UTF-8 encoded data. + + void SvUTF8(SV* sv) + +=for hackers +Found in file sv.h + +=item SvUTF8_off + +Unsets the UTF8 status of an SV. + + void SvUTF8_off(SV *sv) + +=for hackers +Found in file sv.h + +=item SvUTF8_on + +Tells an SV that it is a string and encoded in UTF8. Do not use frivolously. + + void SvUTF8_on(SV *sv) + +=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). 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. + + void sv_catpv(SV* sv, const char* ptr) + +=for hackers +Found in file sv.c + +=item sv_catpvf + +Processes its arguments like C and appends the formatted output +to an SV. Handles 'get' magic, but not 'set' magic. C 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, 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 indicates number of bytes to copy. Handles 'get' magic, but not +'set' magic. See C. + + void sv_catpvn(SV* sv, const char* ptr, STRLEN len) + +=for hackers +Found in file sv.c + +=item sv_catpvn_mg + +Like C, 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, 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 onto the end of the string in SV +C. Handles 'get' magic, but not 'set' magic. See C. + + void sv_catsv(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.c + +=item sv_catsv_mg + +Like C, 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 must be a pointer to somewhere inside +the string buffer. The C 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 is less than, equal to, or greater than the string in +C. + + 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 + + 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. 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 and will +upgrade the SV to C. Returns a pointer to the character buffer. +Use C. + + 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 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. + + 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. + + 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. + + void sv_setiv(SV* sv, IV num) + +=for hackers +Found in file sv.c + +=item sv_setiv_mg + +Like C, 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. + + void sv_setnv(SV* sv, NV num) + +=for hackers +Found in file sv.c + +=item sv_setnv_mg + +Like C, 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. + + void sv_setpv(SV* sv, const char* ptr) + +=for hackers +Found in file sv.c + +=item sv_setpvf + +Processes its arguments like C and sets an SV to the formatted +output. Does not handle 'set' magic. See C. + + void sv_setpvf(SV* sv, const char* pat, ...) + +=for hackers +Found in file sv.c + +=item sv_setpvf_mg + +Like C, 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. + + void sv_setpviv(SV* sv, IV num) + +=for hackers +Found in file sv.c + +=item sv_setpviv_mg + +Like C, 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 parameter indicates the number of +bytes to be copied. Does not handle 'set' magic. See C. + + void sv_setpvn(SV* sv, const char* ptr, STRLEN len) + +=for hackers +Found in file sv.c + +=item sv_setpvn_mg + +Like C, 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, 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 +argument will be upgraded to an RV. That RV will be modified to point to +the new SV. The C argument indicates the package for the +blessing. Set C to C 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 +argument will be upgraded to an RV. That RV will be modified to point to +the new SV. The C argument indicates the package for the +blessing. Set C to C 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 +argument will be upgraded to an RV. That RV will be modified to point to +the new SV. If the C argument is NULL then C will be placed +into the SV. The C argument indicates the package for the +blessing. Set C to C 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 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. The C argument will be upgraded to +an RV. That RV will be modified to point to the new SV. The C +argument indicates the package for the blessing. Set C to +C to avoid the blessing. The new SV will be returned and will have +a reference count of 1. + +Note that C 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 into the destination SV C. +The source SV may be destroyed if it is mortal. Does not handle 'set' +magic. See the macro forms C, C and +C. + + void sv_setsv(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.c + +=item sv_setsv_mg + +Like C, 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. + + void sv_setuv(SV* sv, UV num) + +=for hackers +Found in file sv.c + +=item sv_setuv_mg + +Like C, 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. See C. + + 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. See +C. + + bool sv_upgrade(SV* sv, U32 mt) + +=for hackers +Found in file sv.c + +=item sv_usepvn + +Tells an SV to use C 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 should point to memory that was allocated by C. The +string length, C, must be supplied. This function will realloc the +memory pointed to by C, 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. + + void sv_usepvn(SV* sv, char* ptr, STRLEN len) + +=for hackers +Found in file sv.c + +=item sv_usepvn_mg + +Like C, 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 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 +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 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 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 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 to designate the object in a C++ +XSUB. This is always the proper type for the C++ object. See C and +L. + + (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 bytes of the given string form valid a UTF8 +string, false otherwise. + + is_utf8_string U8 *s(STRLEN len) + +=for hackers +Found in file utf8.c + +=item utf8_to_bytes + +Converts a string C of length C from UTF8 into byte encoding. +Unlike C, this over-writes the original string, and +updates len to contain the new length. +Returns zero on failure, setting C to -1. + + U8 * utf8_to_bytes(U8 *s, STRLEN *len) + +=for hackers +Found in file utf8.c + +=item utf8_to_uv + +Returns the character value of the first character in the string C +which is assumed to be in UTF8 encoding; C will be set to the +length, in bytes, of that character, and the pointer C will be +advanced to the end of the character. + +If C does not point to a well-formed UTF8 character, an optional UTF8 +warning is produced. + + U8* s utf8_to_uv(I32 *retlen) + +=for hackers +Found in file utf8.c + +=item utf8_to_uv_chk + +Returns the character value of the first character in the string C +which is assumed to be in UTF8 encoding; C will be set to the +length, in bytes, of that character, and the pointer C will be +advanced to the end of the character. + +If C does not point to a well-formed UTF8 character, the behaviour +is dependent on the value of C: if this is true, it is +assumed that the caller will raise a warning, and this function will +set C to C<-1> and return. If C is not true, an optional UTF8 +warning is produced. + + U8* s utf8_to_uv_chk(I32 *retlen, I32 checking) + +=for hackers +Found in file utf8.c + +=item warn + +This is the XSUB-writer's interface to Perl's C function. Use this +function the same way you use the C C function. See +C. + + 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. + + 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. + + 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 +indicates the length of the string. Handles 'set' magic. See +C. + + 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. + + 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. + + 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. + +=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. + + 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. + + 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. + + XSRETURN_NO; + +=for hackers +Found in file XSUB.h + +=item XSRETURN_NV + +Return an double from an XSUB immediately. Uses C. + + 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. + + 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. + + XSRETURN_UNDEF; + +=for hackers +Found in file XSUB.h + +=item XSRETURN_YES + +Return C<&PL_sv_yes> from an XSUB immediately. Uses C. + + XSRETURN_YES; + +=for hackers +Found in file XSUB.h + +=item XST_mIV + +Place an integer into the specified position C 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 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 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 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 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 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. See C. + +=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 variable. This is usually handled automatically by +C. See L. + + XS_VERSION_BOOTCHECK; + +=for hackers +Found in file XSUB.h + +=item Zero + +The XSUB-writer's interface to the C C function. The C is the +destination, C is the number of items, and C 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 +. 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 . + +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 Froehrich@cray.comE> -May 3, 1995