README

   1 FastCGI Developer's Kit README
   2 ------------------------------
   3
   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.
   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
  32 2.2.3
  33 -----
  34
  35  *) [WIN32] Eliminate the (partial and broken) use of OverlappedIO - this
  36     was causing a loose spin in acceptNamedPipe().
  37
  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]
  40
  41  *) Update the echo-cpp example to show the restoral of the original
  42     streambufs.  Trub, Vladimir [vtrub@purolator.com]
  43
  44  *) Fix a bug a that caused the lib to crash under certain circumstances
  45     when an error occured on a read
  46
  47  *) Test for iostreams that support a streambuf assigment operator
  48
  49  *) (WIN32) Fixed initialization of the accept mutex when OpenSocket() was used.
  50     Niklas Bergh [niklas.bergh@tific.com]
  51
  52
  53 2.2.2
  54 -----
  55
  56  *) Added support for shared libraries.
  57
  58  *) Added support for a graceful shutdown via an event under Win32.
  59
  60  *) Added default signal handlers for PIPE, USR1, and TERM.
  61
  62  *) Fix some minor bugs in the 0S_ layer.
  63
  64  *) Fixed the C++ streambuf implementation.
  65
  66
  67 Changes with devkit 2.1.1
  68 -------------------------
  69
  70  *) Fixed an unintentional sign extension during promotion  in Java's
  71     FCGIInputStream.read(). Takayuki Tachikawa <tachi@po.ntts.co.jp>
  72
  73  *) Cleaned up warnings in examples (mostly main() complaints).
  74
  75  *) Removed examples/tiny-cgi.c (it wasn't a FastCGI application?!).
  76
  77  *) Remove some debugging code and clean up some gcc warnings in cgi-fcgi.c.
  78
  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>.
  82
  83  *) Remove the printf() and #include of stdio.h from examples/echo2.c.
  84
  85  *) Remove the static initialization of _fcgi_sF[] because on glibc 2.x based
  86     systems stdin/stdout/stderr are no longer static.
  87
  88  *) Flush FastCGI buffers at application exit.  <eichin@fastengines.com>
  89
  90  << INSERT OTHER STUFF HERE >>
  91
  92
  93 What's New: Version 2.0b2, 04 April 1997
  94 --------------------------------------
  95
  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.
 117
 118
 119 What's New: Version 2.0b1, 24 March 1997
 120 --------------------------------------
 121
 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
 130
 131
 132 What's New: Version 1.5.1, 12 December 1996
 133 --------------------------------------
 134
 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".
 142
 143
 144 What's New: Version 1.5, 12 June 1996
 145 --------------------------------------
 146
 147 General:
 148
 149   Added a white paper on FastCGI application performance to the
 150   doc directory.  Generally brought the other docs up to date.
 151
 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
 156   and Apache.)
 157
 158   Added the tiny-authorizer and sample-store applications to
 159   the examples.  These are explained in the index.html.
 160
 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
 165     not fatal.
 166
 167 C libraries:
 168
 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.
 177
 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).
 181
 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").
 185
 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.
 191
 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
 195   Mahoney).
 196
 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
 201   be attempted.
 202
 203 Perl:
 204
 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.
 213
 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.
 217
 218 Tcl:
 219
 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.
 230
 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.
 234
 235 Java:
 236
 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.
 241
 242
 243
 244 What's New: Version 1.4, 10 May 1996
 245 --------------------------------------
 246
 247 Includes Java classes and Java examples.
 248
 249
 250
 251 What's New: Version 1.3.1, 6 May 1996
 252 --------------------------------------
 253
 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,
 260 France.
 261
 262
 263
 264 What's New: Version 1.3, 29 April 1996
 265 --------------------------------------
 266
 267 First public release; new license terms on all files.
 268
 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
 272 you are restarting.
 273
 274
 275
 276 What's New: Version 1.2.2, 15 April 1996
 277 ----------------------------------------
 278
 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
 286 environment.
 287
 288
 289
 290 What's New: Version 1.2.1, 22 March 1996
 291 ----------------------------------------
 292
 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!
 296
 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.
 300
 301
 302
 303 What's New: Version 1.2, 20 March 1996
 304 --------------------------------------
 305
 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.
 311
 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.
 315
 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.
 321
 322 2.  We introduced the new "module" prefix FCGX in order to simplify
 323 the relationship between fcgi_stdio and fcgiapp.
 324
 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.
 332
 333 The Accept function visible in Tcl is now called FCGI_Accept, not
 334 FCGI_accept.
 335
 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.
 339
 340 3. The kit now fully supports the Responder, Authorizer,
 341 and Filter roles.
 342
 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
 346 gives full details.
 347
 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.
 353
 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.
 357
 358 4. The fcgiapp interface changed slightly in order to treat
 359 the streams and environment data more symmetrically.
 360
 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.
 366
 367 fcgiapp also added the procedure FCGX_IsCGI, providing a standardized
 368 test of whether the app was started as CGI or FastCGI.
 369
 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
 373 running configure.
 374
 375
 376
 377 What's New: Version 1.1, 30 Jan 1996
 378 ------------------------------------
 379
 380 1. More platforms: Digital UNIX, IBM AIX, Silicon Graphics IRIX,
 381 Sun SunOS 4.1.4.
 382
 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.
 387
 388
 389
 390 Version 1.0, 10 Jan 1996
 391 ------------------------