perl/FCGI.pm

   1 package FCGI;
   2 use strict;
   3
   4 BEGIN {
   5     our $VERSION = '0.74';
   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 # Some things (e.g. IPC::Run) use fileno to determine if a filehandle is open,
  72 # so we return a defined, but meaningless value. (-1 being the error return
  73 # value from the syscall in c, meaning it can never be a valid fd no)
  74 # Probably a better alternative would be to return the fcgi stream fd.
  75 sub FILENO { -1 }
  76
  77 1;
  78
  79 =pod
  80
  81 =head1 NAME
  82
  83 FCGI - Fast CGI module
  84
  85 =head1 SYNOPSIS
  86
  87     use FCGI;
  88
  89     my $count = 0;
  90     my $request = FCGI::Request();
  91
  92     while($request->Accept() >= 0) {
  93         print("Content-type: text/html\r\n\r\n", ++$count);
  94     }
  95
  96 =head1 DESCRIPTION
  97
  98 Functions:
  99
 100 =over 4
 101
 102 =item FCGI::Request
 103
 104 Creates a request handle. It has the following optional parameters:
 105
 106 =over 8
 107
 108 =item input perl file handle (default: \*STDIN)
 109
 110 =item output perl file handle (default: \*STDOUT)
 111
 112 =item error perl file handle (default: \*STDERR)
 113
 114 These filehandles will be setup to act as input/output/error
 115 on successful Accept.
 116
 117 =item environment hash reference (default: \%ENV)
 118
 119 The hash will be populated with the environment.
 120
 121 =item socket (default: 0)
 122
 123 Socket to communicate with the server.
 124 Can be the result of the OpenSocket function.
 125 For the moment, it's the file descriptor of the socket
 126 that should be passed. This may change in the future.
 127
 128 You should only use your own socket if your program
 129 is not started by a process manager such as mod_fastcgi
 130 (except for the FastCgiExternalServer case) or cgi-fcgi.
 131 If you use the option, you have to let your FastCGI
 132 server know which port (and possibly server) your program
 133 is listening on.
 134 See remote.pl for an example.
 135
 136 =item flags (default: 0)
 137
 138 Possible values:
 139
 140 =over 12
 141
 142 =item FCGI::FAIL_ACCEPT_ON_INTR
 143
 144 If set, Accept will fail if interrupted.
 145 It not set, it will just keep on waiting.
 146
 147 =back
 148
 149 =back
 150
 151 Example usage:
 152     my $req = FCGI::Request;
 153
 154 or:
 155     my %env;
 156     my $in = new IO::Handle;
 157     my $out = new IO::Handle;
 158     my $err = new IO::Handle;
 159     my $req = FCGI::Request($in, $out, $err, \%env);
 160
 161 =item FCGI::OpenSocket(path, backlog)
 162
 163 Creates a socket suitable to use as an argument to Request.
 164
 165 =over 8
 166
 167 =item path
 168
 169 Pathname of socket or colon followed by local tcp port.
 170 Note that some systems take file permissions into account
 171 on Unix domain sockets, so you'll have to make sure that
 172 the server can write to the created file, by changing
 173 the umask before the call and/or changing permissions and/or
 174 group of the file afterwards.
 175
 176 =item backlog
 177
 178 Maximum length of the queue of pending connections.
 179 If a connection
 180 request arrives with the queue full the client may receive
 181 an  error  with  an  indication of ECONNREFUSED.
 182
 183 =back
 184
 185 =item FCGI::CloseSocket(socket)
 186
 187 Close a socket opened with OpenSocket.
 188
 189 =item $req->Accept()
 190
 191 Accepts a connection on $req, attaching the filehandles and
 192 populating the environment hash.
 193 Returns 0 on success.
 194 If a connection has been accepted before, the old
 195 one will be finished first.
 196
 197 Note that unlike with the old interface, no die and warn
 198 handlers are installed by default. This means that if
 199 you are not running an sfio enabled perl, any warn or
 200 die message will not end up in the server's log by default.
 201 It is advised you set up die and warn handlers yourself.
 202 FCGI.pm contains an example of die and warn handlers.
 203
 204 =item $req->Finish()
 205
 206 Finishes accepted connection.
 207 Also detaches filehandles.
 208
 209 =item $req->Flush()
 210
 211 Flushes accepted connection.
 212
 213 =item $req->Detach()
 214
 215 Temporarily detaches filehandles on an accepted connection.
 216
 217 =item $req->Attach()
 218
 219 Re-attaches filehandles on an accepted connection.
 220
 221 =item $req->LastCall()
 222
 223 Tells the library not to accept any more requests on this handle.
 224 It should be safe to call this method from signal handlers.
 225
 226 Note that this method is still experimental and everything
 227 about it, including its name, is subject to change.
 228
 229 =item $env = $req->GetEnvironment()
 230
 231 Returns the environment parameter passed to FCGI::Request.
 232
 233 =item ($in, $out, $err) = $req->GetHandles()
 234
 235 Returns the file handle parameters passed to FCGI::Request.
 236
 237 =item $isfcgi = $req->IsFastCGI()
 238
 239 Returns whether or not the program was run as a FastCGI.
 240
 241 =back
 242
 243 =head1 LIMITATIONS
 244
 245 FCGI.pm isn't Unicode aware, only characters within the range 0x00-0xFF are
 246 supported. Attempts to output strings containing characters above 0xFF results
 247 in a exception: (F) C<Wide character in %s>.
 248
 249 Users who wants the previous (FCGI.pm <= 0.68) incorrect behavior can disable the
 250 exception by using the C<bytes> pragma.
 251
 252     {
 253         use bytes;
 254         print "\x{263A}";
 255     }
 256
 257
 258 =head1 AUTHOR
 259
 260 Sven Verdoolaege <skimo@kotnet.org>
 261
 262 =cut
 263
 264 __END__