README

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