view release on metacpan or  search on metacpan

nsapi_perl.pod  view on Meta::CPAN

constants are termed request-response codes.  Any nsapi_perl
subroutine should also always return one of these constants.  The
constants are defined in the Netscape::Server module which should
therefore always be use()d by your nsapi_perl module.

The following will import the request-response codes from
Netscape::Server.

 use Netscape::Server qw/:request_codes/;

The constants are described in detail in L<Netscape::Server>; I will
list them here for reference:

 REQ_ABORTED, REQ_EXIT, REQ_NOACTION, REQ_PROCEED

The interpretation of the value returned by the subroutine to the
server depends on what stage of the request was being processed, as
the following table indicates.

 Request   |            Subroutine returns
 Stage     |REQ_ABORTED|REQ_EXIT|REQ_NOACTION|REQ_PROCEED
 --------------------------------------------------------
 AuthTrans |     x     |   x    |     n      |     s
 NameTrans |     x     |   x    |     n      |     s
 PathCheck |     x     |   x    |     s      |     s
 ObjectType|     x     |   x    |     s      |     s
 Service   |     x     |   x    |     n      |     s
 AddLog    |     ?     |   ?    |     ?      |     ?
 --------------------------------------------------------

 x - request is aborted entirely
 s - request skips to next stage
 n - request goes to next directive in same stage

Basically REQ_ABORTED and REQ_EXIT each indicate an error, but you
should only use REQ_EXIT if there was an I/O error when talking to the
client.  REQ_PROCEED always causes processing to move to the next
stage.  REQ_NOACTION sometimes causes the next directive in the same
stage to be called.  This could be used to implement, for instance, a
sequence of NameTrans functions each mapping in their own way the
request path.

I have never seen any documentation about how the server interprets
values returned by AddLog functions.  I suppose since it is the last
step anyway, it may not really matter.

Netscape::Server also provides other constants that can be used to set
the http status of the request or the severity of errors; see
L<Netscape::Server> for full details.

=head1 DYNAMIC LOADING OF EXTENSIONS

When you put a statement in a module that causes automatic loading of
a Perl extension, such as

 use Socket;

you may get error messages from the run-time loader that look like:

 Can't load '/path/lib/perl5/arch/auto/Foo/Foo.so' for module Foo:
 ld.so.1: ./ns-httpd: fatal: relocation error: symbol not found:
 Perl_sv_undef: referenced in '/path/lib/perl5/arch/auto/Foo/Foo.so'
 at /path/lib/perl5/arch/5.00404/DynaLoader.pm line 166.

This is because the Perl library is loaded into the Netscape server by
dlopen(3) (or its equivalent).  On many platforms symbols contained in
objects loaded in by dlopen are not visibile to other objects loaded
in by dlopen (such as Foo.so in the above example).

On some operating systems, this restriction may be worked around by
adding the B<shlib> argument to the nsapi_perl_init() function call in
obj.conf, like this:

 Init fn="nsapi_perl_init"
      init-script="/home/benjamin/foobar.pl"
      shlib="/path/to/nsapi_perl.so"

Here, F</path/to/nsapi_perl.so> should be the full path to the
nsapi_perl shared object.  This location was determined during the
installation of nsapi_perl.

The presence of a B<shlib> argument in the call to nsapi_perl_init
causes nsapi_perl to call dlopen(3) on F</path/to/nsapi_perl.so>, passing
dlopen a flag (RTLD_GLOBAL) that tells the runtime linker symbols
within this object are to be visible to other objects acquired at a
later time via dlopen.

Obviously this workaround only works on those systems that define
RTLD_GLOBAL.  Currently this includes at least Solaris and IRIX; there
may be others too that I am not aware of.  A B<shlib> argument on a
system that does not support RTLD_GLOBAL is silently ignored.

(Earlier versions of nsapi_perl used a libperl argument to nsapi_perl
init instead of shlib.  libperl was expected to point to a (shared)
perl library, like libperl.so.  It is now recommended that you use the
shlib argument instead of the libperl argument, and that you point to
the nsapi_perl shared object itself, rather than the shared Perl
library.)

Incidently, extension modules on Win32 are reported to work just fine
"out of the box".

=head1 EXAMPLES

=head2 Hello World

In F<obj.conf>:

 <Object ppath="/document/root/greetings/*">
 ObjectType fn="nsapi_perl_handler" module="Netscape::HelloWorld"
     sub="content_type" type="text/html"
 Service fn="nsapi_perl_handler" module="Netscape::HelloWorld"
 </Object>

In F<nsapi_perl_init.pl>:
 use Netscape::HelloWorld;

In F<HelloWorld.pm>:

 package Netscape::HelloWorld;
 use strict;