README

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