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