First:
mv perlapi.pod perlxs.pod
Then apply the patch. You should apply it over the perlapi that is in
5.001m, ignoring the patch I sent last week.
I think the section "Creating A New Extension" should be thrown out now that
the "Getting Started" section exists. Put it together, let me know what you
think.
perlapi is referenced in the following pod/ files:
Makefile
perl.pod
perlcall.pod
perlguts.pod
perlmod.pod
Should we point all of them to perlxs?
Dean
*** pod/perlxs.pod Wed May 31 16:08:11 1995
--- ../patches/perlxs.pod Thu Oct 12 23:03:24 1995
***************
*** 1,6 ****
=head1 NAME
! perlapi - Perl 5 application programming interface for C extensions
=head1 DESCRIPTION
--- 1,6 ----
=head1 NAME
! perlxs - XS language reference manual
=head1 DESCRIPTION
***************
*** 23,30 ****
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
--- 23,65 ----
to handle special structures and types for the library being
linked.
+ =head2 Getting Started
+
+ A new extension should begin with the B<h2xs> tool. This will generate
+ templates for the new Perl module (PM), the XS source file (XS), the MANIFEST
+ file, and the Makefile.PL (PL) files. The Makefile.PL file is a Perl script
+ which will generate a Makefile. This makefile knows how to find and run
+ xsubpp for your extension. When you type "make" your XS file will be run
+ through xsubpp and a C file will be produced. Then the C file will be
+ compiled. A simple example looks like this for an example module named
+ B<Foo>:
+
+ $ h2xs -Afn Foo
+ $ cd ext/Foo
+ $ ls
+ Foo.pm Foo.xs MANIFEST Makefile.PL
+ $ perl5 Makefile.PL
+ $ ls
+ Foo.pm Foo.xs MANIFEST Makefile.PL Makefile
+ $ <edit Foo.pm and Foo.xs to add your stuff>
+ $ make
+ <you will see xsubpp run on Foo.xs and you'll see the C compiler
+ <run on Foo.c, and a bunch of other less-interesting things
+ <will happen.
+
+ If your Perl was built with dynamic loading then the makefile will build a
+ dynamically loadable extension. If you don't have dynamic loading then the
+ makefile will build a static extension and should create a new Perl binary.
+ The default behavior depends on what is available.
+
+ For more information about h2xs consult its manpage, embedded in the
+ source. For information about the Makefile.PL and Makefile consult the
+ MakeMaker manpage.
+
+ =head2 On The Road
+
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
***************
*** 66,73 ****
bool_t
rpcb_gettime(host,timep)
! char * host
! time_t &timep
OUTPUT:
timep
--- 101,108 ----
bool_t
rpcb_gettime(host,timep)
! char *host
! time_t &timep
OUTPUT:
timep
***************
*** 100,136 ****
allow the programmer to create a more Perl-like interface to the C
function.
- It is recommended that the B<h2xs> tool be used when creating new
- extensions. This tool will generate template source files and Makefiles.
- This is discussed in more detail in the section titled "Creating A New
- Extension" and in the B<h2xs> manpage.
-
=head2 The Anatomy of an XSUB
! The following XSUB allows a Perl program to access a C library function called sin(). The XSUB will imitate the C
! function which takes a single argument and returns a single
! value.
double
sin(x)
! double<tab>x
! The compiler expects a tab between the parameter name and its type, and
! any or no whitespace before the type. When using C pointers the
! indirection operator C<*> should be considered part of the type and the
! address operator C<&> should be considered part of the variable, as is
! demonstrated in the rpcb_gettime() function above. See the section on
! typemaps for more about handling qualifiers and unary operators in C
! types.
! The parameter list of a function must not have whitespace
! after the open-parenthesis or before the close-parenthesis.
INCORRECT CORRECT
double double
sin( x ) sin(x)
! double x double x
The function name and the return type must be placed on
separate lines.
--- 135,165 ----
allow the programmer to create a more Perl-like interface to the C
function.
=head2 The Anatomy of an XSUB
! The following XSUB allows a Perl program to access a C library function
! called sin(). The XSUB will imitate the C function which takes a single
! argument and returns a single value.
double
sin(x)
! double x
! 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. (This restriction will be
! relaxed in later versions of B<xsubpp>.)
INCORRECT CORRECT
double double
sin( x ) sin(x)
! double x double x
The function name and the return type must be placed on
separate lines.
***************
*** 138,145 ****
INCORRECT CORRECT
double sin(x) double
! double x sin(x)
! double x
=head2 The Argument Stack
--- 167,174 ----
INCORRECT CORRECT
double sin(x) double
! double x sin(x)
! double x
=head2 The Argument Stack
***************
*** 151,158 ****
first position on that stack which belongs to the active
function will be referred to as position 0 for that function.
! XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x> refers
! to a position in this XSUB's part of the stack. Position 0 for that
function would be known to the XSUB as ST(0). The XSUB's incoming
parameters and outgoing return values always begin at ST(0). For many
simple cases the B<xsubpp> compiler will generate the code necessary to
--- 180,187 ----
first position on that stack which belongs to the active
function will be referred to as position 0 for that function.
! XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
! refers to a position in this XSUB's part of the stack. Position 0 for that
function would be known to the XSUB as ST(0). The XSUB's incoming
parameters and outgoing return values always begin at ST(0). For many
simple cases the B<xsubpp> compiler will generate the code necessary to
***************
*** 246,259 ****
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
--- 275,286 ----
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.
bool_t
rpcb_gettime(host,timep)
! char *host
! time_t &timep
OUTPUT:
timep
***************
*** 263,272 ****
bool_t
rpcb_gettime(host,timep)
! char * host
! time_t &timep
OUTPUT:
! timep<tab>sv_setnv(ST(1), (double)timep);
=head2 The CODE: Keyword
--- 290,299 ----
bool_t
rpcb_gettime(host,timep)
! char *host
! time_t &timep
OUTPUT:
! timep sv_setnv(ST(1), (double)timep);
=head2 The CODE: Keyword
***************
*** 284,291 ****
bool_t
rpcb_gettime(host,timep)
! char * host
! time_t timep
CODE:
RETVAL = rpcb_gettime( host, &timep );
OUTPUT:
--- 311,318 ----
bool_t
rpcb_gettime(host,timep)
! char *host
! time_t timep
CODE:
RETVAL = rpcb_gettime( host, &timep );
OUTPUT:
***************
*** 314,321 ****
bool_t
rpcb_gettime(host,timep)
! char * host
! time_t &timep = NO_INIT
OUTPUT:
timep
--- 341,348 ----
bool_t
rpcb_gettime(host,timep)
! char *host
! time_t &timep = NO_INIT
OUTPUT:
timep
***************
*** 335,342 ****
bool_t
rpcb_gettime(host,timep)
! char * host = (char *)SvPV(ST(0),na);
! time_t &timep = 0;
OUTPUT:
timep
--- 362,369 ----
bool_t
rpcb_gettime(host,timep)
! char *host = (char *)SvPV(ST(0),na);
! time_t &timep = 0;
OUTPUT:
timep
***************
*** 368,375 ****
bool_t
rpcb_gettime(timep,host="localhost")
! char * host
! time_t timep = NO_INIT
CODE:
RETVAL = rpcb_gettime( host, &timep );
OUTPUT:
--- 395,402 ----
bool_t
rpcb_gettime(timep,host="localhost")
! char *host
! time_t timep = NO_INIT
CODE:
RETVAL = rpcb_gettime( host, &timep );
OUTPUT:
***************
*** 398,404 ****
bool_t
rpcb_gettime(timep, ...)
! time_t timep = NO_INIT
CODE:
{
char *host = "localhost";
--- 425,431 ----
bool_t
rpcb_gettime(timep, ...)
! time_t timep = NO_INIT
CODE:
{
char *host = "localhost";
***************
*** 427,433 ****
void
rpcb_gettime(host)
! char * host
PPCODE:
{
time_t timep;
--- 454,460 ----
void
rpcb_gettime(host)
! char *host
PPCODE:
{
time_t timep;
***************
*** 513,519 ****
void
rpcb_gettime(host)
! char * host
PPCODE:
{
time_t timep;
--- 540,546 ----
void
rpcb_gettime(host)
! char *host
PPCODE:
{
time_t timep;
***************
*** 728,734 ****
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
--- 755,761 ----
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
***************
*** 754,766 ****
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 );
--- 781,793 ----
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 );
***************
*** 899,905 ****
void
rpcb_gettime(host="localhost")
! char * host
CODE:
{
time_t timep;
--- 926,932 ----
void
rpcb_gettime(host="localhost")
! char *host
CODE:
{
time_t timep;
***************
*** 910,922 ****
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 );
--- 937,949 ----
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 );
***************
*** 956,959 ****
=head1 AUTHOR
Dean Roehrich F<E<lt>roehrich@cray.comE<gt>>
! May 3, 1995
--- 983,986 ----
=head1 AUTHOR
Dean Roehrich F<E<lt>roehrich@cray.comE<gt>>
! Oct 12, 1995
mv perlapi.pod perlxs.pod
Then apply the patch. You should apply it over the perlapi that is in
5.001m, ignoring the patch I sent last week.
I think the section "Creating A New Extension" should be thrown out now that
the "Getting Started" section exists. Put it together, let me know what you
think.
perlapi is referenced in the following pod/ files:
Makefile
perl.pod
perlcall.pod
perlguts.pod
perlmod.pod
Should we point all of them to perlxs?
Dean
*** pod/perlxs.pod Wed May 31 16:08:11 1995
--- ../patches/perlxs.pod Thu Oct 12 23:03:24 1995
***************
*** 1,6 ****
=head1 NAME
! perlapi - Perl 5 application programming interface for C extensions
=head1 DESCRIPTION
--- 1,6 ----
=head1 NAME
! perlxs - XS language reference manual
=head1 DESCRIPTION
***************
*** 23,30 ****
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
--- 23,65 ----
to handle special structures and types for the library being
linked.
+ =head2 Getting Started
+
+ A new extension should begin with the B<h2xs> tool. This will generate
+ templates for the new Perl module (PM), the XS source file (XS), the MANIFEST
+ file, and the Makefile.PL (PL) files. The Makefile.PL file is a Perl script
+ which will generate a Makefile. This makefile knows how to find and run
+ xsubpp for your extension. When you type "make" your XS file will be run
+ through xsubpp and a C file will be produced. Then the C file will be
+ compiled. A simple example looks like this for an example module named
+ B<Foo>:
+
+ $ h2xs -Afn Foo
+ $ cd ext/Foo
+ $ ls
+ Foo.pm Foo.xs MANIFEST Makefile.PL
+ $ perl5 Makefile.PL
+ $ ls
+ Foo.pm Foo.xs MANIFEST Makefile.PL Makefile
+ $ <edit Foo.pm and Foo.xs to add your stuff>
+ $ make
+ <you will see xsubpp run on Foo.xs and you'll see the C compiler
+ <run on Foo.c, and a bunch of other less-interesting things
+ <will happen.
+
+ If your Perl was built with dynamic loading then the makefile will build a
+ dynamically loadable extension. If you don't have dynamic loading then the
+ makefile will build a static extension and should create a new Perl binary.
+ The default behavior depends on what is available.
+
+ For more information about h2xs consult its manpage, embedded in the
+ source. For information about the Makefile.PL and Makefile consult the
+ MakeMaker manpage.
+
+ =head2 On The Road
+
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
***************
*** 66,73 ****
bool_t
rpcb_gettime(host,timep)
! char * host
! time_t &timep
OUTPUT:
timep
--- 101,108 ----
bool_t
rpcb_gettime(host,timep)
! char *host
! time_t &timep
OUTPUT:
timep
***************
*** 100,136 ****
allow the programmer to create a more Perl-like interface to the C
function.
- It is recommended that the B<h2xs> tool be used when creating new
- extensions. This tool will generate template source files and Makefiles.
- This is discussed in more detail in the section titled "Creating A New
- Extension" and in the B<h2xs> manpage.
-
=head2 The Anatomy of an XSUB
! The following XSUB allows a Perl program to access a C library function called sin(). The XSUB will imitate the C
! function which takes a single argument and returns a single
! value.
double
sin(x)
! double<tab>x
! The compiler expects a tab between the parameter name and its type, and
! any or no whitespace before the type. When using C pointers the
! indirection operator C<*> should be considered part of the type and the
! address operator C<&> should be considered part of the variable, as is
! demonstrated in the rpcb_gettime() function above. See the section on
! typemaps for more about handling qualifiers and unary operators in C
! types.
! The parameter list of a function must not have whitespace
! after the open-parenthesis or before the close-parenthesis.
INCORRECT CORRECT
double double
sin( x ) sin(x)
! double x double x
The function name and the return type must be placed on
separate lines.
--- 135,165 ----
allow the programmer to create a more Perl-like interface to the C
function.
=head2 The Anatomy of an XSUB
! The following XSUB allows a Perl program to access a C library function
! called sin(). The XSUB will imitate the C function which takes a single
! argument and returns a single value.
double
sin(x)
! double x
! 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. (This restriction will be
! relaxed in later versions of B<xsubpp>.)
INCORRECT CORRECT
double double
sin( x ) sin(x)
! double x double x
The function name and the return type must be placed on
separate lines.
***************
*** 138,145 ****
INCORRECT CORRECT
double sin(x) double
! double x sin(x)
! double x
=head2 The Argument Stack
--- 167,174 ----
INCORRECT CORRECT
double sin(x) double
! double x sin(x)
! double x
=head2 The Argument Stack
***************
*** 151,158 ****
first position on that stack which belongs to the active
function will be referred to as position 0 for that function.
! XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x> refers
! to a position in this XSUB's part of the stack. Position 0 for that
function would be known to the XSUB as ST(0). The XSUB's incoming
parameters and outgoing return values always begin at ST(0). For many
simple cases the B<xsubpp> compiler will generate the code necessary to
--- 180,187 ----
first position on that stack which belongs to the active
function will be referred to as position 0 for that function.
! XSUBs refer to their stack arguments with the macro B<ST(x)>, where I<x>
! refers to a position in this XSUB's part of the stack. Position 0 for that
function would be known to the XSUB as ST(0). The XSUB's incoming
parameters and outgoing return values always begin at ST(0). For many
simple cases the B<xsubpp> compiler will generate the code necessary to
***************
*** 246,259 ****
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
--- 275,286 ----
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.
bool_t
rpcb_gettime(host,timep)
! char *host
! time_t &timep
OUTPUT:
timep
***************
*** 263,272 ****
bool_t
rpcb_gettime(host,timep)
! char * host
! time_t &timep
OUTPUT:
! timep<tab>sv_setnv(ST(1), (double)timep);
=head2 The CODE: Keyword
--- 290,299 ----
bool_t
rpcb_gettime(host,timep)
! char *host
! time_t &timep
OUTPUT:
! timep sv_setnv(ST(1), (double)timep);
=head2 The CODE: Keyword
***************
*** 284,291 ****
bool_t
rpcb_gettime(host,timep)
! char * host
! time_t timep
CODE:
RETVAL = rpcb_gettime( host, &timep );
OUTPUT:
--- 311,318 ----
bool_t
rpcb_gettime(host,timep)
! char *host
! time_t timep
CODE:
RETVAL = rpcb_gettime( host, &timep );
OUTPUT:
***************
*** 314,321 ****
bool_t
rpcb_gettime(host,timep)
! char * host
! time_t &timep = NO_INIT
OUTPUT:
timep
--- 341,348 ----
bool_t
rpcb_gettime(host,timep)
! char *host
! time_t &timep = NO_INIT
OUTPUT:
timep
***************
*** 335,342 ****
bool_t
rpcb_gettime(host,timep)
! char * host = (char *)SvPV(ST(0),na);
! time_t &timep = 0;
OUTPUT:
timep
--- 362,369 ----
bool_t
rpcb_gettime(host,timep)
! char *host = (char *)SvPV(ST(0),na);
! time_t &timep = 0;
OUTPUT:
timep
***************
*** 368,375 ****
bool_t
rpcb_gettime(timep,host="localhost")
! char * host
! time_t timep = NO_INIT
CODE:
RETVAL = rpcb_gettime( host, &timep );
OUTPUT:
--- 395,402 ----
bool_t
rpcb_gettime(timep,host="localhost")
! char *host
! time_t timep = NO_INIT
CODE:
RETVAL = rpcb_gettime( host, &timep );
OUTPUT:
***************
*** 398,404 ****
bool_t
rpcb_gettime(timep, ...)
! time_t timep = NO_INIT
CODE:
{
char *host = "localhost";
--- 425,431 ----
bool_t
rpcb_gettime(timep, ...)
! time_t timep = NO_INIT
CODE:
{
char *host = "localhost";
***************
*** 427,433 ****
void
rpcb_gettime(host)
! char * host
PPCODE:
{
time_t timep;
--- 454,460 ----
void
rpcb_gettime(host)
! char *host
PPCODE:
{
time_t timep;
***************
*** 513,519 ****
void
rpcb_gettime(host)
! char * host
PPCODE:
{
time_t timep;
--- 540,546 ----
void
rpcb_gettime(host)
! char *host
PPCODE:
{
time_t timep;
***************
*** 728,734 ****
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
--- 755,761 ----
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
***************
*** 754,766 ****
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 );
--- 781,793 ----
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 );
***************
*** 899,905 ****
void
rpcb_gettime(host="localhost")
! char * host
CODE:
{
time_t timep;
--- 926,932 ----
void
rpcb_gettime(host="localhost")
! char *host
CODE:
{
time_t timep;
***************
*** 910,922 ****
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 );
--- 937,949 ----
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 );
***************
*** 956,959 ****
=head1 AUTHOR
Dean Roehrich F<E<lt>roehrich@cray.comE<gt>>
! May 3, 1995
--- 983,986 ----
=head1 AUTHOR
Dean Roehrich F<E<lt>roehrich@cray.comE<gt>>
! Oct 12, 1995