doc/fcgi-spec.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
   2 <HTML>
   3    <!--Copyright (c) 1996 Open Market, Inc.                                    -->
   4    <!--See the file "LICENSE" for information on usage and redistribution-->
   5    <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES.                   -->
   6    <HEAD>
   7       <TITLE>
   8          FastCGI Specification
   9       </TITLE>
  10 <STYLE TYPE="text/css">
  11  h5.c2 {text-align: center}
  12  div.c1 {text-align: center}
  13 </STYLE>
  14    </HEAD>
  15    <BODY>
  16       <DIV CLASS="c1">
  17          <H2>
  18             FastCGI Specification
  19          </H2>
  20       </DIV>
  21       <DIV CLASS="c1">
  22          Mark R. Brown<BR>
  23          Open Market, Inc.<BR>
  24          <P>
  25             Document Version: 1.0<BR>
  26             29 April 1996<BR>
  27          </P>
  28       </DIV>
  29       <P>
  30       </P>
  31       <H5 CLASS="c2">
  32          Copyright &copy; 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.<BR>
  33          Tel: 617-621-9500 Fax: 617-621-1703 URL: <A HREF=
  34          "http://www.openmarket.com/">http://www.openmarket.com/</A><BR>
  35          <BR>
  36          $Id: fcgi-spec.html,v 1.4 2002/02/25 00:42:59 robs Exp $
  37       </H5>
  38       <HR>
  39       <UL TYPE="square">
  40          <LI>
  41             <A HREF="#S1">1. Introduction</A>
  42          </LI>
  43          <LI>
  44             <A HREF="#S2">2. Initial Process State</A>
  45             <UL TYPE="square">
  46                <LI>
  47                   <A HREF="#S2.1">2.1 Argument list</A>
  48                </LI>
  49                <LI>
  50                   <A HREF="#S2.2">2.2 File descriptors</A>
  51                </LI>
  52                <LI>
  53                   <A HREF="#S2.3">2.3 Environment variables</A>
  54                </LI>
  55                <LI>
  56                   <A HREF="#S2.4">2.4 Other state</A>
  57                </LI>
  58             </UL>
  59          </LI>
  60          <LI>
  61             <A HREF="#S3">3. Protocol Basics</A>
  62             <UL TYPE="square">
  63                <LI>
  64                   <A HREF="#S3.1">3.1 Notation</A>
  65                </LI>
  66                <LI>
  67                   <A HREF="#S3.2">3.2 Accepting Transport Connections</A>
  68                </LI>
  69                <LI>
  70                   <A HREF="#S3.3">3.3 Records</A>
  71                </LI>
  72                <LI>
  73                   <A HREF="#S3.4">3.4 Name-Value Pairs</A>
  74                </LI>
  75                <LI>
  76                   <A HREF="#S3.5">3.5 Closing Transport Connections</A>
  77                </LI>
  78             </UL>
  79          </LI>
  80          <LI>
  81             <A HREF="#S4">4. Management Record Types</A>
  82             <UL TYPE="square">
  83                <LI>
  84                   <A HREF="#S4.1">4.1 <TT>FCGI_GET_VALUES, FCGI_GET_VALUES_RESULT</TT></A>
  85                </LI>
  86                <LI>
  87                   <A HREF="#S4.2">4.2 <TT>FCGI_UNKNOWN_TYPE</TT></A>
  88                </LI>
  89             </UL>
  90          </LI>
  91          <LI>
  92             <A HREF="#S5">5. Application Record Types</A>
  93             <UL TYPE="square">
  94                <LI>
  95                   <A HREF="#S5.1">5.1 <TT>FCGI_BEGIN_REQUEST</TT></A>
  96                </LI>
  97                <LI>
  98                   <A HREF="#S5.2">5.2 Name-Value Pair Streams: <TT>FCGI_PARAMS</TT>, <TT>FCGI_RESULTS</TT></A>
  99                </LI>
 100                <LI>
 101                   <A HREF="#S5.3">5.3 Byte Streams: <TT>FCGI_STDIN</TT>, <TT>FCGI_DATA</TT>, <TT>FCGI_STDOUT</TT>,
 102                   <TT>FCGI_STDERR</TT></A>
 103                </LI>
 104                <LI>
 105                   <A HREF="#S5.4">5.4 <TT>FCGI_ABORT_REQUEST</TT></A>
 106                </LI>
 107                <LI>
 108                   <A HREF="#S5.5">5.5 <TT>FCGI_END_REQUEST</TT></A>
 109                </LI>
 110             </UL>
 111          </LI>
 112          <LI>
 113             <A HREF="#S6">6. Roles</A>
 114             <UL TYPE="square">
 115                <LI>
 116                   <A HREF="#S6.1">6.1 Role Protocols</A>
 117                </LI>
 118                <LI>
 119                   <A HREF="#S6.2">6.2 Responder</A>
 120                </LI>
 121                <LI>
 122                   <A HREF="#S6.3">6.3 Authorizer</A>
 123                </LI>
 124                <LI>
 125                   <A HREF="#S6.4">6.4 Filter</A>
 126                </LI>
 127             </UL>
 128          </LI>
 129          <LI>
 130             <A HREF="#S7">7. Errors</A>
 131          </LI>
 132          <LI>
 133             <A HREF="#S8">8. Types and Constants</A>
 134          </LI>
 135          <LI>
 136             <A HREF="#S9">9. References</A>
 137          </LI>
 138          <LI>
 139             <A HREF="#SA">A. Table: Properties of the record types</A>
 140          </LI>
 141          <LI>
 142             <A HREF="#SB">B. Typical Protocol Message Flow</A>
 143          </LI>
 144       </UL>
 145       <P>
 146       </P>
 147       <HR>
 148       <H3>
 149          <A NAME="S1">1. Introduction</A>
 150       </H3>
 151       <P>
 152          FastCGI is an open extension to CGI that provides high performance for all Internet applications without the
 153          penalties of Web server APIs.
 154       </P>
 155       <P>
 156          This specification has narrow goal: to specify, from an application perspective, the interface between a
 157          FastCGI application and a Web server that supports FastCGI. Many Web server features related to FastCGI, e.g.
 158          application management facilities, have nothing to do with the application to Web server interface, and are
 159          not described here.
 160       </P>
 161       <P>
 162          This specification is for Unix (more precisely, for POSIX systems that support Berkeley Sockets). The bulk of
 163          the specification is a simple communications protocol that is independent of byte ordering and will extend to
 164          other systems.
 165       </P>
 166       <P>
 167          We&#39;ll introduce FastCGI by comparing it with conventional Unix implementations of CGI/1.1. FastCGI is
 168          designed to support long-lived application processes, i.e. <I>application servers</I>. That&#39;s a major
 169          difference compared with conventional Unix implementations of CGI/1.1, which construct an application process,
 170          use it respond to one request, and have it exit.
 171       </P>
 172       <P>
 173          The initial state of a FastCGI process is more spartan than the initial state of a CGI/1.1 process, because
 174          the FastCGI process doesn&#39;t begin life connected to anything. It doesn&#39;t have the conventional open
 175          files <TT>stdin</TT>, <TT>stdout</TT>, and <TT>stderr</TT>, and it doesn&#39;t receive much information
 176          through environment variables. The key piece of initial state in a FastCGI process is a listening socket,
 177          through which it accepts connections from a Web server.
 178       </P>
 179       <P>
 180          After a FastCGI process accepts a connection on its listening socket, the process executes a simple protocol
 181          to receive and send data. The protocol serves two purposes. First, the protocol multiplexes a single transport
 182          connection between several independent FastCGI requests. This supports applications that are able to process
 183          concurrent requests using event-driven or multi-threaded programming techniques. Second, within each request
 184          the protocol provides several independent data streams in each direction. This way, for instance, both
 185          <TT>stdout</TT> and <TT>stderr</TT> data pass over a single transport connection from the application to the
 186          Web server, rather than requiring separate pipes as with CGI/1.1.
 187       </P>
 188       <P>
 189          A FastCGI application plays one of several well-defined <I>roles</I>. The most familiar is the
 190          <I>Responder</I> role, in which the application receives all the information associated with an HTTP request
 191          and generates an HTTP response; that&#39;s the role CGI/1.1 programs play. A second role is <I>Authorizer</I>,
 192          in which the application receives all the information associated with an HTTP request and generates an
 193          authorized/unauthorized decision. A third role is <I>Filter</I>, in which the application receives all the
 194          information associated with an HTTP request, plus an extra stream of data from a file stored on the Web
 195          server, and generates a &quot;filtered&quot; version of the data stream as an HTTP response. The framework is
 196          extensible so that more FastCGI can be defined later.
 197       </P>
 198       <P>
 199          In the remainder of this specification the terms &quot;FastCGI application,&quot; &quot;application
 200          process,&quot; or &quot;application server&quot; are abbreviated to &quot;application&quot; whenever that
 201          won&#39;t cause confusion.
 202       </P>
 203       <P>
 204       </P>
 205       <H3>
 206          <A NAME="S2">2. Initial Process State</A>
 207       </H3>
 208       <H4>
 209          <A NAME="S2.1">2.1 Argument list</A>
 210       </H4>
 211       <P>
 212          By default the Web server creates an argument list containing a single element, the name of the application,
 213          taken to be the last component of the executable&#39;s path name. The Web server may provide a way to specify
 214          a different application name, or a more elaborate argument list.
 215       </P>
 216       <P>
 217          Note that the file executed by the Web server might be an interpreter file (a text file that starts with the
 218          characters <TT>#!</TT>), in which case the application&#39;s argument list is constructed as described in the
 219          <TT>execve</TT> manpage.
 220       </P>
 221       <P>
 222       </P>
 223       <H4>
 224          <A NAME="S2.2">2.2 File descriptors</A>
 225       </H4>
 226       <P>
 227          The Web server leaves a single file descriptor, <TT>FCGI_LISTENSOCK_FILENO</TT>, open when the application
 228          begins execution. This descriptor refers to a listening socket created by the Web server.
 229       </P>
 230       <P>
 231          <TT>FCGI_LISTENSOCK_FILENO</TT> equals <TT>STDIN_FILENO</TT>. The standard descriptors <TT>STDOUT_FILENO</TT>
 232          and <TT>STDERR_FILENO</TT> are closed when the application begins execution. A reliable method for an
 233          application to determine whether it was invoked using CGI or FastCGI is to call
 234          <TT>getpeername(FCGI_LISTENSOCK_FILENO)</TT>, which returns -1 with <TT>errno</TT> set to <TT>ENOTCONN</TT>
 235          for a FastCGI application.
 236       </P>
 237       <P>
 238          The Web server&#39;s choice of reliable transport, Unix stream pipes (<TT>AF_UNIX</TT>) or TCP/IP
 239          (<TT>AF_INET</TT>), is implicit in the internal state of the <TT>FCGI_LISTENSOCK_FILENO</TT> socket.
 240       </P>
 241       <P>
 242       </P>
 243       <H4>
 244          <A NAME="S2.3">2.3 Environment variables</A>
 245       </H4>
 246       <P>
 247          The Web server may use environment variables to pass parameters to the application. This specification defines
 248          one such variable, <TT>FCGI_WEB_SERVER_ADDRS</TT>; we expect more to be defined as the specification evolves.
 249          The Web server may provide a way to bind other environment variables, such as the <TT>PATH</TT> variable.
 250       </P>
 251       <P>
 252       </P>
 253       <H4>
 254          <A NAME="S2.4">2.4 Other state</A>
 255       </H4>
 256       <P>
 257          The Web server may provide a way to specify other components of an application&#39;s initial process state,
 258          such as the priority, user ID, group ID, root directory, and working directory of the process.
 259       </P>
 260       <P>
 261       </P>
 262       <H3>
 263          <A NAME="S3">3. Protocol Basics</A>
 264       </H3>
 265       <H4>
 266          <A NAME="S3.1">3.1 Notation</A>
 267       </H4>
 268       <P>
 269          We use C language notation to define protocol message formats. All structure elements are defined in terms of
 270          the <TT>unsigned char</TT> type, and are arranged so that an ISO C compiler lays them out in the obvious
 271          manner, with no padding. The first byte defined in the structure is transmitted first, the second byte second,
 272          etc.
 273       </P>
 274       <P>
 275          We use two conventions to abbreviate our definitions.
 276       </P>
 277       <P>
 278          First, when two adjacent structure components are named identically except for the suffixes
 279          &quot;<TT>B1</TT>&quot; and &quot;<TT>B0</TT>,&quot; it means that the two components may be viewed as a
 280          single number, computed as <TT>B1&lt;&lt;8 + B0</TT>. The name of this single number is the name of the
 281          components, minus the suffixes. This convention generalizes in an obvious way to handle numbers represented in
 282          more than two bytes.
 283       </P>
 284       <P>
 285          Second, we extend C <TT>struct</TT>s to allow the form
 286       </P>
 287 <PRE>
 288         struct {
 289             unsigned char mumbleLengthB1;
 290             unsigned char mumbleLengthB0;
 291             ... /* other stuff */
 292             unsigned char mumbleData[mumbleLength];
 293         };
 294 </PRE>
 295       <P>
 296          meaning a structure of varying length, where the length of a component is determined by the values of the
 297          indicated earlier component or components.
 298       </P>
 299       <P>
 300       </P>
 301       <H4>
 302          <A NAME="S3.2">3.2 Accepting Transport Connections</A>
 303       </H4>
 304       <P>
 305          A FastCGI application calls <TT>accept()</TT> on the socket referred to by file descriptor
 306          <TT>FCGI_LISTENSOCK_FILENO</TT> to accept a new transport connection. If the <TT>accept()</TT> succeeds, and
 307          the <TT>FCGI_WEB_SERVER_ADDRS</TT> environment variable is bound, the application application immediately
 308          performs the following special processing:
 309       </P>
 310       <P>
 311       </P>
 312       <UL TYPE="square">
 313          <LI>
 314             <TT>FCGI_WEB_SERVER_ADDRS</TT>: The value is a list of valid IP addresses for the Web server.
 315             <P>
 316                If <TT>FCGI_WEB_SERVER_ADDRS</TT> was bound, the application checks the peer IP address of the new
 317                connection for membership in the list. If the check fails (including the possibility that the connection
 318                didn&#39;t use TCP/IP transport), the application responds by closing the connection.
 319             </P>
 320             <P>
 321                <TT>FCGI_WEB_SERVER_ADDRS</TT> is expressed as a comma-separated list of IP addresses. Each IP address
 322                is written as four decimal numbers in the range [0..255] separated by decimal points. So one legal
 323                binding for this variable is <TT>FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71</TT>.
 324             </P>
 325             <BR>
 326             <BR>
 327          </LI>
 328       </UL>
 329       <P>
 330          An application may accept several concurrent transport connections, but it need not do so.
 331       </P>
 332       <P>
 333       </P>
 334       <H4>
 335          <A NAME="S3.3">3.3 Records</A>
 336       </H4>
 337       <P>
 338          Applications execute requests from a Web server using a simple protocol. Details of the protocol depend upon
 339          the application&#39;s role, but roughly speaking the Web server first sends parameters and other data to the
 340          application, then the application sends result data to the Web server, and finally the application sends the
 341          Web server an indication that the request is complete.
 342       </P>
 343       <P>
 344          All data that flows over the transport connection is carried in <I>FastCGI records</I>. FastCGI records
 345          accomplish two things. First, records multiplex the transport connection between several independent FastCGI
 346          requests. This multiplexing supports applications that are able to process concurrent requests using
 347          event-driven or multi-threaded programming techniques. Second, records provide several independent data
 348          streams in each direction within a single request. This way, for instance, both <TT>stdout</TT> and
 349          <TT>stderr</TT> data can pass over a single transport connection from the application to the Web server,
 350          rather than requiring separate connections.
 351       </P>
 352       <P>
 353       </P>
 354 <PRE>
 355         typedef struct {
 356             unsigned char version;
 357             unsigned char type;
 358             unsigned char requestIdB1;
 359             unsigned char requestIdB0;
 360             unsigned char contentLengthB1;
 361             unsigned char contentLengthB0;
 362             unsigned char paddingLength;
 363             unsigned char reserved;
 364             unsigned char contentData[contentLength];
 365             unsigned char paddingData[paddingLength];
 366         } FCGI_Record;
 367 </PRE>
 368       <P>
 369          A FastCGI record consists of a fixed-length prefix followed by a variable number of content and padding bytes.
 370          A record contains seven components:
 371       </P>
 372       <P>
 373       </P>
 374       <UL TYPE="square">
 375          <LI>
 376             <TT>version</TT>: Identifies the FastCGI protocol version. This specification documents
 377             <TT>FCGI_VERSION_1</TT>.
 378             <P>
 379             </P>
 380          </LI>
 381          <LI>
 382             <TT>type</TT>: Identifies the FastCGI record type, i.e. the general function that the record performs.
 383             Specific record types and their functions are detailed in later sections.
 384             <P>
 385             </P>
 386          </LI>
 387          <LI>
 388             <TT>requestId</TT>: Identifies the <I>FastCGI request</I> to which the record belongs.
 389             <P>
 390             </P>
 391          </LI>
 392          <LI>
 393             <TT>contentLength</TT>: The number of bytes in the <TT>contentData</TT> component of the record.
 394             <P>
 395             </P>
 396          </LI>
 397          <LI>
 398             <TT>paddingLength</TT>: The number of bytes in the <TT>paddingData</TT> component of the record.
 399             <P>
 400             </P>
 401          </LI>
 402          <LI>
 403             <TT>contentData</TT>: Between 0 and 65535 bytes of data, interpreted according to the record type.
 404             <P>
 405             </P>
 406          </LI>
 407          <LI>
 408             <TT>paddingData</TT>: Between 0 and 255 bytes of data, which are ignored.<BR>
 409             <BR>
 410          </LI>
 411       </UL>
 412       <P>
 413          We use a relaxed C <TT>struct</TT> initializer syntax to specify constant FastCGI records. We omit the
 414          <TT>version</TT> component, ignore padding, and treat <TT>requestId</TT> as a number. Thus
 415          <TT>{FCGI_END_REQUEST, 1, {FCGI_REQUEST_COMPLETE,0}}</TT> is a record with <TT>type == FCGI_END_REQUEST</TT>,
 416          <TT>requestId == 1</TT>, and <TT>contentData == {FCGI_REQUEST_COMPLETE,0}</TT>.
 417       </P>
 418       <P>
 419       </P>
 420       <H5>
 421          Padding
 422       </H5>
 423       <P>
 424          The protocol allows senders to pad the records they send, and requires receivers to interpret the
 425          <TT>paddingLength</TT> and skip the <TT>paddingData</TT>. Padding allows senders to keep data aligned for more
 426          efficient processing. Experience with the X window system protocols shows the performance benefit of such
 427          alignment.
 428       </P>
 429       <P>
 430          We recommend that records be placed on boundaries that are multiples of eight bytes. The fixed-length portion
 431          of a <TT>FCGI_Record</TT> is eight bytes.
 432       </P>
 433       <P>
 434       </P>
 435       <H5>
 436          Managing Request IDs
 437       </H5>
 438       <P>
 439          The Web server re-uses FastCGI request IDs; the application keeps track of the current state of each request
 440          ID on a given transport connection. A request ID <TT>R</TT> becomes active when the application receives a
 441          record <TT>{FCGI_BEGIN_REQUEST, R, ...}</TT> and becomes inactive when the application sends a record
 442          <TT>{FCGI_END_REQUEST, R, ...}</TT> to the Web server.
 443       </P>
 444       <P>
 445          While a request ID <TT>R</TT> is inactive, the application ignores records with <TT>requestId == R</TT>,
 446          except for <TT>FCGI_BEGIN_REQUEST</TT> records as just described.
 447       </P>
 448       <P>
 449          The Web server attempts to keep FastCGI request IDs small. That way the application can keep track of request
 450          ID states using a short array rather than a long array or a hash table. An application also has the option of
 451          accepting only one request at a time. In this case the application simply checks incoming <TT>requestId</TT>
 452          values against the current request ID.
 453       </P>
 454       <P>
 455       </P>
 456       <H5>
 457          Types of Record Types
 458       </H5>
 459       <P>
 460          There are two useful ways of classifying FastCGI record types.
 461       </P>
 462       <P>
 463          The first distinction is between <I>management</I> records and <I>application</I> records. A management record
 464          contains information that is not specific to any Web server request, such as information about the protocol
 465          capabilities of the application. An application record contains information about a particular request,
 466          identified by the <TT>requestId</TT> component.
 467       </P>
 468       <P>
 469          Management records have a <TT>requestId</TT> value of zero, also called the <I>null request ID</I>.
 470          Application records have a nonzero <TT>requestId</TT>.
 471       </P>
 472       <P>
 473          The second distinction is between <I>discrete</I> and <I>stream</I> records. A discrete record contains a
 474          meaningful unit of data all by itself. A stream record is part of a <I>stream</I>, i.e. a series of zero or
 475          more non-empty records (<TT>length != 0</TT>) of the stream type, followed by an empty record (<TT>length ==
 476          0</TT>) of the stream type. The <TT>contentData</TT> components of a stream&#39;s records, when concatenated,
 477          form a byte sequence; this byte sequence is the value of the stream. Therefore the value of a stream is
 478          independent of how many records it contains or how its bytes are divided among the non-empty records.
 479       </P>
 480       <P>
 481          These two classifications are independent. Among the record types defined in this version of the FastCGI
 482          protocol, all management record types are also discrete record types, and nearly all application record types
 483          are stream record types. But three application record types are discrete, and nothing prevents defining a
 484          management record type that&#39;s a stream in some later version of the protocol.
 485       </P>
 486       <P>
 487       </P>
 488       <H4>
 489          <A NAME="S3.4">3.4 Name-Value Pairs</A>
 490       </H4>
 491       <P>
 492          In many of their roles, FastCGI applications need to read and write varying numbers of variable-length values.
 493          So it is useful to adopt a standard format for encoding a name-value pair.
 494       </P>
 495       <P>
 496          FastCGI transmits a name-value pair as the length of the name, followed by the length of the value, followed
 497          by the name, followed by the value. Lengths of 127 bytes and less can be encoded in one byte, while longer
 498          lengths are always encoded in four bytes:
 499       </P>
 500       <P>
 501       </P>
 502 <PRE>
 503         typedef struct {
 504             unsigned char nameLengthB0;  /* nameLengthB0  &gt;&gt; 7 == 0 */
 505             unsigned char valueLengthB0; /* valueLengthB0 &gt;&gt; 7 == 0 */
 506             unsigned char nameData[nameLength];
 507             unsigned char valueData[valueLength];
 508         } FCGI_NameValuePair11;
 509
 510         typedef struct {
 511             unsigned char nameLengthB0;  /* nameLengthB0  &gt;&gt; 7 == 0 */
 512             unsigned char valueLengthB3; /* valueLengthB3 &gt;&gt; 7 == 1 */
 513             unsigned char valueLengthB2;
 514             unsigned char valueLengthB1;
 515             unsigned char valueLengthB0;
 516             unsigned char nameData[nameLength];
 517             unsigned char valueData[valueLength
 518                     ((B3 &amp; 0x7f) &lt;&lt; 24) + (B2 &lt;&lt; 16) + (B1 &lt;&lt; 8) + B0];
 519         } FCGI_NameValuePair14;
 520
 521         typedef struct {
 522             unsigned char nameLengthB3;  /* nameLengthB3  &gt;&gt; 7 == 1 */
 523             unsigned char nameLengthB2;
 524             unsigned char nameLengthB1;
 525             unsigned char nameLengthB0;
 526             unsigned char valueLengthB0; /* valueLengthB0 &gt;&gt; 7 == 0 */
 527             unsigned char nameData[nameLength
 528                     ((B3 &amp; 0x7f) &lt;&lt; 24) + (B2 &lt;&lt; 16) + (B1 &lt;&lt; 8) + B0];
 529             unsigned char valueData[valueLength];
 530         } FCGI_NameValuePair41;
 531
 532         typedef struct {
 533             unsigned char nameLengthB3;  /* nameLengthB3  &gt;&gt; 7 == 1 */
 534             unsigned char nameLengthB2;
 535             unsigned char nameLengthB1;
 536             unsigned char nameLengthB0;
 537             unsigned char valueLengthB3; /* valueLengthB3 &gt;&gt; 7 == 1 */
 538             unsigned char valueLengthB2;
 539             unsigned char valueLengthB1;
 540             unsigned char valueLengthB0;
 541             unsigned char nameData[nameLength
 542                     ((B3 &amp; 0x7f) &lt;&lt; 24) + (B2 &lt;&lt; 16) + (B1 &lt;&lt; 8) + B0];
 543             unsigned char valueData[valueLength
 544                     ((B3 &amp; 0x7f) &lt;&lt; 24) + (B2 &lt;&lt; 16) + (B1 &lt;&lt; 8) + B0];
 545         } FCGI_NameValuePair44;
 546 </PRE>
 547       <P>
 548          The high-order bit of the first byte of a length indicates the length&#39;s encoding. A high-order zero
 549          implies a one-byte encoding, a one a four-byte encoding.
 550       </P>
 551       <P>
 552          This name-value pair format allows the sender to transmit binary values without additional encoding, and
 553          enables the receiver to allocate the correct amount of storage immediately even for large values.
 554       </P>
 555       <P>
 556       </P>
 557       <H4>
 558          <A NAME="S3.5">3.5 Closing Transport Connections</A>
 559       </H4>
 560       <P>
 561          The Web server controls the lifetime of transport connections. The Web server can close a connection when no
 562          requests are active. Or the Web server can delegate close authority to the application (see
 563          <TT>FCGI_BEGIN_REQUEST</TT>). In this case the application closes the connection at the end of a specified
 564          request.
 565       </P>
 566       <P>
 567          This flexibility accommodates a variety of application styles. Simple applications will process one request at
 568          a time and accept a new transport connection for each request. More complex applications will process
 569          concurrent requests, over one or multiple transport connections, and will keep transport connections open for
 570          long periods of time.
 571       </P>
 572       <P>
 573          A simple application gets a significant performance boost by closing the transport connection when it has
 574          finished writing its response. The Web server needs to control the connection lifetime for long-lived
 575          connections.
 576       </P>
 577       <P>
 578          When an application closes a connection or finds that a connection has closed, the application initiates a new
 579          connection.
 580       </P>
 581       <P>
 582       </P>
 583       <H3>
 584          <A NAME="S4">4. Management Record Types</A>
 585       </H3>
 586       <H4>
 587          <A NAME="S4.1">4.1 <TT>FCGI_GET_VALUES, FCGI_GET_VALUES_RESULT</TT></A>
 588       </H4>
 589       <P>
 590          The Web server can query specific variables within the application. The server will typically perform a query
 591          on application startup in order to to automate certain aspects of system configuration.
 592       </P>
 593       <P>
 594          The application receives a query as a record <TT>{FCGI_GET_VALUES, 0, ...}</TT>. The <TT>contentData</TT>
 595          portion of a <TT>FCGI_GET_VALUES</TT> record contains a sequence of name-value pairs with empty values.
 596       </P>
 597       <P>
 598          The application responds by sending a record <TT>{FCGI_GET_VALUES_RESULT, 0, ...}</TT> with the values
 599          supplied. If the application doesn&#39;t understand a variable name that was included in the query, it omits
 600          that name from the response.
 601       </P>
 602       <P>
 603          <TT>FCGI_GET_VALUES</TT> is designed to allow an open-ended set of variables. The initial set provides
 604          information to help the server perform application and connection management:
 605       </P>
 606       <P>
 607       </P>
 608       <UL TYPE="square">
 609          <LI>
 610             <TT>FCGI_MAX_CONNS</TT>: The maximum number of concurrent transport connections this application will
 611             accept, e.g. <TT>&quot;1&quot;</TT> or <TT>&quot;10&quot;</TT>.
 612             <P>
 613             </P>
 614          </LI>
 615          <LI>
 616             <TT>FCGI_MAX_REQS</TT>: The maximum number of concurrent requests this application will accept, e.g.
 617             <TT>&quot;1&quot;</TT> or <TT>&quot;50&quot;</TT>.
 618             <P>
 619             </P>
 620          </LI>
 621          <LI>
 622             <TT>FCGI_MPXS_CONNS</TT>: <TT>&quot;0&quot;</TT> if this application does not multiplex connections (i.e.
 623             handle concurrent requests over each connection), <TT>&quot;1&quot;</TT> otherwise.<BR>
 624             <BR>
 625          </LI>
 626       </UL>
 627       <P>
 628          An application may receive a <TT>FCGI_GET_VALUES</TT> record at any time. The application&#39;s response
 629          should not involve the application proper but only the FastCGI library.
 630       </P>
 631       <P>
 632       </P>
 633       <H4>
 634          <A NAME="S4.2">4.2 <TT>FCGI_UNKNOWN_TYPE</TT></A>
 635       </H4>
 636       <P>
 637          The set of management record types is likely to grow in future versions of this protocol. To provide for this
 638          evolution, the protocol includes the <TT>FCGI_UNKNOWN_TYPE</TT> management record. When an application
 639          receives a management record whose type <TT>T</TT> it does not understand, the application responds with
 640          <TT>{FCGI_UNKNOWN_TYPE, 0, {T}}</TT>.
 641       </P>
 642       <P>
 643          The <TT>contentData</TT> component of a <TT>FCGI_UNKNOWN_TYPE</TT> record has the form:
 644       </P>
 645 <PRE>
 646         typedef struct {
 647             unsigned char type;
 648             unsigned char reserved[7];
 649         } FCGI_UnknownTypeBody;
 650 </PRE>
 651       <P>
 652          The <TT>type</TT> component is the type of the unrecognized management record.
 653       </P>
 654       <P>
 655       </P>
 656       <H3>
 657          <A NAME="S5">5. Application Record Types</A>
 658       </H3>
 659       <H4>
 660          <A NAME="S5.1">5.1 <TT>FCGI_BEGIN_REQUEST</TT></A>
 661       </H4>
 662       <P>
 663          The Web server sends a <TT>FCGI_BEGIN_REQUEST</TT> record to start a request.
 664       </P>
 665       <P>
 666          The <TT>contentData</TT> component of a <TT>FCGI_BEGIN_REQUEST</TT> record has the form:
 667       </P>
 668 <PRE>
 669         typedef struct {
 670             unsigned char roleB1;
 671             unsigned char roleB0;
 672             unsigned char flags;
 673             unsigned char reserved[5];
 674         } FCGI_BeginRequestBody;
 675 </PRE>
 676       <P>
 677          The <TT>role</TT> component sets the role the Web server expects the application to play. The
 678          currently-defined roles are:
 679       </P>
 680       <P>
 681       </P>
 682       <UL TYPE="square">
 683          <LI>
 684             <TT>FCGI_RESPONDER</TT>
 685          </LI>
 686          <LI>
 687             <TT>FCGI_AUTHORIZER</TT>
 688          </LI>
 689          <LI>
 690             <TT>FCGI_FILTER</TT>
 691          </LI>
 692       </UL>
 693       <P>
 694          Roles are described in more detail in <A HREF="#S6">Section 6</A> below.
 695       </P>
 696       <P>
 697          The <TT>flags</TT> component contains a bit that controls connection shutdown:
 698       </P>
 699       <P>
 700       </P>
 701       <UL TYPE="square">
 702          <LI>
 703             <TT>flags &amp; FCGI_KEEP_CONN</TT>: If zero, the application closes the connection after responding to
 704             this request. If not zero, the application does not close the connection after responding to this request;
 705             the Web server retains responsibility for the connection.<BR>
 706             <BR>
 707          </LI>
 708       </UL>
 709       <H4>
 710          <A NAME="S5.2">5.2 Name-Value Pair Stream: <TT>FCGI_PARAMS</TT></A>
 711       </H4>
 712       <TT>FCGI_PARAMS</TT>
 713       <P>
 714          is a stream record type used in sending name-value pairs from the Web server to the application. The
 715          name-value pairs are sent down the stream one after the other, in no specified order.
 716       </P>
 717       <P>
 718       </P>
 719       <H4>
 720          <A NAME="S5.3">5.3 Byte Streams: <TT>FCGI_STDIN</TT>, <TT>FCGI_DATA</TT>, <TT>FCGI_STDOUT</TT>,
 721          <TT>FCGI_STDERR</TT></A>
 722       </H4>
 723       <TT>FCGI_STDIN</TT>
 724       <P>
 725          is a stream record type used in sending arbitrary data from the Web server to the application.
 726          <TT>FCGI_DATA</TT> is a second stream record type used to send additional data to the application.
 727       </P>
 728       <P>
 729          <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT> are stream record types for sending arbitrary data and error
 730          data respectively from the application to the Web server.
 731       </P>
 732       <P>
 733       </P>
 734       <H4>
 735          <A NAME="S5.4">5.4 <TT>FCGI_ABORT_REQUEST</TT></A>
 736       </H4>
 737       <P>
 738          The Web server sends a <TT>FCGI_ABORT_REQUEST</TT> record to abort a request. After receiving
 739          <TT>{FCGI_ABORT_REQUEST, R}</TT>, the application responds as soon as possible with <TT>{FCGI_END_REQUEST, R,
 740          {FCGI_REQUEST_COMPLETE, appStatus}}</TT>. This is truly a response from the application, not a low-level
 741          acknowledgement from the FastCGI library.
 742       </P>
 743       <P>
 744          A Web server aborts a FastCGI request when an HTTP client closes its transport connection while the FastCGI
 745          request is running on behalf of that client. The situation may seem unlikely; most FastCGI requests will have
 746          short response times, with the Web server providing output buffering if the client is slow. But the FastCGI
 747          application may be delayed communicating with another system, or performing a server push.
 748       </P>
 749       <P>
 750          When a Web server is not multiplexing requests over a transport connection, the Web server can abort a request
 751          by closing the request&#39;s transport connection. But with multiplexed requests, closing the transport
 752          connection has the unfortunate effect of aborting <I>all</I> the requests on the connection.
 753       </P>
 754       <P>
 755       </P>
 756       <H4>
 757          <A NAME="S5.5">5.5 <TT>FCGI_END_REQUEST</TT></A>
 758       </H4>
 759       <P>
 760          The application sends a <TT>FCGI_END_REQUEST</TT> record to terminate a request, either because the
 761          application has processed the request or because the application has rejected the request.
 762       </P>
 763       <P>
 764          The <TT>contentData</TT> component of a <TT>FCGI_END_REQUEST</TT> record has the form:
 765       </P>
 766 <PRE>
 767         typedef struct {
 768             unsigned char appStatusB3;
 769             unsigned char appStatusB2;
 770             unsigned char appStatusB1;
 771             unsigned char appStatusB0;
 772             unsigned char protocolStatus;
 773             unsigned char reserved[3];
 774         } FCGI_EndRequestBody;
 775 </PRE>
 776       <P>
 777          The <TT>appStatus</TT> component is an application-level status code. Each role documents its usage of
 778          <TT>appStatus</TT>.
 779       </P>
 780       <P>
 781          The <TT>protocolStatus</TT> component is a protocol-level status code; the possible <TT>protocolStatus</TT>
 782          values are:
 783       </P>
 784       <P>
 785       </P>
 786       <UL TYPE="square">
 787          <LI>
 788             <TT>FCGI_REQUEST_COMPLETE</TT>: normal end of request.
 789             <P>
 790             </P>
 791          </LI>
 792          <LI>
 793             <TT>FCGI_CANT_MPX_CONN</TT>: rejecting a new request. This happens when a Web server sends concurrent
 794             requests over one connection to an application that is designed to process one request at a time per
 795             connection.
 796             <P>
 797             </P>
 798          </LI>
 799          <LI>
 800             <TT>FCGI_OVERLOADED</TT>: rejecting a new request. This happens when the application runs out of some
 801             resource, e.g. database connections.
 802             <P>
 803             </P>
 804          </LI>
 805          <LI>
 806             <TT>FCGI_UNKNOWN_ROLE</TT>: rejecting a new request. This happens when the Web server has specified a role
 807             that is unknown to the application.<BR>
 808             <BR>
 809          </LI>
 810       </UL>
 811       <H3>
 812          <A NAME="S6">6. Roles</A>
 813       </H3>
 814       <H4>
 815          <A NAME="S6.1">6.1 Role Protocols</A>
 816       </H4>
 817       <P>
 818          Role protocols only include records with application record types. They transfer essentially all data using
 819          streams.
 820       </P>
 821       <P>
 822          To make the protocols reliable and to simplify application programming, role protocols are designed to use
 823          <I>nearly sequential marshalling</I>. In a protocol with strictly sequential marshalling, the application
 824          receives its first input, then its second, etc. until it has received them all. Similarly, the application
 825          sends its first output, then its second, etc. until it has sent them all. Inputs are not interleaved with each
 826          other, and outputs are not interleaved with each other.
 827       </P>
 828       <P>
 829          The sequential marshalling rule is too restrictive for some FastCGI roles, because CGI programs can write to
 830          both <TT>stdout</TT> and <TT>stderr</TT> without timing restrictions. So role protocols that use both
 831          <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT> allow these two streams to be interleaved.
 832       </P>
 833       <P>
 834          All role protocols use the <TT>FCGI_STDERR</TT> stream just the way <TT>stderr</TT> is used in conventional
 835          applications programming: to report application-level errors in an intelligible way. Use of the
 836          <TT>FCGI_STDERR</TT> stream is always optional. If an application has no errors to report, it sends either no
 837          <TT>FCGI_STDERR</TT> records or one zero-length <TT>FCGI_STDERR</TT> record.
 838       </P>
 839       <P>
 840          When a role protocol calls for transmitting a stream other than <TT>FCGI_STDERR</TT>, at least one record of
 841          the stream type is always transmitted, even if the stream is empty.
 842       </P>
 843       <P>
 844          Again in the interests of reliable protocols and simplified application programming, role protocols are
 845          designed to be <I>nearly request-response</I>. In a truly request-response protocol, the application receives
 846          all of its input records before sending its first output record. Request-response protocols don&#39;t allow
 847          pipelining.
 848       </P>
 849       <P>
 850          The request-response rule is too restrictive for some FastCGI roles; after all, CGI programs aren&#39;t
 851          restricted to read all of <TT>stdin</TT> before starting to write <TT>stdout</TT>. So some role protocols
 852          allow that specific possibility. First the application receives all of its inputs except for a final stream
 853          input. As the application begins to receive the final stream input, it can begin writing its output.
 854       </P>
 855       <P>
 856          When a role protocol uses <TT>FCGI_PARAMS</TT> to transmit textual values, such as the values that CGI
 857          programs obtain from environment variables, the length of the value does not include the terminating null
 858          byte, and the value itself does not include a null byte. An application that needs to provide
 859          <TT>environ(7)</TT> format name-value pairs must insert an equal sign between the name and value and append a
 860          null byte after the value.
 861       </P>
 862       <P>
 863          Role protocols do not support the non-parsed header feature of CGI. FastCGI applications set response status
 864          using the <TT>Status</TT> and <TT>Location</TT> CGI headers.
 865       </P>
 866       <P>
 867       </P>
 868       <H4>
 869          <A NAME="S6.2">6.2 Responder</A>
 870       </H4>
 871       <P>
 872          A Responder FastCGI application has the same purpose as a CGI/1.1 program: It receives all the information
 873          associated with an HTTP request and generates an HTTP response.
 874       </P>
 875       <P>
 876          It suffices to explain how each element of CGI/1.1 is emulated by a Responder:
 877       </P>
 878       <BR>
 879       <BR>
 880       <UL TYPE="square">
 881          <LI>
 882             The Responder application receives CGI/1.1 environment variables from the Web server over
 883             <TT>FCGI_PARAMS</TT>.
 884             <P>
 885             </P>
 886          </LI>
 887          <LI>
 888             Next the Responder application receives CGI/1.1 <TT>stdin</TT> data from the Web server over
 889             <TT>FCGI_STDIN</TT>. The application receives at most <TT>CONTENT_LENGTH</TT> bytes from this stream before
 890             receiving the end-of-stream indication. (The application receives less than <TT>CONTENT_LENGTH</TT> bytes
 891             only if the HTTP client fails to provide them, e.g. because the client crashed.)
 892             <P>
 893             </P>
 894          </LI>
 895          <LI>
 896             The Responder application sends CGI/1.1 <TT>stdout</TT> data to the Web server over <TT>FCGI_STDOUT</TT>,
 897             and CGI/1.1 <TT>stderr</TT> data over <TT>FCGI_STDERR</TT>. The application sends these concurrently, not
 898             one after the other. The application must wait to finish reading <TT>FCGI_PARAMS</TT> before it begins
 899             writing <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT>, but it needn&#39;t finish reading from
 900             <TT>FCGI_STDIN</TT> before it begins writing these two streams.
 901             <P>
 902             </P>
 903          </LI>
 904          <LI>
 905             After sending all its <TT>stdout</TT> and <TT>stderr</TT> data, the Responder application sends a
 906             <TT>FCGI_END_REQUEST</TT> record. The application sets the <TT>protocolStatus</TT> component to
 907             <TT>FCGI_REQUEST_COMPLETE</TT> and the <TT>appStatus</TT> component to the status code that the CGI program
 908             would have returned via the <TT>exit</TT> system call.<BR>
 909             <BR>
 910          </LI>
 911       </UL>
 912       <P>
 913          A Responder performing an update, e.g. implementing a <TT>POST</TT> method, should compare the number of bytes
 914          received on <TT>FCGI_STDIN</TT> with <TT>CONTENT_LENGTH</TT> and abort the update if the two numbers are not
 915          equal.
 916       </P>
 917       <P>
 918       </P>
 919       <H4>
 920          <A NAME="S6.3">6.3 Authorizer</A>
 921       </H4>
 922       <P>
 923          An Authorizer FastCGI application receives all the information associated with an HTTP request and generates
 924          an authorized/unauthorized decision. In case of an authorized decision the Authorizer can also associate
 925          name-value pairs with the HTTP request; when giving an unauthorized decision the Authorizer sends a complete
 926          response to the HTTP client.
 927       </P>
 928       <P>
 929          Since CGI/1.1 defines a perfectly good way to represent the information associated with an HTTP request,
 930          Authorizers use the same representation:
 931       </P>
 932       <P>
 933       </P>
 934       <UL TYPE="square">
 935          <LI>
 936             The Authorizer application receives HTTP request information from the Web server on the
 937             <TT>FCGI_PARAMS</TT> stream, in the same format as a Responder. The Web server does not send
 938             <TT>CONTENT_LENGTH</TT>, <TT>PATH_INFO</TT>, <TT>PATH_TRANSLATED</TT>, and <TT>SCRIPT_NAME</TT> headers.
 939             <P>
 940             </P>
 941          </LI>
 942          <LI>
 943             The Authorizer application sends <TT>stdout</TT> and <TT>stderr</TT> data in the same manner as a
 944             Responder. The CGI/1.1 response status specifies the disposition of the request. If the application sends
 945             status 200 (OK), the Web server allows access. Depending upon its configuration the Web server may proceed
 946             with other access checks, including requests to other Authorizers.
 947             <P>
 948                An Authorizer application&#39;s 200 response may include headers whose names are prefixed with
 949                <TT>Variable-</TT>. These headers communicate name-value pairs from the application to the Web server.
 950                For instance, the response header
 951             </P>
 952 <PRE>
 953         Variable-AUTH_METHOD: database lookup
 954 </PRE>
 955             transmits the value <TT>&quot;database lookup&quot;</TT> with name <TT>AUTH-METHOD</TT>. The server
 956             associates such name-value pairs with the HTTP request and includes them in subsequent CGI or FastCGI
 957             requests performed in processing the HTTP request. When the application gives a 200 response, the server
 958             ignores response headers whose names aren&#39;t prefixed with <TT>Variable-</TT> prefix, and ignores any
 959             response content.
 960             <P>
 961                For Authorizer response status values other than &quot;200&quot; (OK), the Web server denies access and
 962                sends the response status, headers, and content back to the HTTP client.
 963             </P>
 964             <BR>
 965             <BR>
 966          </LI>
 967       </UL>
 968       <H4>
 969          <A NAME="S6.4">6.4 Filter</A>
 970       </H4>
 971       <P>
 972          A Filter FastCGI application receives all the information associated with an HTTP request, plus an extra
 973          stream of data from a file stored on the Web server, and generates a &quot;filtered&quot; version of the data
 974          stream as an HTTP response.
 975       </P>
 976       <P>
 977          A Filter is similar in functionality to a Responder that takes a data file as a parameter. The difference is
 978          that with a Filter, both the data file and the Filter itself can be access controlled using the Web
 979          server&#39;s access control mechanisms, while a Responder that takes the name of a data file as a parameter
 980          must perform its own access control checks on the data file.
 981       </P>
 982       <P>
 983          The steps taken by a Filter are similar to those of a Responder. The server presents the Filter with
 984          environment variables first, then standard input (normally form <TT>POST</TT> data), finally the data file
 985          input:
 986       </P>
 987       <BR>
 988       <BR>
 989       <UL TYPE="square">
 990          <LI>
 991             Like a Responder, the Filter application receives name-value pairs from the Web server over
 992             <TT>FCGI_PARAMS</TT>. Filter applications receive two Filter-specific variables:
 993             <TT>FCGI_DATA_LAST_MOD</TT> and <TT>FCGI_DATA_LENGTH</TT>.
 994             <P>
 995             </P>
 996          </LI>
 997          <LI>
 998             Next the Filter application receives CGI/1.1 <TT>stdin</TT> data from the Web server over
 999             <TT>FCGI_STDIN</TT>. The application receives at most <TT>CONTENT_LENGTH</TT> bytes from this stream before
1000             receiving the end-of-stream indication. (The application receives less than <TT>CONTENT_LENGTH</TT> bytes
1001             only if the HTTP client fails to provide them, e.g. because the client crashed.)
1002             <P>
1003             </P>
1004          </LI>
1005          <LI>
1006             Next the Filter application receives the file data from the Web server over <TT>FCGI_DATA</TT>. This
1007             file&#39;s last modification time (expressed as an integer number of seconds since the epoch January 1,
1008             1970 UTC) is <TT>FCGI_DATA_LAST_MOD</TT>; the application may consult this variable and respond from a
1009             cache without reading the file data. The application reads at most <TT>FCGI_DATA_LENGTH</TT> bytes from
1010             this stream before receiving the end-of-stream indication.
1011             <P>
1012             </P>
1013          </LI>
1014          <LI>
1015             The Filter application sends CGI/1.1 <TT>stdout</TT> data to the Web server over <TT>FCGI_STDOUT</TT>, and
1016             CGI/1.1 <TT>stderr</TT> data over <TT>FCGI_STDERR</TT>. The application sends these concurrently, not one
1017             after the other. The application must wait to finish reading <TT>FCGI_STDIN</TT> before it begins writing
1018             <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT>, but it needn&#39;t finish reading from <TT>FCGI_DATA</TT>
1019             before it begins writing these two streams.
1020             <P>
1021             </P>
1022          </LI>
1023          <LI>
1024             After sending all its <TT>stdout</TT> and <TT>stderr</TT> data, the application sends a
1025             <TT>FCGI_END_REQUEST</TT> record. The application sets the <TT>protocolStatus</TT> component to
1026             <TT>FCGI_REQUEST_COMPLETE</TT> and the <TT>appStatus</TT> component to the status code that a similar CGI
1027             program would have returned via the <TT>exit</TT> system call.<BR>
1028             <BR>
1029          </LI>
1030       </UL>
1031       <P>
1032          A Filter should compare the number of bytes received on <TT>FCGI_STDIN</TT> with <TT>CONTENT_LENGTH</TT> and
1033          on <TT>FCGI_DATA</TT> with <TT>FCGI_DATA_LENGTH</TT>. If the numbers don&#39;t match and the Filter is a
1034          query, the Filter response should provide an indication that data is missing. If the numbers don&#39;t match
1035          and the Filter is an update, the Filter should abort the update.
1036       </P>
1037       <P>
1038       </P>
1039       <H3>
1040          <A NAME="S7">7. Errors</A>
1041       </H3>
1042       <P>
1043          A FastCGI application exits with zero status to indicate that it terminated on purpose, e.g. in order to
1044          perform a crude form of garbage collection. A FastCGI application that exits with nonzero status is assumed to
1045          have crashed. How a Web server or other application manager responds to applications that exit with zero or
1046          nonzero status is outside the scope of this specification.
1047       </P>
1048       <P>
1049          A Web server can request that a FastCGI application exit by sending it <TT>SIGTERM</TT>. If the application
1050          ignores <TT>SIGTERM</TT> the Web server can resort to <TT>SIGKILL</TT>.
1051       </P>
1052       <P>
1053          FastCGI applications report application-level errors with the <TT>FCGI_STDERR</TT> stream and the
1054          <TT>appStatus</TT> component of the <TT>FCGI_END_REQUEST</TT> record. In many cases an error will be reported
1055          directly to the user via the <TT>FCGI_STDOUT</TT> stream.
1056       </P>
1057       <P>
1058          On Unix, applications report lower-level errors, including FastCGI protocol errors and syntax errors in
1059          FastCGI environment variables, to <TT>syslog</TT>. Depending upon the severity of the error, the application
1060          may either continue or exit with nonzero status.
1061       </P>
1062       <P>
1063       </P>
1064       <H3>
1065          <A NAME="S8">8. Types and Constants</A>
1066       </H3>
1067 <PRE>
1068 /*
1069  * Listening socket file number
1070  */
1071 #define FCGI_LISTENSOCK_FILENO 0
1072
1073 typedef struct {
1074     unsigned char version;
1075     unsigned char type;
1076     unsigned char requestIdB1;
1077     unsigned char requestIdB0;
1078     unsigned char contentLengthB1;
1079     unsigned char contentLengthB0;
1080     unsigned char paddingLength;
1081     unsigned char reserved;
1082 } FCGI_Header;
1083
1084 /*
1085  * Number of bytes in a FCGI_Header.  Future versions of the protocol
1086  * will not reduce this number.
1087  */
1088 #define FCGI_HEADER_LEN  8
1089
1090 /*
1091  * Value for version component of FCGI_Header
1092  */
1093 #define FCGI_VERSION_1           1
1094
1095 /*
1096  * Values for type component of FCGI_Header
1097  */
1098 #define FCGI_BEGIN_REQUEST       1
1099 #define FCGI_ABORT_REQUEST       2
1100 #define FCGI_END_REQUEST         3
1101 #define FCGI_PARAMS              4
1102 #define FCGI_STDIN               5
1103 #define FCGI_STDOUT              6
1104 #define FCGI_STDERR              7
1105 #define FCGI_DATA                8
1106 #define FCGI_GET_VALUES          9
1107 #define FCGI_GET_VALUES_RESULT  10
1108 #define FCGI_UNKNOWN_TYPE       11
1109 #define FCGI_MAXTYPE (FCGI_UNKNOWN_TYPE)
1110
1111 /*
1112  * Value for requestId component of FCGI_Header
1113  */
1114 #define FCGI_NULL_REQUEST_ID     0
1115
1116 typedef struct {
1117     unsigned char roleB1;
1118     unsigned char roleB0;
1119     unsigned char flags;
1120     unsigned char reserved[5];
1121 } FCGI_BeginRequestBody;
1122
1123 typedef struct {
1124     FCGI_Header header;
1125     FCGI_BeginRequestBody body;
1126 } FCGI_BeginRequestRecord;
1127
1128 /*
1129  * Mask for flags component of FCGI_BeginRequestBody
1130  */
1131 #define FCGI_KEEP_CONN  1
1132
1133 /*
1134  * Values for role component of FCGI_BeginRequestBody
1135  */
1136 #define FCGI_RESPONDER  1
1137 #define FCGI_AUTHORIZER 2
1138 #define FCGI_FILTER     3
1139
1140 typedef struct {
1141     unsigned char appStatusB3;
1142     unsigned char appStatusB2;
1143     unsigned char appStatusB1;
1144     unsigned char appStatusB0;
1145     unsigned char protocolStatus;
1146     unsigned char reserved[3];
1147 } FCGI_EndRequestBody;
1148
1149 typedef struct {
1150     FCGI_Header header;
1151     FCGI_EndRequestBody body;
1152 } FCGI_EndRequestRecord;
1153
1154 /*
1155  * Values for protocolStatus component of FCGI_EndRequestBody
1156  */
1157 #define FCGI_REQUEST_COMPLETE 0
1158 #define FCGI_CANT_MPX_CONN    1
1159 #define FCGI_OVERLOADED       2
1160 #define FCGI_UNKNOWN_ROLE     3
1161
1162 /*
1163  * Variable names for FCGI_GET_VALUES / FCGI_GET_VALUES_RESULT records
1164  */
1165 #define FCGI_MAX_CONNS  &quot;FCGI_MAX_CONNS&quot;
1166 #define FCGI_MAX_REQS   &quot;FCGI_MAX_REQS&quot;
1167 #define FCGI_MPXS_CONNS &quot;FCGI_MPXS_CONNS&quot;
1168
1169 typedef struct {
1170     unsigned char type;
1171     unsigned char reserved[7];
1172 } FCGI_UnknownTypeBody;
1173
1174 typedef struct {
1175     FCGI_Header header;
1176     FCGI_UnknownTypeBody body;
1177 } FCGI_UnknownTypeRecord;
1178 </PRE>
1179       <P>
1180       </P>
1181       <H3>
1182          <A NAME="S9">9. References</A>
1183       </H3>
1184       <P>
1185          National Center for Supercomputer Applications, <A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">The Common Gateway
1186          Interface</A>, version CGI/1.1.
1187       </P>
1188       <P>
1189          D.R.T. Robinson, <A HREF="http://cgi-spec.golux.com/">The WWW
1190          Common Gateway Interface Version 1.1</A>, Internet-Draft, 15 February 1996.
1191       </P>
1192       <P>
1193       </P>
1194       <H3>
1195          <A NAME="SA">A. Table: Properties of the record types</A>
1196       </H3>
1197       <P>
1198          The following chart lists all of the record types and indicates these properties of each:
1199       </P>
1200       <P>
1201       </P>
1202       <UL TYPE="square">
1203          <LI>
1204             <TT>WS-&gt;App</TT>: records of this type can only be sent by the Web server to the application. Records of
1205             other types can only be sent by the application to the Web server.
1206             <P>
1207             </P>
1208          </LI>
1209          <LI>
1210             <TT>management</TT>: records of this type contain information that is not specific to a Web server request,
1211             and use the null request ID. Records of other types contain request-specific information, and cannot use
1212             the null request ID.
1213             <P>
1214             </P>
1215          </LI>
1216          <LI>
1217             <TT>stream</TT>: records of this type form a stream, terminated by a record with empty
1218             <TT>contentData</TT>. Records of other types are discrete; each carries a meaningful unit of data.<BR>
1219             <BR>
1220          </LI>
1221       </UL>
1222 <PRE>
1223                                WS-&gt;App   management  stream
1224
1225         FCGI_GET_VALUES           x          x
1226         FCGI_GET_VALUES_RESULT               x
1227         FCGI_UNKNOWN_TYPE                    x
1228
1229         FCGI_BEGIN_REQUEST        x
1230         FCGI_ABORT_REQUEST        x
1231         FCGI_END_REQUEST
1232         FCGI_PARAMS               x                    x
1233         FCGI_STDIN                x                    x
1234         FCGI_DATA                 x                    x
1235         FCGI_STDOUT                                    x
1236         FCGI_STDERR                                    x
1237
1238
1239 </PRE>
1240       <P>
1241       </P>
1242       <H3>
1243          <A NAME="SB">B. Typical Protocol Message Flow</A>
1244       </H3>
1245       <P>
1246          Additional notational conventions for the examples:
1247       </P>
1248       <UL>
1249          <LI>
1250             The <TT>contentData</TT> of stream records (<TT>FCGI_PARAMS</TT>, <TT>FCGI_STDIN</TT>,
1251             <TT>FCGI_STDOUT</TT>, and <TT>FCGI_STDERR</TT>) is represented as a character string. A string ending in
1252             <TT>&quot; ... &quot;</TT> is too long to display, so only a prefix is shown.
1253          </LI>
1254          <LI>
1255             Messages sent to the Web server are indented with respect to messages received from the Web server.
1256          </LI>
1257          <LI>
1258             Messages are shown in the time sequence experienced by the application.
1259          </LI>
1260       </UL>
1261       <P>
1262          1. A simple request with no data on <TT>stdin</TT>, and a successful response:
1263       </P>
1264 <PRE>
1265 {FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}
1266 {FCGI_PARAMS,          1, &quot;\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... &quot;}
1267 {FCGI_PARAMS,          1, &quot;&quot;}
1268 {FCGI_STDIN,           1, &quot;&quot;}
1269
1270     {FCGI_STDOUT,      1, &quot;Content-type: text/html\r\n\r\n&lt;html&gt;\n&lt;head&gt; ... &quot;}
1271     {FCGI_STDOUT,      1, &quot;&quot;}
1272     {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
1273 </PRE>
1274       <P>
1275          2. Similar to example 1, but this time with data on <TT>stdin</TT>. The Web server chooses to send the
1276          parameters using more <TT>FCGI_PARAMS</TT> records than before:
1277       </P>
1278 <PRE>
1279 {FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}
1280 {FCGI_PARAMS,          1, &quot;\013\002SERVER_PORT80\013\016SER&quot;}
1281 {FCGI_PARAMS,          1, &quot;VER_ADDR199.170.183.42 ... &quot;}
1282 {FCGI_PARAMS,          1, &quot;&quot;}
1283 {FCGI_STDIN,           1, &quot;quantity=100&amp;item=3047936&quot;}
1284 {FCGI_STDIN,           1, &quot;&quot;}
1285
1286     {FCGI_STDOUT,      1, &quot;Content-type: text/html\r\n\r\n&lt;html&gt;\n&lt;head&gt; ... &quot;}
1287     {FCGI_STDOUT,      1, &quot;&quot;}
1288     {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
1289 </PRE>
1290       <P>
1291          3. Similar to example 1, but this time the application detects an error. The application logs a message to
1292          <TT>stderr</TT>, returns a page to the client, and returns non-zero exit status to the Web server. The
1293          application chooses to send the page using more <TT>FCGI_STDOUT</TT> records:
1294       </P>
1295 <PRE>
1296 {FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, 0}}
1297 {FCGI_PARAMS,          1, &quot;\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... &quot;}
1298 {FCGI_PARAMS,          1, &quot;&quot;}
1299 {FCGI_STDIN,           1, &quot;&quot;}
1300
1301     {FCGI_STDOUT,      1, &quot;Content-type: text/html\r\n\r\n&lt;ht&quot;}
1302     {FCGI_STDERR,      1, &quot;config error: missing SI_UID\n&quot;}
1303     {FCGI_STDOUT,      1, &quot;ml&gt;\n&lt;head&gt; ... &quot;}
1304     {FCGI_STDOUT,      1, &quot;&quot;}
1305     {FCGI_STDERR,      1, &quot;&quot;}
1306     {FCGI_END_REQUEST, 1, {938, FCGI_REQUEST_COMPLETE}}
1307 </PRE>
1308       <P>
1309          4. Two instances of example 1, multiplexed onto a single connection. The first request is more difficult than
1310          the second, so the application finishes the requests out of order:
1311       </P>
1312 <PRE>
1313 {FCGI_BEGIN_REQUEST,   1, {FCGI_RESPONDER, FCGI_KEEP_CONN}}
1314 {FCGI_PARAMS,          1, &quot;\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... &quot;}
1315 {FCGI_PARAMS,          1, &quot;&quot;}
1316 {FCGI_BEGIN_REQUEST,   2, {FCGI_RESPONDER, FCGI_KEEP_CONN}}
1317 {FCGI_PARAMS,          2, &quot;\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... &quot;}
1318 {FCGI_STDIN,           1, &quot;&quot;}
1319
1320     {FCGI_STDOUT,      1, &quot;Content-type: text/html\r\n\r\n&quot;}
1321
1322 {FCGI_PARAMS,          2, &quot;&quot;}
1323 {FCGI_STDIN,           2, &quot;&quot;}
1324
1325     {FCGI_STDOUT,      2, &quot;Content-type: text/html\r\n\r\n&lt;html&gt;\n&lt;head&gt; ... &quot;}
1326     {FCGI_STDOUT,      2, &quot;&quot;}
1327     {FCGI_END_REQUEST, 2, {0, FCGI_REQUEST_COMPLETE}}
1328     {FCGI_STDOUT,      1, &quot;&lt;html&gt;\n&lt;head&gt; ... &quot;}
1329     {FCGI_STDOUT,      1, &quot;&quot;}
1330     {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
1331 </PRE>
1332       <P>
1333       </P>
1334       <HR>
1335       <ADDRESS>
1336          &copy; 1995, 1996 Open Market, Inc. / mbrown@openmarket.com
1337       </ADDRESS>
1338    </BODY>
1339 </HTML>
1340