1 FastCGI Developer's Kit README
2 ------------------------------
4 Version 2.0b2, 04 April 1997
5 $Id: README,v 1.2 1999/06/07 05:03:47 roberts Exp $
6 Copyright (c) 1996 Open Market, Inc.
7 See the file "LICENSE.TERMS" for information on usage and redistribution
8 of this file, and for a DISCLAIMER OF ALL WARRANTIES.
13 Open the kit's index page, index.html in this directory, using the
14 "Open File" command in your Web browser. The index page gives you an
15 overview of the kit structure and helps you navigate the kit. The
16 index page also contains links that run some example applications, but
17 the applications won't work when index.html is opened using the "Open
18 File" command because they aren't being accessed through a Web server.
20 For further instructions see the FastCGI Developer's Kit
21 document, accessible via the index page.
26 The following is a small list of what should be available in the final
28 1. Fix all compilation problems on all Unixes and NT.
29 2. Provide perl.c for perl5.003 (replace run() with runops())
30 3. Provide latest Tcl patches (NT requires Tcl7.5+)
31 4. Provide FCGI_VERSION directive for automatic version recognition.
33 5. Provide new Java interface to conform to JDK1.1.1 (due to final
35 6. Provide samples of Perl on NT.
38 Changes with devkit 2.1.1
39 -------------------------
41 *) Flush FastCGI buffers at application exit. <eichin@fastengines.com>
43 << INSERT OTHER STUFF HERE >>
46 What's New: Version 2.0b2, 04 April 1997
47 --------------------------------------
49 Some additional bug fixes, mostly on NT port. The following list
50 of the bugs that have been and fixed:
51 1. Updated build_no_shell.bat to create a FcgiBin directory under the
52 top level of the FastCGI kit and copy all executables and the
53 FastCGI dll there. This makes it easier to use.
54 2. Corrected the Unix version of OS_SpawnChild so that it didn't close
55 the listenFd when forking off child processes. This code would
56 affect the cgi-fcgi application on Unix. The problem is that it
57 could only start one fastcgi process. Any other processes would not
58 get the listen file descriptor and they would die.
59 3. Corrected cgi-fcgi.c so that it properly handled large posts. The
60 bug was introduced with the asynchronous I/O model implemented for
61 the Windows NT port. The problem was not clearing a bit indicating
62 that a read had completed. This caused the application to stall.
63 4. Corrected OS_DoIo, the function used for scheduling I/O for cgi-fcgi.
64 It had a bug where it wasn't creating a copy of the file descriptors
65 used for I/O. This would cause the master list of FDs to watch to be
66 reset and thus would hang the application because we would no longer
67 watch for I/O on those file descriptors. (This problem was specific to
68 Unix and only happened with the cgi-fcgi application.)
69 5. Cleaned up several compilation warnings present on OSF.
72 What's New: Version 2.0b1, 24 March 1997
73 --------------------------------------
75 This "beta" release adds the functionality of "cgi-fcgi" to the
76 Windows NT platform and allows for creation of FastCGI applications
77 running in Win32 environment. There is almost no new documentation
78 provided, but will become part of this kit in the official release.
79 1. Added FastCGI libraries running on Windows NT 3.51+
80 2. Rename errno to FCGI_errno in the FCGX_Stream, which was causing
81 problems on some Linux platforms and NT.
82 3. Fixed a parenthesis problem in FCGI_gets
85 What's New: Version 1.5.1, 12 December 1996
86 --------------------------------------
88 This release introduces mostly bug fixes, without any additional
89 functionality to the kit.
90 1. Conditional compilation for the hp-ux compiler.
91 2. Loop around the accept() call to eliminate "OS Error: Interrupted
92 System Call" message from appearing in the error logs.
93 3. Casting of the FCGI_Header to (char *), which eliminates the
94 assertion failure "bufPtr->size>0".
97 What's New: Version 1.5, 12 June 1996
98 --------------------------------------
102 Added a white paper on FastCGI application performance to the
103 doc directory. Generally brought the other docs up to date.
105 Rearranged the kit to put more emphasis on running FastCGI-capable
106 servers and less on running cgi-fcgi. Added
107 examples/conf/om-httpd.config, a config file that demonstrates all
108 of the example apps. (Would like to have similar configs for NCSA
111 Added the tiny-authorizer and sample-store applications to
112 the examples. These are explained in the index.html.
114 In addition to everything else it does, sample-store demonstrates
115 a bug in the Open Market WebServer 2.0: When an Authorizer
116 application denies access, the server tacks some extra junk onto
117 the end of the page the application returns. A little ugly but
122 Added the functions FCGX_Finish and FCGI_Finish. These functions
123 finish the current request from the HTTP server but do not begin a
124 new request. These functions make it possible for applications to
125 perform other processing between requests. An application must not
126 use its stdin, stdout, stderr, or environ between calling
127 FCGI_Finish and calling FCGI_Accept. See doc/FCGI_Finish.3 for
128 more information. The application examples/sample-store.c demonstrates
129 the use of FCGI_Finish.
131 Added conditional 'extern "C"' stuff to the .h files fcgi_stdio.h,
132 fcgiapp.h, and fcgiappmisc.h for the benefit of C++ applications
133 (suggested by Jim McCarthy).
135 Fixed two bugs in FCGX_VFPrintF (reported by Ben Laurie). These
136 bugs affected processing of %f format specifiers and of all format
137 specifiers containing a precision spec (e.g "%12.4g").
139 Fixed a bug in FCGX_Accept in which the environment variable
140 FCGI_WEBSERVER_ADDRS was being read rather than the specified
141 FCGI_WEB_SERVER_ADDRS. Fixed a bug in FCGX_Accept in which the
142 wrong storage was freed when FCGI_WEB_SERVER_ADDRS contained more
143 than one address or if the address check failed.
145 Changed FCGX_Accept to avoid depending upon accept(2) returning the
146 correct value of sin_family in the socketaddr structure for an
147 AF_UNIX connection (SCO returns the wrong value, as reported by Paul
150 Changed the error retry logic in FCGX_Accept. FCGX_Accept now
151 returns -1 only in case of operating system errors that occur while
152 accepting a connection (e.g. out of file descriptors). Other errors
153 cause the current connection to be dropped and a new connection to
158 Changed FCGI.xs to make it insensitive to Perl's treatment of
159 environ (we hope). Changed FCGI::accept so the initial environment
160 variables are not unset on the first call to FCGI::accept (or on
161 subsequent calls either). Added the echo-perl example
162 program. Added a workaround for the "empty initial environment bug"
163 to tiny-perl-fcgi. Changed the example Perl scripts to use a new
164 symbolic link ./perl, avoiding the HP-UX 32 character limit on the
165 first line of a command interpreter file.
167 Because the FastCGI-enabled Perl interpreter uses the C fcgi_stdio
168 library, it picks up all the changes listed above for C. There's
169 a new Perl subroutine FCGI::finish.
173 Fixed a bug in tclFCGI.c that caused the request environment
174 variables to be lost. Changed FCGI_Accept so the initial
175 environment variables are not unset on the first call to FCGI_Accept
176 (or on subsequent calls either). Added the echo-tcl example
177 program. Fixed another bug that caused Tcl to become confused by
178 file opens; as a side effect of this change, writes to stdout/stderr
179 that occur in an app running as FastCGI before FCGI_Accept is called
180 are no-ops rather than crashing Tcl. Changed the example Tcl
181 scripts to use a new symbolic link ./tclsh, avoiding the HP-UX 32
182 character limit on the first line of a command interpreter file.
184 Because the FastCGI-enabled Tcl interpreter uses the C fcgi_stdio
185 library, it picks up all the changes listed above for C; there's
186 a new Tcl command FCGI_Finish.
190 Fixed a sign-extension bug in FCGIMessage.java that caused bad encodings
191 of names and values in name-value pairs for lengths in [128..255].
192 Made small cleanups in the Java example programs to make them more
193 consistent with the other examples.
197 What's New: Version 1.4, 10 May 1996
198 --------------------------------------
200 Includes Java classes and Java examples.
204 What's New: Version 1.3.1, 6 May 1996
205 --------------------------------------
207 New, simplified, license terms. Includes an expanded whitepaper that
208 describes FastCGI support in Open Market's Secure WebServer 2.0.
209 Includes Open Market FastCGI 1.0 Programmer's Guide. Includes
210 "FastCGI: A High-Performance Gateway Interface", a position paper
211 presented at the workshop "Programming the Web - a search for APIs",
212 Fifth International World Wide Web Conference, 6 May 1996, Paris,
217 What's New: Version 1.3, 29 April 1996
218 --------------------------------------
220 First public release; new license terms on all files.
222 Changed cgi-fcgi.c to use SO_REUSEADDR when creating the listening socket;
223 this avoids the need to wait through the TIME_WAIT state on all the TCP
224 connections made by the previous instance of an external application
229 What's New: Version 1.2.2, 15 April 1996
230 ----------------------------------------
232 Partially fixed a bug in Perl's FCGI::accept (source file FCGI.xs).
233 The per-request environment variables were being lost. Now the
234 per-request environment variables show up correctly, except that if
235 the Perl application has an empty initial environment, the environment
236 variables associated with the *first* request are lost. Therefore,
237 when starting Perl, always set some environment variable using the
238 AppClass -initial-env option, or by running cgi-fcgi in a non-empty
243 What's New: Version 1.2.1, 22 March 1996
244 ----------------------------------------
246 Fixed a bug in FCGI_Accept. If your application running as FastCGI
247 opened a file before calling FCGI_Accept, it would decide that it
248 was really running as CGI. Things went downhill quickly after that!
250 Also added advisory locking to serialize calls to accept on shared
251 listening sockets on Solaris and IRIX, to work around problems
252 with concurrent accept calls on these platforms.
256 What's New: Version 1.2, 20 March 1996
257 --------------------------------------
259 1. This version of the kit implements the most recent draft
260 of the protocol spec. Enhancements to the protocol include
261 a BEGIN_REQUEST record that simplifies request ID management
262 and transmits role and keep-alive information, and a simplified
263 end-of-stream indication.
265 The protocol spec has been revised to describe exactly what's
266 been implemented, leaving out the features that we hope to
267 introduce in later releases.
269 At the application level, the visible change is the FCGI_ROLE
270 variable that's available to applications. This allows an application
271 to check that it has been invoked in the expected role. A single
272 application can be written to respond in several roles. The
273 FCGI_Accept.3 manpage contains more information.
275 2. We introduced the new "module" prefix FCGX in order to simplify
276 the relationship between fcgi_stdio and fcgiapp.
278 A growing number of functions are provided in both fcgi_stdio and
279 fcgiapp versions. Rather than inventing an ad hoc solution for each
280 naming conflict (as we did with FCGI_accept and FCGI_Accept), we've
281 bitten the bullet and systematically renamed *all* the fcgapp
282 primitives with the prefix FCGX_. In fcgi_stdio, we've renamed
283 FCGI_accept to FCGI_Accept. So all functions that are common in the
284 two libraries have the same name modulo the different prefixes.
286 The Accept function visible in Tcl is now called FCGI_Accept, not
289 The Accept function visible in Perl is now FCGI::accept. All
290 lower case names for functions and all upper case names for
291 modules appears to be a Perl convention, so we conform.
293 3. The kit now fully supports the Responder, Authorizer,
296 The Filter role required a new function, FCGI_StartFilterData.
297 FCGI_StartFilterData changes the input stream from reading
298 FCGI_STDIN data to reading FCGI_DATA data. The manpage
301 Another new function, FCGI_SetExitStatus, is primarily for
302 the Responder role but is available to all. FCGI_SetExitStatus
303 allows an application to set a nonzero "exit" status
304 before completing a request and calling FCGI_Accept again.
305 The manpage gives full details.
307 These two new functions are provided at both the fcgi_stdio interface
308 and the basic fcgiapp interface. Naturally, the fcgiapp versions are
309 called FCGX_StartFilterData and FCGX_SetExitStatus.
311 4. The fcgiapp interface changed slightly in order to treat
312 the streams and environment data more symmetrically.
314 FCGX_Accept now returns an environment pointer, rather than requiring
315 a call to FCGX_GetAllParams to retrieve an environment pointer.
316 FCGX_GetParam takes an explicit environment pointer argument.
317 FCGX_GetAllParams is eliminated. See the documentation in the header
318 file for complete information.
320 fcgiapp also added the procedure FCGX_IsCGI, providing a standardized
321 test of whether the app was started as CGI or FastCGI.
323 5. We've ported the kits to vendor-supported ANSI C compilers
324 on Sun (Solaris 2.X), HP, and Digital platforms. GCC can be
325 selected on these platforms by performing SETENV CC gcc before
330 What's New: Version 1.1, 30 Jan 1996
331 ------------------------------------
333 1. More platforms: Digital UNIX, IBM AIX, Silicon Graphics IRIX,
336 2. Perl and Tcl: Simple recipes for producing Perl and Tcl
337 interpreters that run as FastCGI applications. No source
338 code changes are needed to Perl and Tcl. Documented
339 in separate documents, accessible via the index page.
343 Version 1.0, 10 Jan 1996
344 ------------------------