local-lib5/man/man3/FCGI.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "FCGI 3"
 127 .TH FCGI 3 "2010-05-28" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 FCGI \- Fast CGI module
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use FCGI;
 138 \&
 139 \&    my $count = 0;
 140 \&    my $request = FCGI::Request();
 141 \&
 142 \&    while($request\->Accept() >= 0) {
 143 \&        print("Content\-type: text/html\er\en\er\en", ++$count);
 144 \&    }
 145 .Ve
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 Functions:
 149 .IP "FCGI::Request" 4
 150 .IX Item "FCGI::Request"
 151 Creates a request handle. It has the following optional parameters:
 152 .RS 4
 153 .IP "input perl file handle (default: \e*STDIN)" 8
 154 .IX Item "input perl file handle (default: *STDIN)"
 155 .PD 0
 156 .IP "output perl file handle (default: \e*STDOUT)" 8
 157 .IX Item "output perl file handle (default: *STDOUT)"
 158 .IP "error perl file handle (default: \e*STDERR)" 8
 159 .IX Item "error perl file handle (default: *STDERR)"
 160 .PD
 161 These filehandles will be setup to act as input/output/error
 162 on succesful Accept.
 163 .IP "environment hash reference (default: \e%ENV)" 8
 164 .IX Item "environment hash reference (default: %ENV)"
 165 The hash will be populated with the environment.
 166 .IP "socket (default: 0)" 8
 167 .IX Item "socket (default: 0)"
 168 Socket to communicate with the server.
 169 Can be the result of the OpenSocket function.
 170 For the moment, it's the file descriptor of the socket
 171 that should be passed. This may change in the future.
 172 .Sp
 173 You should only use your own socket if your program
 174 is not started by a process manager such as mod_fastcgi
 175 (except for the FastCgiExternalServer case) or cgi-fcgi.
 176 If you use the option, you have to let your FastCGI
 177 server know which port (and possibly server) your program
 178 is listening on.
 179 See remote.pl for an example.
 180 .IP "flags (default: 0)" 8
 181 .IX Item "flags (default: 0)"
 182 Possible values:
 183 .RS 8
 184 .IP "\s-1FCGI::FAIL_ACCEPT_ON_INTR\s0" 12
 185 .IX Item "FCGI::FAIL_ACCEPT_ON_INTR"
 186 If set, Accept will fail if interrupted.
 187 It not set, it will just keep on waiting.
 188 .RE
 189 .RS 8
 190 .RE
 191 .RE
 192 .RS 4
 193 .Sp
 194 Example usage:
 195     my \f(CW$req\fR = FCGI::Request;
 196 .Sp
 197 or:
 198     my \f(CW%env\fR;
 199     my \f(CW$in\fR = new IO::Handle;
 200     my \f(CW$out\fR = new IO::Handle;
 201     my \f(CW$err\fR = new IO::Handle;
 202     my \f(CW$req\fR = FCGI::Request($in, \f(CW$out\fR, \f(CW$err\fR, \e%env);
 203 .RE
 204 .IP "FCGI::OpenSocket(path, backlog)" 4
 205 .IX Item "FCGI::OpenSocket(path, backlog)"
 206 Creates a socket suitable to use as an argument to Request.
 207 .RS 4
 208 .IP "path" 8
 209 .IX Item "path"
 210 Pathname of socket or colon followed by local tcp port.
 211 Note that some systems take file permissions into account
 212 on Unix domain sockets, so you'll have to make sure that
 213 the server can write to the created file, by changing
 214 the umask before the call and/or changing permissions and/or
 215 group of the file afterwards.
 216 .IP "backlog" 8
 217 .IX Item "backlog"
 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 \s-1ECONNREFUSED\s0.
 222 .RE
 223 .RS 4
 224 .RE
 225 .IP "FCGI::CloseSocket(socket)" 4
 226 .IX Item "FCGI::CloseSocket(socket)"
 227 Close a socket opened with OpenSocket.
 228 .ie n .IP "$req\->\fIAccept()\fR" 4
 229 .el .IP "\f(CW$req\fR\->\fIAccept()\fR" 4
 230 .IX Item "$req->Accept()"
 231 Accepts a connection on \f(CW$req\fR, 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 .Sp
 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 \&\s-1FCGI\s0.pm contains an example of die and warn handlers.
 243 .ie n .IP "$req\->\fIFinish()\fR" 4
 244 .el .IP "\f(CW$req\fR\->\fIFinish()\fR" 4
 245 .IX Item "$req->Finish()"
 246 Finishes accepted connection.
 247 Also detaches filehandles.
 248 .ie n .IP "$req\->\fIFlush()\fR" 4
 249 .el .IP "\f(CW$req\fR\->\fIFlush()\fR" 4
 250 .IX Item "$req->Flush()"
 251 Flushes accepted connection.
 252 .ie n .IP "$req\->\fIDetach()\fR" 4
 253 .el .IP "\f(CW$req\fR\->\fIDetach()\fR" 4
 254 .IX Item "$req->Detach()"
 255 Temporarily detaches filehandles on an accepted connection.
 256 .ie n .IP "$req\->\fIAttach()\fR" 4
 257 .el .IP "\f(CW$req\fR\->\fIAttach()\fR" 4
 258 .IX Item "$req->Attach()"
 259 Re-attaches filehandles on an accepted connection.
 260 .ie n .IP "$req\->\fILastCall()\fR" 4
 261 .el .IP "\f(CW$req\fR\->\fILastCall()\fR" 4
 262 .IX Item "$req->LastCall()"
 263 Tells the library not to accept any more requests on this handle.
 264 It should be safe to call this method from signal handlers.
 265 .Sp
 266 Note that this method is still experimental and everything
 267 about it, including its name, is subject to change.
 268 .ie n .IP "$env = $req\->\fIGetEnvironment()\fR" 4
 269 .el .IP "\f(CW$env\fR = \f(CW$req\fR\->\fIGetEnvironment()\fR" 4
 270 .IX Item "$env = $req->GetEnvironment()"
 271 Returns the environment parameter passed to FCGI::Request.
 272 .ie n .IP "($in, $out, $err) = $req\->\fIGetHandles()\fR" 4
 273 .el .IP "($in, \f(CW$out\fR, \f(CW$err\fR) = \f(CW$req\fR\->\fIGetHandles()\fR" 4
 274 .IX Item "($in, $out, $err) = $req->GetHandles()"
 275 Returns the file handle parameters passed to FCGI::Request.
 276 .ie n .IP "$isfcgi = $req\->\fIIsFastCGI()\fR" 4
 277 .el .IP "\f(CW$isfcgi\fR = \f(CW$req\fR\->\fIIsFastCGI()\fR" 4
 278 .IX Item "$isfcgi = $req->IsFastCGI()"
 279 Returns whether or not the program was run as a FastCGI.
 280 .SH "AUTHOR"
 281 .IX Header "AUTHOR"
 282 Sven Verdoolaege <skimo@kotnet.org>