Commit | Line | Data |
0198fd3c |
1 | FastCGI Developer's Kit README |
2 | ------------------------------ |
3 | |
af20503c |
4 | $Id: README,v 1.24 2004/01/31 17:47:06 robs Exp $ |
0198fd3c |
5 | Copyright (c) 1996 Open Market, Inc. |
af1b4cad |
6 | See the file "LICENSE" for information on usage and redistribution |
0198fd3c |
7 | of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
8 | |
9 | Basic Directions |
10 | ---------------- |
11 | |
1856131a |
12 | Unix: |
0198fd3c |
13 | |
1856131a |
14 | ./configure |
15 | make |
16 | make install |
0198fd3c |
17 | |
1856131a |
18 | Win32: |
0198fd3c |
19 | |
1856131a |
20 | nmake -f Makefile.nt |
fbf75401 |
21 | |
1856131a |
22 | (or use the MSVC++ project files in the Win32 directory) |
ac8a58ac |
23 | |
1856131a |
24 | |
25 | CHANGES |
26 | ------- |
27 | |
8b4c497b |
28 | For more detail regarding changes, please consult the cvs log available |
29 | on http://fastcgi.com/. |
30 | |
2a7273a1 |
31 | 2.4.1 |
af20503c |
32 | ----- |
33 | |
34 | *) [WIN32] Raise SIGTERM from the ShutdownRequestThread to emulate |
35 | the Unix behaviour. Dan [mail@daniel-albert.de] |
2a7273a1 |
36 | |
ac8d264a |
37 | *) Fix fcgi_streambuf::underflow() such that when there is no buffer |
38 | the character isn't removed. AIDA Shinra <shinra@j10n.org> |
39 | |
2a7273a1 |
40 | *) Add attach() and detach() support. |
41 | |
1856131a |
42 | |
fba762d7 |
43 | 2.4.0 |
48f63bdf |
44 | ----- |
746775a4 |
45 | |
1447563e |
46 | *) When closing connections, shutdown() the send side of TCP sockets to |
47 | prevent a TCP RST from trashing the reciept of data on the client (when |
48 | the client continues to send data to the application). |
28900a86 |
49 | |
746775a4 |
50 | *) [WIN32] force an exit from the ShutdownRequestThread when a shutdown is |
51 | signaled and NamedPipes are in use. |
52 | |
134d8dfc |
53 | *) Use streamsize and char_type in the C++ API. |
48f63bdf |
54 | |
553207ad |
55 | *) [WIN32] Eliminate the (partial and broken) use of OverlappedIO - this |
56 | was causing a loose spin in acceptNamedPipe(). |
57 | |
a34d549f |
58 | *) Fix a bug that caused an assert to pop when an async file descriptor was |
59 | numbered greater than 16. Kevin Eye [eye@buffalo.edu] |
60 | |
8b4c497b |
61 | *) Update the echo-cpp example to show the restoral of the original |
62 | streambufs. Trub, Vladimir [vtrub@purolator.com] |
63 | |
33977e3b |
64 | *) Fix a bug a that caused the lib to crash under certain circumstances |
65 | when an error occured on a read |
66 | |
fae4909b |
67 | *) Test for iostreams that support a streambuf assigment operator |
68 | |
48f63bdf |
69 | *) (WIN32) Fixed initialization of the accept mutex when OpenSocket() was used. |
70 | Niklas Bergh [niklas.bergh@tific.com] |
71 | |
1856131a |
72 | |
73 | 2.2.2 |
74 | ----- |
75 | |
76 | *) Added support for shared libraries. |
77 | |
78 | *) Added support for a graceful shutdown via an event under Win32. |
79 | |
80 | *) Added default signal handlers for PIPE, USR1, and TERM. |
81 | |
82 | *) Fix some minor bugs in the 0S_ layer. |
83 | |
84 | *) Fixed the C++ streambuf implementation. |
85 | |
86 | |
87 | Changes with devkit 2.1.1 |
ac8a58ac |
88 | ------------------------- |
f6d1be39 |
89 | |
6518a3ef |
90 | *) Fixed an unintentional sign extension during promotion in Java's |
91 | FCGIInputStream.read(). Takayuki Tachikawa <tachi@po.ntts.co.jp> |
92 | |
3293ebdf |
93 | *) Cleaned up warnings in examples (mostly main() complaints). |
94 | |
da7d42b2 |
95 | *) Removed examples/tiny-cgi.c (it wasn't a FastCGI application?!). |
96 | |
283822e9 |
97 | *) Remove some debugging code and clean up some gcc warnings in cgi-fcgi.c. |
98 | |
5a7cc494 |
99 | *) Add multithread support to the fcgiapp lib and an example multithreaded |
6518a3ef |
100 | application, threaded.c. Based on work by Dennis Payne |
5a7cc494 |
101 | <dpayne@softscape.com> and Gene Sokolov <hook@aktrad.ru>. |
102 | |
fbf75401 |
103 | *) Remove the printf() and #include of stdio.h from examples/echo2.c. |
104 | |
f6d1be39 |
105 | *) Remove the static initialization of _fcgi_sF[] because on glibc 2.x based |
fbf75401 |
106 | systems stdin/stdout/stderr are no longer static. |
107 | |
ac8a58ac |
108 | *) Flush FastCGI buffers at application exit. <eichin@fastengines.com> |
fbf75401 |
109 | |
ac8a58ac |
110 | << INSERT OTHER STUFF HERE >> |
fbf75401 |
111 | |
0198fd3c |
112 | |
113 | What's New: Version 2.0b2, 04 April 1997 |
114 | -------------------------------------- |
115 | |
116 | Some additional bug fixes, mostly on NT port. The following list |
117 | of the bugs that have been and fixed: |
118 | 1. Updated build_no_shell.bat to create a FcgiBin directory under the |
119 | top level of the FastCGI kit and copy all executables and the |
120 | FastCGI dll there. This makes it easier to use. |
fbf75401 |
121 | 2. Corrected the Unix version of OS_SpawnChild so that it didn't close |
0198fd3c |
122 | the listenFd when forking off child processes. This code would |
123 | affect the cgi-fcgi application on Unix. The problem is that it |
124 | could only start one fastcgi process. Any other processes would not |
125 | get the listen file descriptor and they would die. |
126 | 3. Corrected cgi-fcgi.c so that it properly handled large posts. The |
127 | bug was introduced with the asynchronous I/O model implemented for |
128 | the Windows NT port. The problem was not clearing a bit indicating |
129 | that a read had completed. This caused the application to stall. |
130 | 4. Corrected OS_DoIo, the function used for scheduling I/O for cgi-fcgi. |
fbf75401 |
131 | It had a bug where it wasn't creating a copy of the file descriptors |
132 | used for I/O. This would cause the master list of FDs to watch to be |
0198fd3c |
133 | reset and thus would hang the application because we would no longer |
134 | watch for I/O on those file descriptors. (This problem was specific to |
135 | Unix and only happened with the cgi-fcgi application.) |
136 | 5. Cleaned up several compilation warnings present on OSF. |
fbf75401 |
137 | |
0198fd3c |
138 | |
139 | What's New: Version 2.0b1, 24 March 1997 |
140 | -------------------------------------- |
141 | |
142 | This "beta" release adds the functionality of "cgi-fcgi" to the |
143 | Windows NT platform and allows for creation of FastCGI applications |
fbf75401 |
144 | running in Win32 environment. There is almost no new documentation |
0198fd3c |
145 | provided, but will become part of this kit in the official release. |
146 | 1. Added FastCGI libraries running on Windows NT 3.51+ |
147 | 2. Rename errno to FCGI_errno in the FCGX_Stream, which was causing |
148 | problems on some Linux platforms and NT. |
149 | 3. Fixed a parenthesis problem in FCGI_gets |
150 | |
151 | |
152 | What's New: Version 1.5.1, 12 December 1996 |
153 | -------------------------------------- |
154 | |
155 | This release introduces mostly bug fixes, without any additional |
fbf75401 |
156 | functionality to the kit. |
0198fd3c |
157 | 1. Conditional compilation for the hp-ux compiler. |
158 | 2. Loop around the accept() call to eliminate "OS Error: Interrupted |
159 | System Call" message from appearing in the error logs. |
fbf75401 |
160 | 3. Casting of the FCGI_Header to (char *), which eliminates the |
0198fd3c |
161 | assertion failure "bufPtr->size>0". |
fbf75401 |
162 | |
0198fd3c |
163 | |
164 | What's New: Version 1.5, 12 June 1996 |
165 | -------------------------------------- |
166 | |
167 | General: |
168 | |
169 | Added a white paper on FastCGI application performance to the |
170 | doc directory. Generally brought the other docs up to date. |
171 | |
172 | Rearranged the kit to put more emphasis on running FastCGI-capable |
173 | servers and less on running cgi-fcgi. Added |
174 | examples/conf/om-httpd.config, a config file that demonstrates all |
175 | of the example apps. (Would like to have similar configs for NCSA |
176 | and Apache.) |
177 | |
178 | Added the tiny-authorizer and sample-store applications to |
179 | the examples. These are explained in the index.html. |
180 | |
181 | In addition to everything else it does, sample-store demonstrates |
182 | a bug in the Open Market WebServer 2.0: When an Authorizer |
183 | application denies access, the server tacks some extra junk onto |
184 | the end of the page the application returns. A little ugly but |
185 | not fatal. |
186 | |
187 | C libraries: |
188 | |
189 | Added the functions FCGX_Finish and FCGI_Finish. These functions |
190 | finish the current request from the HTTP server but do not begin a |
191 | new request. These functions make it possible for applications to |
192 | perform other processing between requests. An application must not |
193 | use its stdin, stdout, stderr, or environ between calling |
194 | FCGI_Finish and calling FCGI_Accept. See doc/FCGI_Finish.3 for |
195 | more information. The application examples/sample-store.c demonstrates |
196 | the use of FCGI_Finish. |
197 | |
198 | Added conditional 'extern "C"' stuff to the .h files fcgi_stdio.h, |
199 | fcgiapp.h, and fcgiappmisc.h for the benefit of C++ applications |
200 | (suggested by Jim McCarthy). |
201 | |
202 | Fixed two bugs in FCGX_VFPrintF (reported by Ben Laurie). These |
203 | bugs affected processing of %f format specifiers and of all format |
204 | specifiers containing a precision spec (e.g "%12.4g"). |
205 | |
206 | Fixed a bug in FCGX_Accept in which the environment variable |
207 | FCGI_WEBSERVER_ADDRS was being read rather than the specified |
208 | FCGI_WEB_SERVER_ADDRS. Fixed a bug in FCGX_Accept in which the |
209 | wrong storage was freed when FCGI_WEB_SERVER_ADDRS contained more |
210 | than one address or if the address check failed. |
211 | |
212 | Changed FCGX_Accept to avoid depending upon accept(2) returning the |
213 | correct value of sin_family in the socketaddr structure for an |
214 | AF_UNIX connection (SCO returns the wrong value, as reported by Paul |
215 | Mahoney). |
216 | |
217 | Changed the error retry logic in FCGX_Accept. FCGX_Accept now |
218 | returns -1 only in case of operating system errors that occur while |
219 | accepting a connection (e.g. out of file descriptors). Other errors |
220 | cause the current connection to be dropped and a new connection to |
221 | be attempted. |
222 | |
223 | Perl: |
224 | |
225 | Changed FCGI.xs to make it insensitive to Perl's treatment of |
226 | environ (we hope). Changed FCGI::accept so the initial environment |
227 | variables are not unset on the first call to FCGI::accept (or on |
228 | subsequent calls either). Added the echo-perl example |
229 | program. Added a workaround for the "empty initial environment bug" |
230 | to tiny-perl-fcgi. Changed the example Perl scripts to use a new |
231 | symbolic link ./perl, avoiding the HP-UX 32 character limit on the |
232 | first line of a command interpreter file. |
233 | |
234 | Because the FastCGI-enabled Perl interpreter uses the C fcgi_stdio |
235 | library, it picks up all the changes listed above for C. There's |
236 | a new Perl subroutine FCGI::finish. |
237 | |
238 | Tcl: |
239 | |
240 | Fixed a bug in tclFCGI.c that caused the request environment |
241 | variables to be lost. Changed FCGI_Accept so the initial |
242 | environment variables are not unset on the first call to FCGI_Accept |
243 | (or on subsequent calls either). Added the echo-tcl example |
244 | program. Fixed another bug that caused Tcl to become confused by |
245 | file opens; as a side effect of this change, writes to stdout/stderr |
246 | that occur in an app running as FastCGI before FCGI_Accept is called |
247 | are no-ops rather than crashing Tcl. Changed the example Tcl |
248 | scripts to use a new symbolic link ./tclsh, avoiding the HP-UX 32 |
249 | character limit on the first line of a command interpreter file. |
250 | |
251 | Because the FastCGI-enabled Tcl interpreter uses the C fcgi_stdio |
252 | library, it picks up all the changes listed above for C; there's |
253 | a new Tcl command FCGI_Finish. |
254 | |
255 | Java: |
256 | |
257 | Fixed a sign-extension bug in FCGIMessage.java that caused bad encodings |
258 | of names and values in name-value pairs for lengths in [128..255]. |
259 | Made small cleanups in the Java example programs to make them more |
260 | consistent with the other examples. |
261 | |
262 | |
263 | |
264 | What's New: Version 1.4, 10 May 1996 |
265 | -------------------------------------- |
266 | |
267 | Includes Java classes and Java examples. |
268 | |
269 | |
270 | |
271 | What's New: Version 1.3.1, 6 May 1996 |
272 | -------------------------------------- |
273 | |
274 | New, simplified, license terms. Includes an expanded whitepaper that |
275 | describes FastCGI support in Open Market's Secure WebServer 2.0. |
276 | Includes Open Market FastCGI 1.0 Programmer's Guide. Includes |
277 | "FastCGI: A High-Performance Gateway Interface", a position paper |
278 | presented at the workshop "Programming the Web - a search for APIs", |
279 | Fifth International World Wide Web Conference, 6 May 1996, Paris, |
280 | France. |
281 | |
282 | |
283 | |
284 | What's New: Version 1.3, 29 April 1996 |
285 | -------------------------------------- |
286 | |
287 | First public release; new license terms on all files. |
288 | |
289 | Changed cgi-fcgi.c to use SO_REUSEADDR when creating the listening socket; |
290 | this avoids the need to wait through the TIME_WAIT state on all the TCP |
291 | connections made by the previous instance of an external application |
fbf75401 |
292 | you are restarting. |
0198fd3c |
293 | |
294 | |
295 | |
296 | What's New: Version 1.2.2, 15 April 1996 |
297 | ---------------------------------------- |
298 | |
299 | Partially fixed a bug in Perl's FCGI::accept (source file FCGI.xs). |
300 | The per-request environment variables were being lost. Now the |
301 | per-request environment variables show up correctly, except that if |
302 | the Perl application has an empty initial environment, the environment |
303 | variables associated with the *first* request are lost. Therefore, |
304 | when starting Perl, always set some environment variable using the |
305 | AppClass -initial-env option, or by running cgi-fcgi in a non-empty |
306 | environment. |
307 | |
308 | |
309 | |
310 | What's New: Version 1.2.1, 22 March 1996 |
311 | ---------------------------------------- |
312 | |
313 | Fixed a bug in FCGI_Accept. If your application running as FastCGI |
314 | opened a file before calling FCGI_Accept, it would decide that it |
315 | was really running as CGI. Things went downhill quickly after that! |
316 | |
317 | Also added advisory locking to serialize calls to accept on shared |
318 | listening sockets on Solaris and IRIX, to work around problems |
319 | with concurrent accept calls on these platforms. |
320 | |
321 | |
322 | |
323 | What's New: Version 1.2, 20 March 1996 |
324 | -------------------------------------- |
325 | |
326 | 1. This version of the kit implements the most recent draft |
327 | of the protocol spec. Enhancements to the protocol include |
328 | a BEGIN_REQUEST record that simplifies request ID management |
329 | and transmits role and keep-alive information, and a simplified |
330 | end-of-stream indication. |
331 | |
332 | The protocol spec has been revised to describe exactly what's |
333 | been implemented, leaving out the features that we hope to |
334 | introduce in later releases. |
335 | |
336 | At the application level, the visible change is the FCGI_ROLE |
337 | variable that's available to applications. This allows an application |
338 | to check that it has been invoked in the expected role. A single |
339 | application can be written to respond in several roles. The |
340 | FCGI_Accept.3 manpage contains more information. |
341 | |
342 | 2. We introduced the new "module" prefix FCGX in order to simplify |
343 | the relationship between fcgi_stdio and fcgiapp. |
344 | |
345 | A growing number of functions are provided in both fcgi_stdio and |
346 | fcgiapp versions. Rather than inventing an ad hoc solution for each |
347 | naming conflict (as we did with FCGI_accept and FCGI_Accept), we've |
348 | bitten the bullet and systematically renamed *all* the fcgapp |
349 | primitives with the prefix FCGX_. In fcgi_stdio, we've renamed |
350 | FCGI_accept to FCGI_Accept. So all functions that are common in the |
351 | two libraries have the same name modulo the different prefixes. |
352 | |
353 | The Accept function visible in Tcl is now called FCGI_Accept, not |
354 | FCGI_accept. |
355 | |
356 | The Accept function visible in Perl is now FCGI::accept. All |
357 | lower case names for functions and all upper case names for |
358 | modules appears to be a Perl convention, so we conform. |
359 | |
360 | 3. The kit now fully supports the Responder, Authorizer, |
361 | and Filter roles. |
362 | |
363 | The Filter role required a new function, FCGI_StartFilterData. |
364 | FCGI_StartFilterData changes the input stream from reading |
365 | FCGI_STDIN data to reading FCGI_DATA data. The manpage |
366 | gives full details. |
367 | |
368 | Another new function, FCGI_SetExitStatus, is primarily for |
369 | the Responder role but is available to all. FCGI_SetExitStatus |
370 | allows an application to set a nonzero "exit" status |
371 | before completing a request and calling FCGI_Accept again. |
372 | The manpage gives full details. |
373 | |
374 | These two new functions are provided at both the fcgi_stdio interface |
375 | and the basic fcgiapp interface. Naturally, the fcgiapp versions are |
376 | called FCGX_StartFilterData and FCGX_SetExitStatus. |
377 | |
378 | 4. The fcgiapp interface changed slightly in order to treat |
379 | the streams and environment data more symmetrically. |
380 | |
381 | FCGX_Accept now returns an environment pointer, rather than requiring |
382 | a call to FCGX_GetAllParams to retrieve an environment pointer. |
383 | FCGX_GetParam takes an explicit environment pointer argument. |
384 | FCGX_GetAllParams is eliminated. See the documentation in the header |
385 | file for complete information. |
386 | |
387 | fcgiapp also added the procedure FCGX_IsCGI, providing a standardized |
388 | test of whether the app was started as CGI or FastCGI. |
389 | |
390 | 5. We've ported the kits to vendor-supported ANSI C compilers |
391 | on Sun (Solaris 2.X), HP, and Digital platforms. GCC can be |
392 | selected on these platforms by performing SETENV CC gcc before |
393 | running configure. |
394 | |
395 | |
396 | |
397 | What's New: Version 1.1, 30 Jan 1996 |
398 | ------------------------------------ |
399 | |
400 | 1. More platforms: Digital UNIX, IBM AIX, Silicon Graphics IRIX, |
401 | Sun SunOS 4.1.4. |
402 | |
403 | 2. Perl and Tcl: Simple recipes for producing Perl and Tcl |
404 | interpreters that run as FastCGI applications. No source |
405 | code changes are needed to Perl and Tcl. Documented |
406 | in separate documents, accessible via the index page. |
407 | |
408 | |
409 | |
410 | Version 1.0, 10 Jan 1996 |
411 | ------------------------ |