Commit | Line | Data |
6791223e |
1 | <html><head><title>FCGI_Accept(2) Man Page</title></head> |
0198fd3c |
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> |
6791223e |
9 | </a><a name="95882"></a> |
0198fd3c |
10 | This appendix contains reference pages for the following FastCGI routines from the <code>fcgi_stdio</code> library:<p> |
6791223e |
11 | <ul><a name="95884"></a> |
0198fd3c |
12 | <li><code>FCGI_Accept</code> |
6791223e |
13 | <a name="95885"></a> |
0198fd3c |
14 | <li><code>FCGI_Start_Filter_Data</code> |
6791223e |
15 | <a name="95859"></a> |
0198fd3c |
16 | <li><code>FCGI_SetExitStatus</code> |
6791223e |
17 | </ul><a name="95860"> |
0198fd3c |
18 | <h1> FCGI_Accept (3)</h1> |
19 | </a><a name="95861"> |
20 | <h2> Name</h2> |
6791223e |
21 | </a><a name="95637"></a> |
0198fd3c |
22 | <code>FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream</code> - fcgi_stdio compatibility library<p> |
6791223e |
23 | <a name="95652"> |
0198fd3c |
24 | <h2> Synopsis</h2> |
25 | </a><pre><a name="95669"> |
26 | #include <fcgi_stdio.h> |
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> |
6791223e |
39 | </a><a name="95683"></a> |
0198fd3c |
40 | The FCGI_Accept function accepts a new request from the HTTP server and creates a CGI-compatible execution environment for the request.<p> |
6791223e |
41 | <a name="95657"></a> |
0198fd3c |
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> |
6791223e |
43 | <a name="95658"></a> |
0198fd3c |
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> |
6791223e |
45 | <a name="95659"></a> |
0198fd3c |
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> |
6791223e |
47 | <a name="95660"></a> |
0198fd3c |
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> |
6791223e |
49 | <a name="95661"></a> |
0198fd3c |
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> |
6791223e |
51 | <a name="95662"></a> |
0198fd3c |
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> |
6791223e |
53 | <a name="95663"></a> |
0198fd3c |
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> |
6791223e |
55 | <a name="95664"> |
0198fd3c |
56 | <h2> Return Values</h2> |
6791223e |
57 | </a><a name="95686"></a> |
0198fd3c |
58 | 0 for successful call, -1 for error (application should exit).<p> |
6791223e |
59 | <a name="95309"> |
0198fd3c |
60 | <h1> FCGI_StartFilterData (3)</h1> |
61 | </a><a name="95310"> |
62 | <h2> Name</h2> |
6791223e |
63 | </a><a name="95311"></a> |
0198fd3c |
64 | <code>FCGI_StartFilterData</code> -<code>fcgi_stdio</code> compatibility library<p> |
6791223e |
65 | <a name="95312"> |
0198fd3c |
66 | <h2> Synopsis</h2> |
67 | </a><pre><a name="95313"> |
68 | #include <fcgi_stdio.h> |
69 | </a> |
70 | <a name="95314"> |
71 | int FCGI_StartFilterData(void) |
72 | </a> |
73 | </pre><a name="95315"> |
74 | <h2> Description</h2> |
6791223e |
75 | </a><a name="95728"></a> |
0198fd3c |
76 | Enables a FastCGI Filter application to begin reading its filter input data from <code>stdin</code>.<p> |
6791223e |
77 | <a name="95729"></a> |
0198fd3c |
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> |
6791223e |
79 | <a name="95730"></a> |
0198fd3c |
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> |
6791223e |
81 | <a name="95731"></a> |
0198fd3c |
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> |
6791223e |
83 | <a name="95732"></a> |
0198fd3c |
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> |
6791223e |
85 | <a name="95733"> |
0198fd3c |
86 | <h2> Return Values</h2> |
6791223e |
87 | </a><a name="95322"></a> |
0198fd3c |
88 | Returns 0 on success and a negative integer on failure. <p> |
6791223e |
89 | <a name="95323"> |
0198fd3c |
90 | <h2> Example</h2> |
6791223e |
91 | </a><a name="95363"></a> |
0198fd3c |
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> |
6791223e |
93 | <pre><a name="95324"> |
0198fd3c |
94 | while (FCGI_Accept() >= 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)) > 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> |
6791223e |
142 | </a><a name="95794"></a> |
0198fd3c |
143 | <code>FCGI_SetExitStatus</code> - <code>fcgi_stdio</code> compatibility library<p> |
6791223e |
144 | <a name="95786"> |
0198fd3c |
145 | <h2> Synopsis </h2> |
146 | </a><pre><a name="95795"> |
147 | #include <fcgi_stdio.h> |
148 | </a> |
149 | <a name="95787"> |
150 | void FCGI_SetExitStatus(int status); |
151 | </a> |
152 | </pre><a name="95788"> |
153 | <h2> Description </h2> |
6791223e |
154 | </a><a name="95796"></a> |
0198fd3c |
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> |
6791223e |
156 | <a name="95789"></a> |
0198fd3c |
157 | You can call <code>FCGI_SetExitStatus</code> several times during a request; the last call before the request ends determines the value.<p> |
6791223e |
158 | <a name="95797"></a> |
0198fd3c |
159 | <p> |
6791223e |
160 | |
0198fd3c |
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> |