X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlxs.pod;h=541f75e535f4d75bfb1f445f7200a8559768d5a5;hb=de4864e4e7ced178416488fa2591227064c3222d;hp=781afe60bfaaecb6c80d2ec6b72da0e418c2fef0;hpb=22d4bb9ccb8701e68f9243547d7e3a3c55f70908;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlxs.pod b/pod/perlxs.pod index 781afe6..541f75e 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -66,7 +66,9 @@ for the library being linked. A file in XS format starts with a C language section which goes until the first C> directive. Other XS directives and XSUB definitions may follow this line. The "language" used in this part of the file -is usually referred to as the XS language. +is usually referred to as the XS language. B recognizes and +skips POD (see L) in both the C and XS language sections, which +allows the XS file to contain embedded documentation. See L for a tutorial on the whole extension creation process. @@ -207,9 +209,9 @@ separate lines and should be flush left-adjusted. double x sin(x) double x -The rest of the function description may be indented or left-adjusted. The following example -shows a function with its body left-adjusted. Most examples in this -document will indent the body for better readability. +The rest of the function description may be indented or left-adjusted. The +following example shows a function with its body left-adjusted. Most +examples in this document will indent the body for better readability. CORRECT @@ -276,16 +278,14 @@ mercy of this heuristics unless you use C as return value.) =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 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 with +POD stripped, but otherwise 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 following example will start the XS code and will place all functions in a package named RPC. @@ -754,29 +754,37 @@ thus C is initialized on the declaration line, and our assignment C is not performed too early. Otherwise one would need to have the assignment C in a CODE: or INIT: section.) -=head2 The IN/OUTLIST/IN_OUTLIST Keywords +=head2 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords In the list of parameters for an XSUB, one can precede parameter names -by the C/C/C keywords. C keyword is a default, -the other two keywords indicate how the Perl interface should differ from -the C interface. - -Parameters preceded by C/C keywords are considered to -be used by the C subroutine I. C keyword indicates -that the C subroutine does not inspect the memory pointed by this parameter, -but will write through this pointer to provide additional return values. -Such parameters do not appear in the usage signature of the generated Perl -function. - -Parameters preceded by C I appear as parameters to the -Perl function. These parameters are converted to the corresponding C type, -then pointers to these data are given as arguments to the C function. It -is expected that the C function will write through these pointers +by the C/C/C/C/C keywords. +C keyword is the default, the other keywords indicate how the Perl +interface should differ from the C interface. + +Parameters preceded by C/C/C/C +keywords are considered to be used by the C subroutine I. C/C keywords indicate that the C subroutine +does not inspect the memory pointed by this parameter, but will write +through this pointer to provide additional return values. + +Parameters preceded by C keyword do not appear in the usage +signature of the generated Perl function. + +Parameters preceded by C/C/C I appear as +parameters to the Perl function. With the exception of +C-parameters, these parameters are converted to the corresponding +C type, then pointers to these data are given as arguments to the C +function. It is expected that the C function will write through these +pointers. The return list of the generated Perl function consists of the C return value from the function (unless the XSUB is of C return type or -C was used) followed by all the C -and C parameters (in the order of appearence). Say, an XSUB +C was used) followed by all the C +and C parameters (in the order of appearance). On the +return from the XSUB the C/C Perl parameter will be +modified to have the values written by the C function. + +For example, an XSUB void day_month(OUTLIST day, IN unix_time, OUTLIST month) @@ -792,17 +800,30 @@ The C signature of the corresponding function should be void day_month(int *day, int unix_time, int *month); -The C/C/C keywords can be mixed with ANSI-style -declarations, as in +The C/C/C/C/C keywords can be +mixed with ANSI-style declarations, as in void day_month(OUTLIST int day, int unix_time, OUTLIST int month) (here the optional C keyword is omitted). -The C parameters are somewhat similar to parameters introduced -with L and put into the C section (see -L). Say, the same C function can be interfaced with as +The C parameters are identical with parameters introduced with +L and put into the C section (see +L). The C parameters are very similar, +the only difference being that the value C function writes through the +pointer would not modify the Perl parameter, but is put in the output +list. + +The C/C parameter differ from C/C +parameters only by the the initial value of the Perl parameter not +being read (and not being given to the C function - which gets some +garbage instead). For example, the same C function as above can be +interfaced with as + + void day_month(OUT int day, int unix_time, OUT int month); + +or void day_month(day, unix_time, month) @@ -1347,13 +1368,19 @@ C<&> through, so the function call looks like C. OUTPUT: timep -=head2 Inserting Comments and C Preprocessor Directives +=head2 Inserting POD, Comments and C Preprocessor Directives -C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, -CODE:, PPCODE:, POST_CALL:, and CLEANUP: blocks, as well as outside the functions. -Comments are allowed anywhere after the MODULE keyword. The compiler -will pass the preprocessor directives through untouched and will remove -the commented lines. +C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:, +PPCODE:, POST_CALL:, and CLEANUP: blocks, as well as outside the functions. +Comments are allowed anywhere after the MODULE keyword. The compiler will +pass the preprocessor directives through untouched and will remove the +commented lines. POD documentation is allowed at any point, both in the +C and XS language sections. POD must be terminated with a C<=cut> command; +C will exit with an error if it does not. It is very unlikely that +human generated C code will be mistaken for POD, as most indenting styles +result in whitespace in front of any line starting with C<=>. Machine +generated XS files may fall into this trap unless care is taken to +ensure that a space breaks the sequence "\n=". Comments can be added to XSUBs by placing a C<#> as the first non-whitespace of a line. Care should be taken to avoid making the @@ -1613,7 +1640,7 @@ getnetconfigent() XSUB and an object created by a normal Perl subroutine. 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 +typemap file may consist of three sections labelled C, C, and C. An unlabelled initial section is assumed to be a C section. The INPUT section tells the compiler how to translate Perl values