initial commit
[fcgi] / 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