FCGI

[catagits/Gitalist.git] / local-lib5 / man / man3 / FCGI.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "FCGI 3"
.TH FCGI 3 "2010-05-28" "perl v5.8.8" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
FCGI \- Fast CGI module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use FCGI;
\&
\&    my $count = 0;
\&    my $request = FCGI::Request();
\&
\&    while($request\->Accept() >= 0) {
\&        print("Content\-type: text/html\er\en\er\en", ++$count);
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Functions:
.IP "FCGI::Request" 4
.IX Item "FCGI::Request"
Creates a request handle. It has the following optional parameters:
.RS 4
.IP "input perl file handle (default: \e*STDIN)" 8
.IX Item "input perl file handle (default: *STDIN)"
.PD 0
.IP "output perl file handle (default: \e*STDOUT)" 8
.IX Item "output perl file handle (default: *STDOUT)"
.IP "error perl file handle (default: \e*STDERR)" 8
.IX Item "error perl file handle (default: *STDERR)"
.PD
These filehandles will be setup to act as input/output/error
on succesful Accept.
.IP "environment hash reference (default: \e%ENV)" 8
.IX Item "environment hash reference (default: %ENV)"
The hash will be populated with the environment.
.IP "socket (default: 0)" 8
.IX Item "socket (default: 0)"
Socket to communicate with the server.
Can be the result of the OpenSocket function.
For the moment, it's the file descriptor of the socket
that should be passed. This may change in the future.
.Sp
You should only use your own socket if your program
is not started by a process manager such as mod_fastcgi
(except for the FastCgiExternalServer case) or cgi-fcgi.
If you use the option, you have to let your FastCGI
server know which port (and possibly server) your program
is listening on.
See remote.pl for an example.
.IP "flags (default: 0)" 8
.IX Item "flags (default: 0)"
Possible values:
.RS 8
.IP "\s-1FCGI::FAIL_ACCEPT_ON_INTR\s0" 12
.IX Item "FCGI::FAIL_ACCEPT_ON_INTR"
If set, Accept will fail if interrupted.
It not set, it will just keep on waiting.
.RE
.RS 8
.RE
.RE
.RS 4
.Sp
Example usage:
    my \f(CW$req\fR = FCGI::Request;
.Sp
or:
    my \f(CW%env\fR;
    my \f(CW$in\fR = new IO::Handle;
    my \f(CW$out\fR = new IO::Handle;
    my \f(CW$err\fR = new IO::Handle;
    my \f(CW$req\fR = FCGI::Request($in, \f(CW$out\fR, \f(CW$err\fR, \e%env);
.RE
.IP "FCGI::OpenSocket(path, backlog)" 4
.IX Item "FCGI::OpenSocket(path, backlog)"
Creates a socket suitable to use as an argument to Request.
.RS 4
.IP "path" 8
.IX Item "path"
Pathname of socket or colon followed by local tcp port.
Note that some systems take file permissions into account
on Unix domain sockets, so you'll have to make sure that
the server can write to the created file, by changing
the umask before the call and/or changing permissions and/or
group of the file afterwards.
.IP "backlog" 8
.IX Item "backlog"
Maximum length of the queue of pending connections.
If a connection
request arrives with the queue full the client may receive
an  error  with  an  indication of \s-1ECONNREFUSED\s0.
.RE
.RS 4
.RE
.IP "FCGI::CloseSocket(socket)" 4
.IX Item "FCGI::CloseSocket(socket)"
Close a socket opened with OpenSocket.
.ie n .IP "$req\->\fIAccept()\fR" 4
.el .IP "\f(CW$req\fR\->\fIAccept()\fR" 4
.IX Item "$req->Accept()"
Accepts a connection on \f(CW$req\fR, attaching the filehandles and
populating the environment hash.
Returns 0 on success.
If a connection has been accepted before, the old
one will be finished first.
.Sp
Note that unlike with the old interface, no die and warn
handlers are installed by default. This means that if
you are not running an sfio enabled perl, any warn or
die message will not end up in the server's log by default.
It is advised you set up die and warn handlers yourself.
\&\s-1FCGI\s0.pm contains an example of die and warn handlers.
.ie n .IP "$req\->\fIFinish()\fR" 4
.el .IP "\f(CW$req\fR\->\fIFinish()\fR" 4
.IX Item "$req->Finish()"
Finishes accepted connection.
Also detaches filehandles.
.ie n .IP "$req\->\fIFlush()\fR" 4
.el .IP "\f(CW$req\fR\->\fIFlush()\fR" 4
.IX Item "$req->Flush()"
Flushes accepted connection.
.ie n .IP "$req\->\fIDetach()\fR" 4
.el .IP "\f(CW$req\fR\->\fIDetach()\fR" 4
.IX Item "$req->Detach()"
Temporarily detaches filehandles on an accepted connection.
.ie n .IP "$req\->\fIAttach()\fR" 4
.el .IP "\f(CW$req\fR\->\fIAttach()\fR" 4
.IX Item "$req->Attach()"
Re-attaches filehandles on an accepted connection.
.ie n .IP "$req\->\fILastCall()\fR" 4
.el .IP "\f(CW$req\fR\->\fILastCall()\fR" 4
.IX Item "$req->LastCall()"
Tells the library not to accept any more requests on this handle.
It should be safe to call this method from signal handlers.
.Sp
Note that this method is still experimental and everything
about it, including its name, is subject to change.
.ie n .IP "$env = $req\->\fIGetEnvironment()\fR" 4
.el .IP "\f(CW$env\fR = \f(CW$req\fR\->\fIGetEnvironment()\fR" 4
.IX Item "$env = $req->GetEnvironment()"
Returns the environment parameter passed to FCGI::Request.
.ie n .IP "($in, $out, $err) = $req\->\fIGetHandles()\fR" 4
.el .IP "($in, \f(CW$out\fR, \f(CW$err\fR) = \f(CW$req\fR\->\fIGetHandles()\fR" 4
.IX Item "($in, $out, $err) = $req->GetHandles()"
Returns the file handle parameters passed to FCGI::Request.
.ie n .IP "$isfcgi = $req\->\fIIsFastCGI()\fR" 4
.el .IP "\f(CW$isfcgi\fR = \f(CW$req\fR\->\fIIsFastCGI()\fR" 4
.IX Item "$isfcgi = $req->IsFastCGI()"
Returns whether or not the program was run as a FastCGI.
.SH "AUTHOR"
.IX Header "AUTHOR"
Sven Verdoolaege <skimo@kotnet.org>