1 <html><head><title>FCGI_Accept(2) Man Page</title></head>
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>
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>
14 <li><code>FCGI_Start_Filter_Data</code>
16 <li><code>FCGI_SetExitStatus</code>
18 <h1> FCGI_Accept (3)</h1>
21 </a><a name="95637"></a>
22 <code>FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream</code> - fcgi_stdio compatibility library<p>
25 </a><pre><a name="95669">
26 #include <fcgi_stdio.h>
29 int <br>FCGI_Accept(void);
32 FILE * <br>FCGI_ToFILE(FCGI_FILE *);
35 FCGI_Stream * <br>FCGI_ToFcgiStream(FCGI_FILE *);
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>
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>
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>
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>
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>
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>
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>
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>
56 <h2> Return Values</h2>
57 </a><a name="95686"></a>
58 0 for successful call, -1 for error (application should exit).<p>
60 <h1> FCGI_StartFilterData (3)</h1>
63 </a><a name="95311"></a>
64 <code>FCGI_StartFilterData</code> -<code>fcgi_stdio</code> compatibility library<p>
67 </a><pre><a name="95313">
68 #include <fcgi_stdio.h>
71 int FCGI_StartFilterData(void)
73 </pre><a name="95315">
75 </a><a name="95728"></a>
76 Enables a FastCGI Filter application to begin reading its filter input data from <code>stdin</code>.<p>
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>
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>
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>
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>
86 <h2> Return Values</h2>
87 </a><a name="95322"></a>
88 Returns 0 on success and a negative integer on failure. <p>
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>
94 while (FCGI_Accept() >= 0) {
100 /* Read data passed by client. */
103 while (getchar () != OF)
115 /* Adjust standard input stream. */
118 status = FCGI_StartFilterData();
124 /* Read in filter data and echo it back to client. */
127 while ((len = fread(tempBuffer, 1, 1024, stdin)) > 0)
130 fwrite(tempBuffer, 1, len, stdout);
136 } /* End FCGI_Accept loop */
138 </pre><a name="95846">
139 <h1> FCGI_SetExitStatus(3)</h1>
142 </a><a name="95794"></a>
143 <code>FCGI_SetExitStatus</code> - <code>fcgi_stdio</code> compatibility library<p>
146 </a><pre><a name="95795">
147 #include <fcgi_stdio.h>
150 void FCGI_SetExitStatus(int status);
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>
157 You can call <code>FCGI_SetExitStatus</code> several times during a request; the last call before the request ends determines the value.<p>
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>
168 <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
170 <!-- For more information on how this document, and how the rest of -->
171 <!-- this server was created, email yourEmail@xyzcorp.com -->
173 <!-- Last updated: 04/15/96 08:00:20 -->