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