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