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