local-lib5/lib/perl5/i486-linux-gnu-thread-multi/FCGI.pm

   1 # $Id: FCGI.PL,v 1.37 2002/12/15 20:02:48 skimo Exp $
   2
   3 package FCGI;
   4
   5 require Exporter;
   6 require DynaLoader;
   7
   8 @ISA = qw(Exporter DynaLoader);
   9 # Items to export into callers namespace by default. Note: do not export
  10 # names by default without a very good reason. Use EXPORT_OK instead.
  11 # Do not simply export all your public functions/methods/constants.
  12 @EXPORT = qw(
  13
  14 );
  15
  16 $VERSION = q{0.71};
  17
  18 bootstrap FCGI;
  19 $VERSION = eval $VERSION;
  20 # Preloaded methods go here.
  21
  22 # Autoload methods go after __END__, and are processed by the autosplit program.
  23
  24 *FAIL_ACCEPT_ON_INTR = sub() { 1 };
  25
  26 sub Request(;***$*$) {
  27     my @defaults = (\*STDIN, \*STDOUT, \*STDERR, \%ENV, 0, 0);
  28     $_[4] = fileno($_[4]) if defined($_[4]) && defined(fileno($_[4]));
  29     splice @defaults,0,@_,@_;
  30     RequestX(@defaults);
  31 }
  32
  33 sub accept() {
  34     warn "accept called as a method; you probably wanted to call Accept" if @_;
  35     if (%FCGI::ENV) {
  36         %ENV = %FCGI::ENV;
  37     } else {
  38         %FCGI::ENV = %ENV;
  39     }
  40     my $rc = Accept($global_request);
  41     for (keys %FCGI::ENV) {
  42         $ENV{$_} = $FCGI::ENV{$_} unless exists $ENV{$_};
  43     }
  44
  45     # not SFIO
  46     $SIG{__WARN__} = $warn_handler if (tied (*STDIN));
  47     $SIG{__DIE__} = $die_handler if (tied (*STDIN));
  48
  49     return $rc;
  50 }
  51
  52 sub finish() {
  53     warn "finish called as a method; you probably wanted to call Finish" if @_;
  54     %ENV = %FCGI::ENV if %FCGI::ENV;
  55
  56     # not SFIO
  57     if (tied (*STDIN)) {
  58         delete $SIG{__WARN__} if ($SIG{__WARN__} == $warn_handler);
  59         delete $SIG{__DIE__} if ($SIG{__DIE__} == $die_handler);
  60     }
  61
  62     Finish ($global_request);
  63 }
  64
  65 sub flush() {
  66     warn "flush called as a method; you probably wanted to call Flush" if @_;
  67     Flush($global_request);
  68 }
  69
  70 sub detach() {
  71     warn "detach called as a method; you probably wanted to call Detach" if @_;
  72     Detach($global_request);
  73 }
  74
  75 sub attach() {
  76     warn "attach called as a method; you probably wanted to call Attach" if @_;
  77     Attach($global_request);
  78 }
  79
  80 # deprecated
  81 sub set_exit_status {
  82 }
  83
  84 sub start_filter_data() {
  85     StartFilterData($global_request);
  86 }
  87
  88 $global_request = Request();
  89 $warn_handler = sub { print STDERR @_ };
  90 $die_handler = sub { print STDERR @_ unless $^S };
  91
  92 package FCGI::Stream;
  93
  94 sub PRINTF {
  95   shift->PRINT(sprintf(shift, @_));
  96 }
  97
  98 sub BINMODE {
  99 }
 100
 101 sub READLINE {
 102     my $stream = shift;
 103     my ($s, $c);
 104     my $rs = $/ eq '' ? "\n\n" : $/;
 105     my $l = substr $rs, -1;
 106     my $len = length $rs;
 107
 108     $c = $stream->GETC();
 109     if ($/ eq '') {
 110         while ($c eq "\n") {
 111             $c = $stream->GETC();
 112         }
 113     }
 114     while (defined $c) {
 115         $s .= $c;
 116         last if $c eq $l and substr($s, -$len) eq $rs;
 117         $c = $stream->GETC();
 118     }
 119     $s;
 120 }
 121
 122 sub OPEN {
 123     $_[0]->CLOSE;
 124     if (@_ == 2) {
 125         return open($_[0], $_[1]);
 126     } else {
 127         my $rc;
 128         eval("$rc = open($_[0], $_[1], $_[2])");
 129         die $@ if $@;
 130         return $rc;
 131     }
 132 }
 133
 134 # Some things (e.g. IPC::Run) use fileno to determine if a filehandle is open,
 135 # so we return a defined, but meaningless value. (-1 being the error return
 136 # value from the syscall in c, meaning it can never be a valid fd no)
 137 # Probably a better alternative would be to return the fcgi stream fd.
 138 sub FILENO { -1 }
 139
 140 1;
 141
 142 =pod
 143
 144 =head1 NAME
 145
 146 FCGI - Fast CGI module
 147
 148 =head1 SYNOPSIS
 149
 150     use FCGI;
 151
 152     my $count = 0;
 153     my $request = FCGI::Request();
 154
 155     while($request->Accept() >= 0) {
 156         print("Content-type: text/html\r\n\r\n", ++$count);
 157     }
 158
 159 =head1 DESCRIPTION
 160
 161 Functions:
 162
 163 =over 4
 164
 165 =item FCGI::Request
 166
 167 Creates a request handle. It has the following optional parameters:
 168
 169 =over 8
 170
 171 =item input perl file handle (default: \*STDIN)
 172
 173 =item output perl file handle (default: \*STDOUT)
 174
 175 =item error perl file handle (default: \*STDERR)
 176
 177 These filehandles will be setup to act as input/output/error
 178 on succesful Accept.
 179
 180 =item environment hash reference (default: \%ENV)
 181
 182 The hash will be populated with the environment.
 183
 184 =item socket (default: 0)
 185
 186 Socket to communicate with the server.
 187 Can be the result of the OpenSocket function.
 188 For the moment, it's the file descriptor of the socket
 189 that should be passed. This may change in the future.
 190
 191 You should only use your own socket if your program
 192 is not started by a process manager such as mod_fastcgi
 193 (except for the FastCgiExternalServer case) or cgi-fcgi.
 194 If you use the option, you have to let your FastCGI
 195 server know which port (and possibly server) your program
 196 is listening on.
 197 See remote.pl for an example.
 198
 199 =item flags (default: 0)
 200
 201 Possible values:
 202
 203 =over 12
 204
 205 =item FCGI::FAIL_ACCEPT_ON_INTR
 206
 207 If set, Accept will fail if interrupted.
 208 It not set, it will just keep on waiting.
 209
 210 =back
 211
 212 =back
 213
 214 Example usage:
 215     my $req = FCGI::Request;
 216
 217 or:
 218     my %env;
 219     my $in = new IO::Handle;
 220     my $out = new IO::Handle;
 221     my $err = new IO::Handle;
 222     my $req = FCGI::Request($in, $out, $err, \%env);
 223
 224 =item FCGI::OpenSocket(path, backlog)
 225
 226 Creates a socket suitable to use as an argument to Request.
 227
 228 =over 8
 229
 230 =item path
 231
 232 Pathname of socket or colon followed by local tcp port.
 233 Note that some systems take file permissions into account
 234 on Unix domain sockets, so you'll have to make sure that
 235 the server can write to the created file, by changing
 236 the umask before the call and/or changing permissions and/or
 237 group of the file afterwards.
 238
 239 =item backlog
 240
 241 Maximum length of the queue of pending connections.
 242 If a connection
 243 request arrives with the queue full the client may receive
 244 an  error  with  an  indication of ECONNREFUSED.
 245
 246 =back
 247
 248 =item FCGI::CloseSocket(socket)
 249
 250 Close a socket opened with OpenSocket.
 251
 252 =item $req->Accept()
 253
 254 Accepts a connection on $req, attaching the filehandles and
 255 populating the environment hash.
 256 Returns 0 on success.
 257 If a connection has been accepted before, the old
 258 one will be finished first.
 259
 260 Note that unlike with the old interface, no die and warn
 261 handlers are installed by default. This means that if
 262 you are not running an sfio enabled perl, any warn or
 263 die message will not end up in the server's log by default.
 264 It is advised you set up die and warn handlers yourself.
 265 FCGI.pm contains an example of die and warn handlers.
 266
 267 =item $req->Finish()
 268
 269 Finishes accepted connection.
 270 Also detaches filehandles.
 271
 272 =item $req->Flush()
 273
 274 Flushes accepted connection.
 275
 276 =item $req->Detach()
 277
 278 Temporarily detaches filehandles on an accepted connection.
 279
 280 =item $req->Attach()
 281
 282 Re-attaches filehandles on an accepted connection.
 283
 284 =item $req->LastCall()
 285
 286 Tells the library not to accept any more requests on this handle.
 287 It should be safe to call this method from signal handlers.
 288
 289 Note that this method is still experimental and everything
 290 about it, including its name, is subject to change.
 291
 292 =item $env = $req->GetEnvironment()
 293
 294 Returns the environment parameter passed to FCGI::Request.
 295
 296 =item ($in, $out, $err) = $req->GetHandles()
 297
 298 Returns the file handle parameters passed to FCGI::Request.
 299
 300 =item $isfcgi = $req->IsFastCGI()
 301
 302 Returns whether or not the program was run as a FastCGI.
 303
 304 =back
 305
 306 =head1 AUTHOR
 307
 308 Sven Verdoolaege <skimo@kotnet.org>
 309
 310 =cut
 311
 312 __END__