doc/fastcgi-prog-guide/apaman.htm

   1 <html><head><title>FCGI_Accept(2) Man Page</title></head>
   2 <body bgcolor=#ffffff>
   3
   4 <a href="cover.htm">[Top]</a> <a href="ch4tcl.htm">[Prev]</a> <a href="ap_guida.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
   5 <hr><br>
   6
   7 <a name="3601">
   8 <center><h1>A FastCGI <br>Reference Pages</h1></center>
   9 </a><a name="95882"></a>
  10 This appendix contains reference pages for the following FastCGI routines from the <code>fcgi_stdio</code> library:<p>
  11 <ul><a name="95884"></a>
  12 <li><code>FCGI_Accept</code>
  13 <a name="95885"></a>
  14 <li><code>FCGI_Start_Filter_Data</code>
  15 <a name="95859"></a>
  16 <li><code>FCGI_SetExitStatus</code>
  17 </ul><a name="95860">
  18 <h1> FCGI_Accept (3)</h1>
  19 </a><a name="95861">
  20 <h2> Name</h2>
  21 </a><a name="95637"></a>
  22 <code>FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream</code> - fcgi_stdio compatibility library<p>
  23 <a name="95652">
  24 <h2> Synopsis</h2>
  25 </a><pre><a name="95669">
  26 #include &lt;fcgi_stdio.h&gt;
  27 </a>
  28 <a name="95653">
  29 int <br>FCGI_Accept(void);
  30 </a>
  31 <a name="95654">
  32 FILE * <br>FCGI_ToFILE(FCGI_FILE *);
  33 </a>
  34 <a name="95655">
  35 FCGI_Stream * <br>FCGI_ToFcgiStream(FCGI_FILE *);
  36 </a>
  37 </pre><a name="95656">
  38 <h2> Description </h2>
  39 </a><a name="95683"></a>
  40 The FCGI_Accept function accepts a new request from the HTTP server and creates a CGI-compatible execution environment for the request.<p>
  41 <a name="95657"></a>
  42 If the application was invoked as a CGI program, the first call to FCGI_Accept is essentially a no-op and the second call returns -1. This causes a correctly coded FastCGI application to run a single request and exit, giving CGI behavior.<p>
  43 <a name="95658"></a>
  44 If the application was invoked as a FastCGI server, the first call to FCGI_Accept indicates that the application has completed its initialization and is ready to accept its first request. Subsequent calls to FCGI_Accept indicate that the application has completed processing its current request and is ready to accept a new request.<p>
  45 <a name="95659"></a>
  46 In completing the current request, FCGI_Accept may detect errors, such as a broken pipe to a client who has disconnected early. FCGI_Accept ignores such errors. An application that wishes to handle such errors should explicitly call fclose(stderr), then fclose(stdout); an EOF return from either one indicates an error.<p>
  47 <a name="95660"></a>
  48 After accepting a new request, FCGI_Accept assigns new values to the global variables stdin, stdout, stderr, and environ. After FCGI_Accept returns, these variables have the same interpretation as on entry to a CGI program.<p>
  49 <a name="95661"></a>
  50 In addition to the standard CGI environment variables, the environment variable <code>FCGI_ROLE</code> is always set to the role of the current request. The roles currently defined are <code>RESPONDER, AUTHORIZER</code>, and <code>FILTER</code>.<p>
  51 <a name="95662"></a>
  52 In the <code>FILTER</code> role, the additional variables <code>FCGI_DATA_LENGTH</code> and <code>FCGI_DATA_LAST_MOD</code> are also defined. See <code>FCGI_StartFilterData</code><code>(3</code>) for complete information.<p>
  53 <a name="95663"></a>
  54 The macros <code>FCGI_ToFILE</code> and <code>FCGI_ToFcgiStream</code> are provided to allow escape to native functions that use the types <code>FILE</code> or <code>FCGI_Stream</code>. In the case of <code>FILE</code>, functions would have to be separately compiled, since <code>fcgi_stdio.h</code> replaces the standard <code>FILE</code> with <code>FCGI_FILE</code>.<p>
  55 <a name="95664">
  56 <h2> Return Values</h2>
  57 </a><a name="95686"></a>
  58 0 for successful call, -1 for error (application should exit).<p>
  59 <a name="95309">
  60 <h1> FCGI_StartFilterData (3)</h1>
  61 </a><a name="95310">
  62 <h2> Name</h2>
  63 </a><a name="95311"></a>
  64 <code>FCGI_StartFilterData</code> -<code>fcgi_stdio</code> compatibility library<p>
  65 <a name="95312">
  66 <h2> Synopsis</h2>
  67 </a><pre><a name="95313">
  68 #include &lt;fcgi_stdio.h&gt;
  69 </a>
  70 <a name="95314">
  71 int FCGI_StartFilterData(void)
  72 </a>
  73 </pre><a name="95315">
  74 <h2> Description</h2>
  75 </a><a name="95728"></a>
  76 Enables a FastCGI Filter application to begin reading its filter input data from <code>stdin</code>.<p>
  77 <a name="95729"></a>
  78 In order to call <code>FCGI_StartFilterData</code>, the FastCGI application should have been invoked in the filter role (<code>getenv("FCGI_ROLE") == "FILTER"</code>), and should have read <code>stdin</code> to EOF, consuming the entire <code>FCGI_STDIN</code> data stream. The call to <code>FCGI_StartFilterData</code> positions stdin at the start of <code>FCGI_DATA</code>.<p>
  79 <a name="95730"></a>
  80 If the preconditions are not met (e.g., the application has not read <code>stdin</code> to EOF), <code>FCGI_StartFilterData</code> returns a negative result, and the application will get EOF on attempts to read from <code>stdin</code>.<p>
  81 <a name="95731"></a>
  82 The application can determine the number of bytes available on <code>FCGI_DATA</code> by performing <code>atoi(getenv("FCGI_DATA_LENGTH")</code>. If fewer than this many bytes are delivered on <code>stdin</code> after calling <code>FCGI_StartFilterData</code>, the application should perform an application-specific error response. If the application normally makes an update, most likely it should abort the update.<p>
  83 <a name="95732"></a>
  84 The application can determine last modification time of the filter input data by performing <code>getenv("FCGI_DATA_LAST_MOD").</code> This allows applications to perform caching based on last modification time.<p>
  85 <a name="95733">
  86 <h2> Return Values</h2>
  87 </a><a name="95322"></a>
  88 Returns 0 on success and a negative integer on failure. <p>
  89 <a name="95323">
  90 <h2> Example</h2>
  91 </a><a name="95363"></a>
  92 The following example reads in all the client data, but ignores it. Then, the code calls <code>FCGI_StartFilterData</code>. Finally, the code reads in the file to be filtered and simply echos it back to the client. <p>
  93 <pre><a name="95324">
  94 while (FCGI_Accept() &gt;= 0) {
  95 </a>
  96 <a name="95325">
  97 ...
  98 </a>
  99 <a name="95364">
 100  /* Read data passed by client. */
 101 </a>
 102 <a name="95358">
 103   while (getchar () != OF)
 104 </a>
 105 <a name="95935">
 106 {
 107 </a>
 108 <a name="95930">
 109 }
 110 </a>
 111 <a name="95359">
 112
 113 </a>
 114 <a name="95367">
 115  /* Adjust standard input stream. */
 116 </a>
 117 <a name="95366">
 118   status = FCGI_StartFilterData();
 119 </a>
 120 <a name="95369">
 121
 122 </a>
 123 <a name="95360">
 124  /* Read in filter data and echo it back to client. */
 125 </a>
 126 <a name="95368">
 127   while ((len = fread(tempBuffer, 1, 1024, stdin)) &gt; 0)
 128 </a>
 129 <a name="95361">
 130     fwrite(tempBuffer, 1, len, stdout);
 131 </a>
 132 <a name="95844">
 133
 134 </a>
 135 <a name="95845">
 136 } /* End FCGI_Accept loop */
 137 </a>
 138 </pre><a name="95846">
 139 <h1> FCGI_SetExitStatus(3)</h1>
 140 </a><a name="95793">
 141 <h2> Name </h2>
 142 </a><a name="95794"></a>
 143 <code>FCGI_SetExitStatus</code> - <code>fcgi_stdio</code> compatibility library<p>
 144 <a name="95786">
 145 <h2> Synopsis </h2>
 146 </a><pre><a name="95795">
 147 #include &lt;fcgi_stdio.h&gt;
 148 </a>
 149 <a name="95787">
 150 void FCGI_SetExitStatus(int status);
 151 </a>
 152 </pre><a name="95788">
 153 <h2> Description </h2>
 154 </a><a name="95796"></a>
 155 Sets the exit status for the current FastCGI request. The exit status is the status code the request would have exited with, had the request been run as a CGI program.<p>
 156 <a name="95789"></a>
 157 You can call <code>FCGI_SetExitStatus</code> several times during a request; the last call before the request ends determines the value.<p>
 158 <a name="95797"></a>
 159 <p>
 160
 161 <hr><br>
 162
 163 <a href="cover.htm">[Top]</a> <a href="ch4tcl.htm">[Prev]</a> <a href="ap_guida.htm">[Next]</a> <a href="ap_guida.htm">[Bottom]</a>
 164 <hr><br>
 165
 166
 167
 168 <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
 169 <!-- -->
 170 <!-- For more information on how this document, and how the rest of -->
 171 <!-- this server was created, email yourEmail@xyzcorp.com -->
 172 <!-- -->
 173 <!-- Last updated: 04/15/96 08:00:20 -->
 174
 175 </body>
 176 </html>