| 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 <fcgi_stdio.h> |
| 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 <fcgi_stdio.h> |
| 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("FCGI_ROLE") == "FILTER"</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("FCGI_DATA_LENGTH")</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("FCGI_DATA_LAST_MOD").</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() >= 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)) > 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 <fcgi_stdio.h> |
| 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 [email protected] --> |
| 286 |
<!-- --> |
| 287 |
<!-- Last updated: 04/15/96 08:00:20 --> |
| 288 |
</BODY> |
| 289 |
</HTML> |
| 290 |
|