README

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