Commit | Line | Data |
1b64d24d |
1 | use Config; |
fa01dc1c |
2 | use ExtUtils::MakeMaker; |
1b64d24d |
3 | |
0833402a |
4 | open OUT, ">FCGI.pm"; |
5 | |
6 | print "Generating FCGI.pm\n"; |
7 | print OUT <<'EOP'; |
9aa25e66 |
8 | # $Id: FCGI.PL,v 1.37 2002/12/15 20:02:48 skimo Exp $ |
0833402a |
9 | |
10 | package FCGI; |
11 | |
12 | require Exporter; |
13 | require DynaLoader; |
14 | |
15 | @ISA = qw(Exporter DynaLoader); |
16 | # Items to export into callers namespace by default. Note: do not export |
17 | # names by default without a very good reason. Use EXPORT_OK instead. |
18 | # Do not simply export all your public functions/methods/constants. |
19 | @EXPORT = qw( |
562f0c66 |
20 | |
0833402a |
21 | ); |
22 | |
0833402a |
23 | EOP |
24 | |
21b4f5ec |
25 | print OUT '$VERSION = q{'.MM->parse_version('version.pm')."};\n\n"; |
4945bfbe |
26 | |
08461774 |
27 | print OUT "bootstrap FCGI;\n"; |
0833402a |
28 | |
21b4f5ec |
29 | print OUT '$VERSION = eval $VERSION;'; |
30 | |
0833402a |
31 | print OUT while <DATA>; |
32 | close OUT; |
33 | __END__ |
34 | |
35 | # Preloaded methods go here. |
794c66be |
36 | |
0833402a |
37 | # Autoload methods go after __END__, and are processed by the autosplit program. |
1d209997 |
38 | |
0833402a |
39 | *FAIL_ACCEPT_ON_INTR = sub() { 1 }; |
40 | |
ef8432ef |
41 | sub Request(;***$*$) { |
f85665ba |
42 | my @defaults = (\*STDIN, \*STDOUT, \*STDERR, \%ENV, 0, FAIL_ACCEPT_ON_INTR()); |
e09efffb |
43 | $_[4] = fileno($_[4]) if defined($_[4]) && defined(fileno($_[4])); |
0833402a |
44 | splice @defaults,0,@_,@_; |
45 | RequestX(@defaults); |
46 | } |
1d209997 |
47 | |
0833402a |
48 | package FCGI::Stream; |
e40fb02c |
49 | |
0833402a |
50 | sub PRINTF { |
51 | shift->PRINT(sprintf(shift, @_)); |
34bfd355 |
52 | } |
53 | |
420df423 |
54 | sub BINMODE { |
55 | } |
56 | |
0833402a |
57 | sub READLINE { |
58 | my $stream = shift; |
59 | my ($s, $c); |
60 | my $rs = $/ eq '' ? "\n\n" : $/; |
61 | my $l = substr $rs, -1; |
62 | my $len = length $rs; |
63 | |
64 | $c = $stream->GETC(); |
65 | if ($/ eq '') { |
77528196 |
66 | while ($c eq "\n") { |
67 | $c = $stream->GETC(); |
68 | } |
0833402a |
69 | } |
70 | while (defined $c) { |
77528196 |
71 | $s .= $c; |
72 | last if $c eq $l and substr($s, -$len) eq $rs; |
73 | $c = $stream->GETC(); |
0833402a |
74 | } |
75 | $s; |
76 | } |
1b64d24d |
77 | |
0833402a |
78 | sub OPEN { |
79 | $_[0]->CLOSE; |
80 | if (@_ == 2) { |
77528196 |
81 | return open($_[0], $_[1]); |
0833402a |
82 | } else { |
77528196 |
83 | my $rc; |
84 | eval("$rc = open($_[0], $_[1], $_[2])"); |
85 | die $@ if $@; |
86 | return $rc; |
0833402a |
87 | } |
88 | } |
1b64d24d |
89 | |
0bbb6895 |
90 | # Some things (e.g. IPC::Run) use fileno to determine if a filehandle is open, |
91 | # so we return a defined, but meaningless value. (-1 being the error return |
92 | # value from the syscall in c, meaning it can never be a valid fd no) |
93 | # Probably a better alternative would be to return the fcgi stream fd. |
94 | sub FILENO { -1 } |
497802b1 |
95 | |
0833402a |
96 | 1; |
eede4b76 |
97 | |
0833402a |
98 | =pod |
eede4b76 |
99 | |
0833402a |
100 | =head1 NAME |
eede4b76 |
101 | |
0833402a |
102 | FCGI - Fast CGI module |
eede4b76 |
103 | |
0833402a |
104 | =head1 SYNOPSIS |
6b312a77 |
105 | |
0833402a |
106 | use FCGI; |
6b312a77 |
107 | |
0833402a |
108 | my $count = 0; |
109 | my $request = FCGI::Request(); |
6b312a77 |
110 | |
0833402a |
111 | while($request->Accept() >= 0) { |
77528196 |
112 | print("Content-type: text/html\r\n\r\n", ++$count); |
0833402a |
113 | } |
eede4b76 |
114 | |
0833402a |
115 | =head1 DESCRIPTION |
eede4b76 |
116 | |
0833402a |
117 | Functions: |
eede4b76 |
118 | |
0833402a |
119 | =over 4 |
eede4b76 |
120 | |
0833402a |
121 | =item FCGI::Request |
eede4b76 |
122 | |
0833402a |
123 | Creates a request handle. It has the following optional parameters: |
eede4b76 |
124 | |
0833402a |
125 | =over 8 |
eede4b76 |
126 | |
0833402a |
127 | =item input perl file handle (default: \*STDIN) |
eede4b76 |
128 | |
0833402a |
129 | =item output perl file handle (default: \*STDOUT) |
9915cd6d |
130 | |
0833402a |
131 | =item error perl file handle (default: \*STDERR) |
9915cd6d |
132 | |
0833402a |
133 | These filehandles will be setup to act as input/output/error |
88665260 |
134 | on successful Accept. |
9915cd6d |
135 | |
0833402a |
136 | =item environment hash reference (default: \%ENV) |
9915cd6d |
137 | |
0833402a |
138 | The hash will be populated with the environment. |
9915cd6d |
139 | |
0833402a |
140 | =item socket (default: 0) |
9915cd6d |
141 | |
0833402a |
142 | Socket to communicate with the server. |
143 | Can be the result of the OpenSocket function. |
144 | For the moment, it's the file descriptor of the socket |
145 | that should be passed. This may change in the future. |
9915cd6d |
146 | |
dcdf34f5 |
147 | You should only use your own socket if your program |
148 | is not started by a process manager such as mod_fastcgi |
562f0c66 |
149 | (except for the FastCgiExternalServer case) or cgi-fcgi. |
dcdf34f5 |
150 | If you use the option, you have to let your FastCGI |
151 | server know which port (and possibly server) your program |
152 | is listening on. |
153 | See remote.pl for an example. |
154 | |
0833402a |
155 | =item flags (default: 0) |
1d209997 |
156 | |
0833402a |
157 | Possible values: |
1d209997 |
158 | |
0833402a |
159 | =over 12 |
9915cd6d |
160 | |
0833402a |
161 | =item FCGI::FAIL_ACCEPT_ON_INTR |
5baeeca7 |
162 | |
0833402a |
163 | If set, Accept will fail if interrupted. |
164 | It not set, it will just keep on waiting. |
5baeeca7 |
165 | |
0833402a |
166 | =back |
5baeeca7 |
167 | |
0833402a |
168 | =back |
5baeeca7 |
169 | |
0833402a |
170 | Example usage: |
171 | my $req = FCGI::Request; |
5baeeca7 |
172 | |
0833402a |
173 | or: |
174 | my %env; |
175 | my $in = new IO::Handle; |
176 | my $out = new IO::Handle; |
177 | my $err = new IO::Handle; |
178 | my $req = FCGI::Request($in, $out, $err, \%env); |
5baeeca7 |
179 | |
0833402a |
180 | =item FCGI::OpenSocket(path, backlog) |
5baeeca7 |
181 | |
0833402a |
182 | Creates a socket suitable to use as an argument to Request. |
5baeeca7 |
183 | |
0833402a |
184 | =over 8 |
eede4b76 |
185 | |
0833402a |
186 | =item path |
eede4b76 |
187 | |
0833402a |
188 | Pathname of socket or colon followed by local tcp port. |
420df423 |
189 | Note that some systems take file permissions into account |
190 | on Unix domain sockets, so you'll have to make sure that |
191 | the server can write to the created file, by changing |
192 | the umask before the call and/or changing permissions and/or |
193 | group of the file afterwards. |
eede4b76 |
194 | |
0833402a |
195 | =item backlog |
eede4b76 |
196 | |
0833402a |
197 | Maximum length of the queue of pending connections. |
198 | If a connection |
199 | request arrives with the queue full the client may receive |
200 | an error with an indication of ECONNREFUSED. |
eede4b76 |
201 | |
0833402a |
202 | =back |
eede4b76 |
203 | |
0833402a |
204 | =item FCGI::CloseSocket(socket) |
eede4b76 |
205 | |
0833402a |
206 | Close a socket opened with OpenSocket. |
eede4b76 |
207 | |
0833402a |
208 | =item $req->Accept() |
90a18d65 |
209 | |
0833402a |
210 | Accepts a connection on $req, attaching the filehandles and |
211 | populating the environment hash. |
212 | Returns 0 on success. |
213 | If a connection has been accepted before, the old |
214 | one will be finished first. |
1b64d24d |
215 | |
0833402a |
216 | Note that unlike with the old interface, no die and warn |
217 | handlers are installed by default. This means that if |
218 | you are not running an sfio enabled perl, any warn or |
219 | die message will not end up in the server's log by default. |
220 | It is advised you set up die and warn handlers yourself. |
221 | FCGI.pm contains an example of die and warn handlers. |
1b64d24d |
222 | |
0833402a |
223 | =item $req->Finish() |
1b64d24d |
224 | |
0833402a |
225 | Finishes accepted connection. |
226 | Also detaches filehandles. |
227 | |
228 | =item $req->Flush() |
229 | |
230 | Flushes accepted connection. |
231 | |
232 | =item $req->Detach() |
233 | |
234 | Temporarily detaches filehandles on an accepted connection. |
1b64d24d |
235 | |
0833402a |
236 | =item $req->Attach() |
237 | |
238 | Re-attaches filehandles on an accepted connection. |
239 | |
7fa2de73 |
240 | =item $req->LastCall() |
241 | |
242 | Tells the library not to accept any more requests on this handle. |
243 | It should be safe to call this method from signal handlers. |
244 | |
245 | Note that this method is still experimental and everything |
246 | about it, including its name, is subject to change. |
247 | |
0833402a |
248 | =item $env = $req->GetEnvironment() |
249 | |
250 | Returns the environment parameter passed to FCGI::Request. |
251 | |
252 | =item ($in, $out, $err) = $req->GetHandles() |
253 | |
254 | Returns the file handle parameters passed to FCGI::Request. |
255 | |
256 | =item $isfcgi = $req->IsFastCGI() |
257 | |
258 | Returns whether or not the program was run as a FastCGI. |
259 | |
260 | =back |
261 | |
929a7b0c |
262 | =HEAD1 LIMITATIONS |
263 | |
264 | FCGI.pm isn't Unicode aware, only characters within the range 0x00-0xFF are |
265 | supported. Attempts to output strings containing characters above 0xFF results |
266 | in a exception: (F) C<Wide character in %s>. |
267 | |
268 | Users who wants the previous (FCGI.pm <= 0.68) incorrect behavior can disable the |
269 | exception by using the C<bytes> pragma. |
270 | |
271 | { |
272 | use bytes; |
273 | print "\x{263A}"; |
274 | } |
275 | |
276 | |
0833402a |
277 | =head1 AUTHOR |
278 | |
279 | Sven Verdoolaege <skimo@kotnet.org> |
280 | |
281 | =cut |
282 | |
283 | __END__ |