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