doc/fastcgi-prog-guide/apaman.htm

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
   2 <HTML>
   3    <HEAD>
   4       <TITLE>
   5          FCGI_Accept(2) Man Page
   6       </TITLE>
   7 <STYLE TYPE="text/css">
   8  body {
   9   background-color: #ffffff;
  10  }
  11  li.c2 {list-style: none}
  12  div.c1 {text-align: center}
  13 </STYLE>
  14    </HEAD>
  15    <BODY>
  16       <A HREF="cover.htm">[Top]</A> <A HREF="ch4tcl.htm">[Prev]</A> <A HREF="ap_guida.htm">[Next]</A> <A HREF=
  17       "ap_guida.htm">[Bottom]</A>
  18       <HR>
  19       <BR>
  20        <A NAME="3601"></A>
  21       <DIV CLASS="c1">
  22          <H1>
  23             A FastCGI<BR>
  24             Reference Pages
  25          </H1>
  26       </DIV>
  27       <A NAME="95882"></A>
  28       <P>
  29          This appendix contains reference pages for the following FastCGI routines from the <CODE>fcgi_stdio</CODE>
  30          library:
  31       </P>
  32       <BR>
  33       <BR>
  34       <UL>
  35          <LI CLASS="c2">
  36             <A NAME="95884"></A>
  37          </LI>
  38          <LI>
  39             <CODE>FCGI_Accept</CODE> <A NAME="95885"></A>
  40          </LI>
  41          <LI>
  42             <CODE>FCGI_Start_Filter_Data</CODE> <A NAME="95859"></A>
  43          </LI>
  44          <LI>
  45             <CODE>FCGI_SetExitStatus</CODE>
  46          </LI>
  47       </UL>
  48       <H1>
  49          FCGI_Accept (3)
  50       </H1>
  51       <H2>
  52          Name
  53       </H2>
  54       <A NAME="95637"></A> <CODE>FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream</CODE>
  55       <P>
  56          - fcgi_stdio compatibility library
  57       </P>
  58       <BR>
  59       <BR>
  60       <H2>
  61          Synopsis
  62       </H2>
  63 <PRE>
  64 <A NAME="95669">#include &lt;fcgi_stdio.h&gt;
  65 </A>
  66 <A NAME="95653">int<BR>
  67  FCGI_Accept(void);
  68 </A>
  69 <A NAME="95654">FILE *<BR>
  70  FCGI_ToFILE(FCGI_FILE *);
  71 </A>
  72 <A NAME="95655">FCGI_Stream *<BR>
  73  FCGI_ToFcgiStream(FCGI_FILE *);
  74 </A>
  75 </PRE>
  76       <H2>
  77          Description
  78       </H2>
  79       <A NAME="95683"></A>
  80       <P>
  81          The FCGI_Accept function accepts a new request from the HTTP server and creates a CGI-compatible execution
  82          environment for the request.
  83       </P>
  84       <P>
  85          <A NAME="95657"></A> If the application was invoked as a CGI program, the first call to FCGI_Accept is
  86          essentially a no-op and the second call returns -1. This causes a correctly coded FastCGI application to run a
  87          single request and exit, giving CGI behavior.
  88       </P>
  89       <P>
  90          <A NAME="95658"></A> If the application was invoked as a FastCGI server, the first call to FCGI_Accept
  91          indicates that the application has completed its initialization and is ready to accept its first request.
  92          Subsequent calls to FCGI_Accept indicate that the application has completed processing its current request and
  93          is ready to accept a new request.
  94       </P>
  95       <P>
  96          <A NAME="95659"></A> In completing the current request, FCGI_Accept may detect errors, such as a broken pipe
  97          to a client who has disconnected early. FCGI_Accept ignores such errors. An application that wishes to handle
  98          such errors should explicitly call fclose(stderr), then fclose(stdout); an EOF return from either one
  99          indicates an error.
 100       </P>
 101       <P>
 102          <A NAME="95660"></A> After accepting a new request, FCGI_Accept assigns new values to the global variables
 103          stdin, stdout, stderr, and environ. After FCGI_Accept returns, these variables have the same interpretation as
 104          on entry to a CGI program.
 105       </P>
 106       <P>
 107          <A NAME="95661"></A> In addition to the standard CGI environment variables, the environment variable
 108          <CODE>FCGI_ROLE</CODE> is always set to the role of the current request. The roles currently defined are
 109          <CODE>RESPONDER, AUTHORIZER</CODE>, and <CODE>FILTER</CODE>.
 110       </P>
 111       <P>
 112          <A NAME="95662"></A> In the <CODE>FILTER</CODE> role, the additional variables <CODE>FCGI_DATA_LENGTH</CODE>
 113          and <CODE>FCGI_DATA_LAST_MOD</CODE> are also defined. See <CODE>FCGI_StartFilterData</CODE><CODE>(3</CODE>)
 114          for complete information.
 115       </P>
 116       <P>
 117          <A NAME="95663"></A> The macros <CODE>FCGI_ToFILE</CODE> and <CODE>FCGI_ToFcgiStream</CODE> are provided to
 118          allow escape to native functions that use the types <CODE>FILE</CODE> or <CODE>FCGI_Stream</CODE>. In the case
 119          of <CODE>FILE</CODE>, functions would have to be separately compiled, since <CODE>fcgi_stdio.h</CODE> replaces
 120          the standard <CODE>FILE</CODE> with <CODE>FCGI_FILE</CODE>.
 121       </P>
 122       <BR>
 123       <BR>
 124       <H2>
 125          Return Values
 126       </H2>
 127       <A NAME="95686"></A>
 128       <P>
 129          0 for successful call, -1 for error (application should exit).
 130       </P>
 131       <BR>
 132       <BR>
 133       <H1>
 134          FCGI_StartFilterData (3)
 135       </H1>
 136       <H2>
 137          Name
 138       </H2>
 139       <A NAME="95311"></A> <CODE>FCGI_StartFilterData</CODE>
 140       <P>
 141          -<CODE>fcgi_stdio</CODE> compatibility library
 142       </P>
 143       <BR>
 144       <BR>
 145       <H2>
 146          Synopsis
 147       </H2>
 148 <PRE>
 149 <A NAME="95313">#include &lt;fcgi_stdio.h&gt;
 150 </A>
 151 <A NAME="95314">int FCGI_StartFilterData(void)
 152 </A>
 153 </PRE>
 154       <H2>
 155          Description
 156       </H2>
 157       <A NAME="95728"></A>
 158       <P>
 159          Enables a FastCGI Filter application to begin reading its filter input data from <CODE>stdin</CODE>.
 160       </P>
 161       <P>
 162          <A NAME="95729"></A> In order to call <CODE>FCGI_StartFilterData</CODE>, the FastCGI application should have
 163          been invoked in the filter role (<CODE>getenv(&quot;FCGI_ROLE&quot;) == &quot;FILTER&quot;</CODE>), and should
 164          have read <CODE>stdin</CODE> to EOF, consuming the entire <CODE>FCGI_STDIN</CODE> data stream. The call to
 165          <CODE>FCGI_StartFilterData</CODE> positions stdin at the start of <CODE>FCGI_DATA</CODE>.
 166       </P>
 167       <P>
 168          <A NAME="95730"></A> If the preconditions are not met (e.g., the application has not read <CODE>stdin</CODE>
 169          to EOF), <CODE>FCGI_StartFilterData</CODE> returns a negative result, and the application will get EOF on
 170          attempts to read from <CODE>stdin</CODE>.
 171       </P>
 172       <P>
 173          <A NAME="95731"></A> The application can determine the number of bytes available on <CODE>FCGI_DATA</CODE> by
 174          performing <CODE>atoi(getenv(&quot;FCGI_DATA_LENGTH&quot;)</CODE>. If fewer than this many bytes are delivered
 175          on <CODE>stdin</CODE> after calling <CODE>FCGI_StartFilterData</CODE>, the application should perform an
 176          application-specific error response. If the application normally makes an update, most likely it should abort
 177          the update.
 178       </P>
 179       <P>
 180          <A NAME="95732"></A> The application can determine last modification time of the filter input data by
 181          performing <CODE>getenv(&quot;FCGI_DATA_LAST_MOD&quot;).</CODE> This allows applications to perform caching
 182          based on last modification time.
 183       </P>
 184       <BR>
 185       <BR>
 186       <H2>
 187          Return Values
 188       </H2>
 189       <A NAME="95322"></A>
 190       <P>
 191          Returns 0 on success and a negative integer on failure.
 192       </P>
 193       <BR>
 194       <BR>
 195       <H2>
 196          Example
 197       </H2>
 198       <A NAME="95363"></A>
 199       <P>
 200          The following example reads in all the client data, but ignores it. Then, the code calls
 201          <CODE>FCGI_StartFilterData</CODE>. Finally, the code reads in the file to be filtered and simply echos it back
 202          to the client.
 203       </P>
 204       <BR>
 205       <BR>
 206 <PRE>
 207 <A NAME="95324">while (FCGI_Accept() &gt;= 0) {
 208 </A>
 209 <A NAME="95325">...
 210 </A>
 211  <A NAME="95364">/* Read data passed by client. */
 212 </A>
 213  <A NAME="95358"> while (getchar () != OF)
 214 </A>
 215 <A NAME="95935">{
 216 </A>
 217 <A NAME="95930">}
 218 </A>
 219 <A NAME="95359">
 220 </A>
 221  <A NAME="95367">/* Adjust standard input stream. */
 222 </A>
 223  <A NAME="95366"> status = FCGI_StartFilterData();
 224 </A>
 225 <A NAME="95369">
 226 </A>
 227  <A NAME="95360">/* Read in filter data and echo it back to client. */
 228 </A>
 229  <A NAME="95368"> while ((len = fread(tempBuffer, 1, 1024, stdin)) &gt; 0)
 230 </A>
 231  <A NAME="95361">   fwrite(tempBuffer, 1, len, stdout);
 232 </A>
 233 <A NAME="95844">
 234 </A>
 235 <A NAME="95845">} /* End FCGI_Accept loop */
 236 </A>
 237 </PRE>
 238       <H1>
 239          FCGI_SetExitStatus(3)
 240       </H1>
 241       <H2>
 242          Name
 243       </H2>
 244       <A NAME="95794"></A> <CODE>FCGI_SetExitStatus</CODE>
 245       <P>
 246          - <CODE>fcgi_stdio</CODE> compatibility library
 247       </P>
 248       <BR>
 249       <BR>
 250       <H2>
 251          Synopsis
 252       </H2>
 253 <PRE>
 254 <A NAME="95795">#include &lt;fcgi_stdio.h&gt;
 255 </A>
 256 <A NAME="95787">void FCGI_SetExitStatus(int status);
 257 </A>
 258 </PRE>
 259       <H2>
 260          Description
 261       </H2>
 262       <A NAME="95796"></A>
 263       <P>
 264          Sets the exit status for the current FastCGI request. The exit status is the status code the request would
 265          have exited with, had the request been run as a CGI program.
 266       </P>
 267       <P>
 268          <A NAME="95789"></A> You can call <CODE>FCGI_SetExitStatus</CODE> several times during a request; the last
 269          call before the request ends determines the value.
 270       </P>
 271       <P>
 272          <A NAME="95797"></A>
 273       </P>
 274       <P>
 275       </P>
 276       <HR>
 277       <BR>
 278        <A HREF="cover.htm">[Top]</A> <A HREF="ch4tcl.htm">[Prev]</A> <A HREF="ap_guida.htm">[Next]</A> <A HREF=
 279       "ap_guida.htm">[Bottom]</A>
 280       <HR>
 281       <BR>
 282        <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
 283       <!-- -->
 284       <!-- For more information on how this document, and how the rest of -->
 285       <!-- this server was created, email yourEmail@xyzcorp.com -->
 286       <!-- -->
 287       <!-- Last updated: 04/15/96 08:00:20 -->
 288    </BODY>
 289 </HTML>
 290