README

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