perl/FCGI.PL

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