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