perl/FCGI.pm

   1 package FCGI;
   2 use strict;
   3
   4 BEGIN {
   5     our $VERSION = '0.81';
   6
   7     require XSLoader;
   8     XSLoader::load(__PACKAGE__, $VERSION);
   9 }
  10
  11 sub FAIL_ACCEPT_ON_INTR () { 1 };
  12
  13 sub Request(;***$*$) {
  14     my @defaults = (\*STDIN, \*STDOUT, \*STDERR, \%ENV, 0, FAIL_ACCEPT_ON_INTR);
  15     $_[4] = fileno($_[4]) if defined($_[4]) && defined(fileno($_[4]));
  16     splice @defaults,0,@_,@_;
  17     &RequestX(@defaults);
  18 }
  19
  20 package FCGI::Stream;
  21 use strict;
  22
  23 sub PRINTF {
  24   shift->PRINT(sprintf(shift, @_));
  25 }
  26
  27 sub BINMODE {
  28 }
  29
  30 sub READLINE {
  31     my $stream = shift;
  32     my ($s, $c);
  33     my $rs = $/ eq '' ? "\n\n" : $/;
  34     my $l = substr $rs, -1;
  35     my $len = length $rs;
  36
  37     $c = $stream->GETC();
  38     if ($/ eq '') {
  39         while ($c eq "\n") {
  40             $c = $stream->GETC();
  41         }
  42     }
  43     while (defined $c) {
  44         $s .= $c;
  45         last if $c eq $l and substr($s, -$len) eq $rs;
  46         $c = $stream->GETC();
  47     }
  48     $s;
  49 }
  50
  51 sub OPEN {
  52     require Carp;
  53     Carp::croak(q/Operation 'OPEN' not supported on FCGI::Stream handle/);
  54 }
  55
  56 sub SEEK {
  57     require Carp;
  58     Carp::croak(q/Operation 'SEEK' not supported on FCGI::Stream handle/);
  59 }
  60
  61 sub TELL {
  62     require Carp;
  63     Carp::croak(q/Operation 'TELL' not supported on FCGI::Stream handle/);
  64 }
  65
  66 sub TIEHANDLE {
  67     require Carp;
  68     Carp::croak(q/Operation 'TIEHANDLE' not supported on FCGI::Stream handle/);
  69 }
  70
  71 1;
  72
  73 =pod
  74
  75 =head1 NAME
  76
  77 FCGI - Fast CGI module
  78
  79 =head1 SYNOPSIS
  80
  81     use FCGI;
  82
  83     my $count = 0;
  84     my $request = FCGI::Request();
  85
  86     while($request->Accept() >= 0) {
  87         print("Content-type: text/html\r\n\r\n", ++$count);
  88     }
  89
  90 =head1 DESCRIPTION
  91
  92 Functions:
  93
  94 =over 4
  95
  96 =item FCGI::Request
  97
  98 Creates a request handle. It has the following optional parameters:
  99
 100 =over 8
 101
 102 =item input perl file handle (default: \*STDIN)
 103
 104 =item output perl file handle (default: \*STDOUT)
 105
 106 =item error perl file handle (default: \*STDERR)
 107
 108 These filehandles will be setup to act as input/output/error
 109 on successful Accept.
 110
 111 =item environment hash reference (default: \%ENV)
 112
 113 The hash will be populated with the environment.
 114
 115 =item socket (default: 0)
 116
 117 Socket to communicate with the server.
 118 Can be the result of the OpenSocket function.
 119 For the moment, it's the file descriptor of the socket
 120 that should be passed. This may change in the future.
 121
 122 You should only use your own socket if your program
 123 is not started by a process manager such as mod_fastcgi
 124 (except for the FastCgiExternalServer case) or cgi-fcgi.
 125 If you use the option, you have to let your FastCGI
 126 server know which port (and possibly server) your program
 127 is listening on.
 128 See remote.pl for an example.
 129
 130 =item flags (default: FCGI::FAIL_ACCEPT_ON_INTR)
 131
 132 Possible values:
 133
 134 =over 12
 135
 136 =item FCGI::FAIL_ACCEPT_ON_INTR
 137
 138 If set, Accept will fail if interrupted.
 139 It not set, it will just keep on waiting.
 140
 141 =back
 142
 143 =back
 144
 145 Example usage:
 146     my $req = FCGI::Request;
 147
 148 or:
 149     my %env;
 150     my $in = new IO::Handle;
 151     my $out = new IO::Handle;
 152     my $err = new IO::Handle;
 153     my $req = FCGI::Request($in, $out, $err, \%env);
 154
 155 =item FCGI::OpenSocket(path, backlog)
 156
 157 Creates a socket suitable to use as an argument to Request.
 158
 159 =over 8
 160
 161 =item path
 162
 163 Pathname of socket or colon followed by local tcp port.
 164 Note that some systems take file permissions into account
 165 on Unix domain sockets, so you'll have to make sure that
 166 the server can write to the created file, by changing
 167 the umask before the call and/or changing permissions and/or
 168 group of the file afterwards.
 169
 170 =item backlog
 171
 172 Maximum length of the queue of pending connections.
 173 If a connection
 174 request arrives with the queue full the client may receive
 175 an  error  with  an  indication of ECONNREFUSED.
 176
 177 =back
 178
 179 =item FCGI::CloseSocket(socket)
 180
 181 Close a socket opened with OpenSocket.
 182
 183 =item $req->Accept()
 184
 185 Accepts a connection on $req, attaching the filehandles and
 186 populating the environment hash.
 187 Returns 0 on success.
 188 If a connection has been accepted before, the old
 189 one will be finished first.
 190
 191 Note that unlike with the old interface, no die and warn
 192 handlers are installed by default. This means that if
 193 you are not running an sfio enabled perl, any warn or
 194 die message will not end up in the server's log by default.
 195 It is advised you set up die and warn handlers yourself.
 196 FCGI.pm contains an example of die and warn handlers.
 197
 198 =item $req->Finish()
 199
 200 Finishes accepted connection.
 201 Also detaches filehandles.
 202
 203 =item $req->Flush()
 204
 205 Flushes accepted connection.
 206
 207 =item $req->Detach()
 208
 209 Temporarily detaches filehandles on an accepted connection.
 210
 211 =item $req->Attach()
 212
 213 Re-attaches filehandles on an accepted connection.
 214
 215 =item $req->LastCall()
 216
 217 Tells the library not to accept any more requests on this handle.
 218 It should be safe to call this method from signal handlers.
 219
 220 Note that this method is still experimental and everything
 221 about it, including its name, is subject to change.
 222
 223 =item $env = $req->GetEnvironment()
 224
 225 Returns the environment parameter passed to FCGI::Request.
 226
 227 =item ($in, $out, $err) = $req->GetHandles()
 228
 229 Returns the file handle parameters passed to FCGI::Request.
 230
 231 =item $isfcgi = $req->IsFastCGI()
 232
 233 Returns whether or not the program was run as a FastCGI.
 234
 235 =back
 236
 237 =head1 LIMITATIONS
 238
 239 FCGI.pm isn't Unicode aware, only characters within the range 0x00-0xFF are
 240 supported. Attempts to output strings containing characters above 0xFF results
 241 in a exception: (F) C<Wide character in %s>.
 242
 243 Users who wants the previous (FCGI.pm <= 0.68) incorrect behavior can disable the
 244 exception by using the C<bytes> pragma.
 245
 246     {
 247         use bytes;
 248         print "\x{263A}";
 249     }
 250
 251
 252 =head1 AUTHOR
 253
 254 Sven Verdoolaege <skimo@kotnet.org>
 255
 256 =head1 COPYRIGHT AND LICENCE
 257
 258 This software is copyrighted (c) 1996 by by Open Market, Inc.
 259
 260 See the LICENSE file in this distribution for information on usage and
 261 redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 262
 263 =cut
 264
 265 __END__