Commit | Line | Data |
0833402a |
1 | package FCGI; |
043e7beb |
2 | use strict; |
0833402a |
3 | |
043e7beb |
4 | BEGIN { |
8ee94e26 |
5 | our $VERSION = '0.74'; |
0833402a |
6 | |
043e7beb |
7 | require XSLoader; |
8 | XSLoader::load(__PACKAGE__, $VERSION); |
9 | } |
1d209997 |
10 | |
043e7beb |
11 | sub FAIL_ACCEPT_ON_INTR () { 1 }; |
0833402a |
12 | |
ef8432ef |
13 | sub Request(;***$*$) { |
043e7beb |
14 | my @defaults = (\*STDIN, \*STDOUT, \*STDERR, \%ENV, 0, FAIL_ACCEPT_ON_INTR); |
e09efffb |
15 | $_[4] = fileno($_[4]) if defined($_[4]) && defined(fileno($_[4])); |
0833402a |
16 | splice @defaults,0,@_,@_; |
043e7beb |
17 | &RequestX(@defaults); |
0833402a |
18 | } |
1d209997 |
19 | |
0833402a |
20 | package FCGI::Stream; |
043e7beb |
21 | use strict; |
e40fb02c |
22 | |
0833402a |
23 | sub PRINTF { |
24 | shift->PRINT(sprintf(shift, @_)); |
34bfd355 |
25 | } |
26 | |
420df423 |
27 | sub BINMODE { |
28 | } |
29 | |
0833402a |
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 '') { |
77528196 |
39 | while ($c eq "\n") { |
40 | $c = $stream->GETC(); |
41 | } |
0833402a |
42 | } |
43 | while (defined $c) { |
77528196 |
44 | $s .= $c; |
45 | last if $c eq $l and substr($s, -$len) eq $rs; |
46 | $c = $stream->GETC(); |
0833402a |
47 | } |
48 | $s; |
49 | } |
1b64d24d |
50 | |
0833402a |
51 | sub OPEN { |
fd4e384a |
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/); |
0833402a |
69 | } |
1b64d24d |
70 | |
0bbb6895 |
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 } |
497802b1 |
76 | |
0833402a |
77 | 1; |
eede4b76 |
78 | |
0833402a |
79 | =pod |
eede4b76 |
80 | |
0833402a |
81 | =head1 NAME |
eede4b76 |
82 | |
0833402a |
83 | FCGI - Fast CGI module |
eede4b76 |
84 | |
0833402a |
85 | =head1 SYNOPSIS |
6b312a77 |
86 | |
0833402a |
87 | use FCGI; |
6b312a77 |
88 | |
0833402a |
89 | my $count = 0; |
90 | my $request = FCGI::Request(); |
6b312a77 |
91 | |
0833402a |
92 | while($request->Accept() >= 0) { |
77528196 |
93 | print("Content-type: text/html\r\n\r\n", ++$count); |
0833402a |
94 | } |
eede4b76 |
95 | |
0833402a |
96 | =head1 DESCRIPTION |
eede4b76 |
97 | |
0833402a |
98 | Functions: |
eede4b76 |
99 | |
0833402a |
100 | =over 4 |
eede4b76 |
101 | |
0833402a |
102 | =item FCGI::Request |
eede4b76 |
103 | |
0833402a |
104 | Creates a request handle. It has the following optional parameters: |
eede4b76 |
105 | |
0833402a |
106 | =over 8 |
eede4b76 |
107 | |
0833402a |
108 | =item input perl file handle (default: \*STDIN) |
eede4b76 |
109 | |
0833402a |
110 | =item output perl file handle (default: \*STDOUT) |
9915cd6d |
111 | |
0833402a |
112 | =item error perl file handle (default: \*STDERR) |
9915cd6d |
113 | |
0833402a |
114 | These filehandles will be setup to act as input/output/error |
88665260 |
115 | on successful Accept. |
9915cd6d |
116 | |
0833402a |
117 | =item environment hash reference (default: \%ENV) |
9915cd6d |
118 | |
0833402a |
119 | The hash will be populated with the environment. |
9915cd6d |
120 | |
0833402a |
121 | =item socket (default: 0) |
9915cd6d |
122 | |
0833402a |
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. |
9915cd6d |
127 | |
dcdf34f5 |
128 | You should only use your own socket if your program |
129 | is not started by a process manager such as mod_fastcgi |
562f0c66 |
130 | (except for the FastCgiExternalServer case) or cgi-fcgi. |
dcdf34f5 |
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 | |
0833402a |
136 | =item flags (default: 0) |
1d209997 |
137 | |
0833402a |
138 | Possible values: |
1d209997 |
139 | |
0833402a |
140 | =over 12 |
9915cd6d |
141 | |
0833402a |
142 | =item FCGI::FAIL_ACCEPT_ON_INTR |
5baeeca7 |
143 | |
0833402a |
144 | If set, Accept will fail if interrupted. |
145 | It not set, it will just keep on waiting. |
5baeeca7 |
146 | |
0833402a |
147 | =back |
5baeeca7 |
148 | |
0833402a |
149 | =back |
5baeeca7 |
150 | |
0833402a |
151 | Example usage: |
152 | my $req = FCGI::Request; |
5baeeca7 |
153 | |
0833402a |
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); |
5baeeca7 |
160 | |
0833402a |
161 | =item FCGI::OpenSocket(path, backlog) |
5baeeca7 |
162 | |
0833402a |
163 | Creates a socket suitable to use as an argument to Request. |
5baeeca7 |
164 | |
0833402a |
165 | =over 8 |
eede4b76 |
166 | |
0833402a |
167 | =item path |
eede4b76 |
168 | |
0833402a |
169 | Pathname of socket or colon followed by local tcp port. |
420df423 |
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. |
eede4b76 |
175 | |
0833402a |
176 | =item backlog |
eede4b76 |
177 | |
0833402a |
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. |
eede4b76 |
182 | |
0833402a |
183 | =back |
eede4b76 |
184 | |
0833402a |
185 | =item FCGI::CloseSocket(socket) |
eede4b76 |
186 | |
0833402a |
187 | Close a socket opened with OpenSocket. |
eede4b76 |
188 | |
0833402a |
189 | =item $req->Accept() |
90a18d65 |
190 | |
0833402a |
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. |
1b64d24d |
196 | |
0833402a |
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. |
1b64d24d |
203 | |
0833402a |
204 | =item $req->Finish() |
1b64d24d |
205 | |
0833402a |
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. |
1b64d24d |
216 | |
0833402a |
217 | =item $req->Attach() |
218 | |
219 | Re-attaches filehandles on an accepted connection. |
220 | |
7fa2de73 |
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 | |
0833402a |
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 | |
60121417 |
243 | =head1 LIMITATIONS |
929a7b0c |
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 | |
0833402a |
258 | =head1 AUTHOR |
259 | |
260 | Sven Verdoolaege <skimo@kotnet.org> |
261 | |
262 | =cut |
263 | |
264 | __END__ |