perl/FCGI.pm

   1 # $Id: FCGI.pm,v 1.17 2000/11/12 13:11:13 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 = '0.57';
  17
  18 bootstrap FCGI;
  19
  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     splice @defaults,0,@_,@_;
  29     RequestX(@defaults);
  30 }
  31
  32 sub accept() {
  33     warn "accept called as a method; you probably wanted to call Accept" if @_;
  34     if (defined %FCGI::ENV) {
  35         %ENV = %FCGI::ENV;
  36     } else {
  37         %FCGI::ENV = %ENV;
  38     }
  39     my $rc = Accept($global_request);
  40     for (keys %FCGI::ENV) {
  41         $ENV{$_} = $FCGI::ENV{$_} unless exists $ENV{$_};
  42     }
  43
  44     # not SFIO
  45     $SIG{__WARN__} = $warn_handler if (tied (*STDIN));
  46     $SIG{__DIE__} = $die_handler if (tied (*STDIN));
  47
  48     return $rc;
  49 }
  50
  51 sub finish() {
  52     warn "finish called as a method; you probably wanted to call Finish" if @_;
  53     %ENV = %FCGI::ENV if (defined %FCGI::ENV);
  54
  55     # not SFIO
  56     if (tied (*STDIN)) {
  57         delete $SIG{__WARN__} if ($SIG{__WARN__} == $warn_handler);
  58         delete $SIG{__DIE__} if ($SIG{__DIE__} == $die_handler);
  59     }
  60
  61     Finish ($global_request);
  62 }
  63
  64 sub flush() {
  65     warn "flush called as a method; you probably wanted to call Flush" if @_;
  66     Flush($global_request);
  67 }
  68
  69 sub detach() {
  70     warn "detach called as a method; you probably wanted to call Detach" if @_;
  71     Detach($global_request);
  72 }
  73
  74 sub attach() {
  75     warn "attach called as a method; you probably wanted to call Attach" if @_;
  76     Attach($global_request);
  77 }
  78
  79 # deprecated
  80 sub set_exit_status {
  81 }
  82
  83 sub start_filter_data() {
  84     StartFilterData($global_request);
  85 }
  86
  87 $global_request = Request();
  88 $warn_handler = sub { print STDERR @_ };
  89 $die_handler = sub { print STDERR @_ unless $^S };
  90
  91 package FCGI::Stream;
  92
  93 sub PRINTF {
  94   shift->PRINT(sprintf(shift, @_));
  95 }
  96
  97 sub READLINE {
  98     my $stream = shift;
  99     my ($s, $c);
 100     my $rs = $/ eq '' ? "\n\n" : $/;
 101     my $l = substr $rs, -1;
 102     my $len = length $rs;
 103
 104     $c = $stream->GETC();
 105     if ($/ eq '') {
 106         while ($c eq "\n") {
 107             $c = $stream->GETC();
 108         }
 109     }
 110     while (defined $c) {
 111         $s .= $c;
 112         last if $c eq $l and substr($s, -$len) eq $rs;
 113         $c = $stream->GETC();
 114     }
 115     $s;
 116 }
 117
 118 sub OPEN {
 119     $_[0]->CLOSE;
 120     if (@_ == 2) {
 121         return open($_[0], $_[1]);
 122     } else {
 123         my $rc;
 124         eval("$rc = open($_[0], $_[1], $_[2])");
 125         die $@ if $@;
 126         return $rc;
 127     }
 128 }
 129
 130 1;
 131
 132 =pod
 133
 134 =head1 NAME
 135
 136 FCGI - Fast CGI module
 137
 138 =head1 SYNOPSIS
 139
 140     use FCGI;
 141
 142     my $count = 0;
 143     my $request = FCGI::Request();
 144
 145     while($request->Accept() >= 0) {
 146         print("Content-type: text/html\r\n\r\n", ++$count);
 147     }
 148
 149 =head1 DESCRIPTION
 150
 151 Functions:
 152
 153 =over 4
 154
 155 =item FCGI::Request
 156
 157 Creates a request handle. It has the following optional parameters:
 158
 159 =over 8
 160
 161 =item input perl file handle (default: \*STDIN)
 162
 163 =item output perl file handle (default: \*STDOUT)
 164
 165 =item error perl file handle (default: \*STDERR)
 166
 167 These filehandles will be setup to act as input/output/error
 168 on succesful Accept.
 169
 170 =item environment hash reference (default: \%ENV)
 171
 172 The hash will be populated with the environment.
 173
 174 =item socket (default: 0)
 175
 176 Socket to communicate with the server.
 177 Can be the result of the OpenSocket function.
 178 For the moment, it's the file descriptor of the socket
 179 that should be passed. This may change in the future.
 180
 181 =item flags (default: 0)
 182
 183 Possible values:
 184
 185 =over 12
 186
 187 =item FCGI::FAIL_ACCEPT_ON_INTR
 188
 189 If set, Accept will fail if interrupted.
 190 It not set, it will just keep on waiting.
 191
 192 =back
 193
 194 =back
 195
 196 Example usage:
 197     my $req = FCGI::Request;
 198
 199 or:
 200     my %env;
 201     my $in = new IO::Handle;
 202     my $out = new IO::Handle;
 203     my $err = new IO::Handle;
 204     my $req = FCGI::Request($in, $out, $err, \%env);
 205
 206 =item FCGI::OpenSocket(path, backlog)
 207
 208 Creates a socket suitable to use as an argument to Request.
 209
 210 =over 8
 211
 212 =item path
 213
 214 Pathname of socket or colon followed by local tcp port.
 215
 216 =item backlog
 217
 218 Maximum length of the queue of pending connections.
 219 If a connection
 220 request arrives with the queue full the client may receive
 221 an  error  with  an  indication of ECONNREFUSED.
 222
 223 =back
 224
 225 =item FCGI::CloseSocket(socket)
 226
 227 Close a socket opened with OpenSocket.
 228
 229 =item $req->Accept()
 230
 231 Accepts a connection on $req, attaching the filehandles and
 232 populating the environment hash.
 233 Returns 0 on success.
 234 If a connection has been accepted before, the old
 235 one will be finished first.
 236
 237 Note that unlike with the old interface, no die and warn
 238 handlers are installed by default. This means that if
 239 you are not running an sfio enabled perl, any warn or
 240 die message will not end up in the server's log by default.
 241 It is advised you set up die and warn handlers yourself.
 242 FCGI.pm contains an example of die and warn handlers.
 243
 244 =item $req->Finish()
 245
 246 Finishes accepted connection.
 247 Also detaches filehandles.
 248
 249 =item $req->Flush()
 250
 251 Flushes accepted connection.
 252
 253 =item $req->Detach()
 254
 255 Temporarily detaches filehandles on an accepted connection.
 256
 257 =item $req->Attach()
 258
 259 Re-attaches filehandles on an accepted connection.
 260
 261 =item $env = $req->GetEnvironment()
 262
 263 Returns the environment parameter passed to FCGI::Request.
 264
 265 =item ($in, $out, $err) = $req->GetHandles()
 266
 267 Returns the file handle parameters passed to FCGI::Request.
 268
 269 =item $isfcgi = $req->IsFastCGI()
 270
 271 Returns whether or not the program was run as a FastCGI.
 272
 273 =back
 274
 275 =head1 AUTHOR
 276
 277 Sven Verdoolaege <skimo@kotnet.org>
 278
 279 =cut
 280
 281 __END__