| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> |
| 2 |
<HTML> |
| 3 |
<HEAD> |
| 4 |
<TITLE> |
| 5 |
FastCGI Programmer's Guide - Chapter 1, The Fast Common Gateway Interface |
| 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="ap_guide.htm">[Prev]</A> <A HREF="ch2c.htm">[Next]</A> <A HREF= |
| 17 |
"ap_guida.htm">[Bottom]</A> |
| 18 |
<HR> |
| 19 |
<BR> |
| 20 |
<A NAME="9432"></A> |
| 21 |
<DIV CLASS="c1"> |
| 22 |
<H1> |
| 23 |
1 The Fast Common<BR> |
| 24 |
Gateway Interface |
| 25 |
</H1> |
| 26 |
</DIV> |
| 27 |
<A NAME="7982"></A> |
| 28 |
<P> |
| 29 |
The Fast Common Gateway Interface (FastCGI) is an enhancement to the existing CGI (Common Gateway Interface), |
| 30 |
which is a standard for interfacing external applications with Web servers. |
| 31 |
</P> |
| 32 |
<P> |
| 33 |
<A NAME="8373"></A> FastCGI is a proposed open standard and we expect both free and commercial Web servers to |
| 34 |
support it. FastCGI is included in Open Market WebServer and Secure WebServer, versions 2.0 and greater. |
| 35 |
</P> |
| 36 |
<BR> |
| 37 |
<BR> |
| 38 |
<H1> |
| 39 |
Advantages of FastCGI |
| 40 |
</H1> |
| 41 |
<A NAME="8369"></A> |
| 42 |
<P> |
| 43 |
FastCGI extends and enhances the CGI model in several ways: |
| 44 |
</P> |
| 45 |
<BR> |
| 46 |
<BR> |
| 47 |
<UL> |
| 48 |
<LI CLASS="c2"> |
| 49 |
<A NAME="7832"></A> |
| 50 |
</LI> |
| 51 |
<LI> |
| 52 |
FastCGI enables applications to persist between client requests, eliminating application start up overhead |
| 53 |
and allowing the application to maintain state between client calls. <A NAME="7995"></A> |
| 54 |
</LI> |
| 55 |
<LI> |
| 56 |
FastCGI enables applications to reside on remote systems (rather than having to reside on the same system |
| 57 |
as the Web server) <A NAME="7997"></A> |
| 58 |
</LI> |
| 59 |
<LI> |
| 60 |
FastCGI enables additional flexibility in application functionality, with explicit support for applications |
| 61 |
that do client authentication and filtering of input. |
| 62 |
</LI> |
| 63 |
</UL> |
| 64 |
<H2> |
| 65 |
Long-lived Applications |
| 66 |
</H2> |
| 67 |
<A NAME="8458"></A> |
| 68 |
<P> |
| 69 |
CGI applications are ephemeral and short-lived: each time a client requests a CGI application, the server asks |
| 70 |
the operating system to spawn a new CGI process. After the CGI process satisfies the request, the server kills |
| 71 |
it. The server spawns and subsequently kills a new process for each client request. |
| 72 |
</P> |
| 73 |
<P> |
| 74 |
<A NAME="8459"></A> FastCGI applications are long-lived, and can persist between client calls. The server |
| 75 |
spawns the FastCGI process once and it continues to run and satisfy client requests until it is explicitly |
| 76 |
terminated. You can also ask the Web server to start multiple copies of a FastCGI application, if you expect |
| 77 |
that concurrent processing will improve the application's performance. |
| 78 |
</P> |
| 79 |
<P> |
| 80 |
<A NAME="5761"></A> Long-lived applications have two important advantages over short-lived applications: |
| 81 |
</P> |
| 82 |
<BR> |
| 83 |
<BR> |
| 84 |
<UL> |
| 85 |
<LI CLASS="c2"> |
| 86 |
<A NAME="7138"></A> |
| 87 |
</LI> |
| 88 |
<LI> |
| 89 |
A short-lived application pays start up overhead on every request; a long-lived application spreads the |
| 90 |
overhead over many requests. For an application that has a heavy start up cost, such as opening a database, |
| 91 |
doing initialization on every call can be very inefficient. Reinitializing for every client is also very |
| 92 |
inefficient for Perl programs, where the interpreter reads through the entire program before executing any |
| 93 |
of it. <A NAME="9204"></A> |
| 94 |
</LI> |
| 95 |
<LI> |
| 96 |
A long-lived application can cache information in memory between requests, allowing it to respond more |
| 97 |
quickly to later requests. |
| 98 |
</LI> |
| 99 |
</UL> |
| 100 |
<A NAME="8733"></A> |
| 101 |
<P> |
| 102 |
FastCGI is not the only way to get a long-lived application on the Web, however. For example, there are many |
| 103 |
existing search engines that are implemented as long-lived applications. |
| 104 |
</P> |
| 105 |
<P> |
| 106 |
<A NAME="8734"></A> In most cases, these applications rely on customized Web servers. In other words, since |
| 107 |
most Web servers do not support long-lived applications, a programmer must code this support into a Web |
| 108 |
server. This approach requires a tremendous amount of work and also ties the application to a particular |
| 109 |
server. |
| 110 |
</P> |
| 111 |
<P> |
| 112 |
<A NAME="8735"></A> Another way to get a long-lived application is to write code that calls routines from the |
| 113 |
Web server's API. This alternative involves a lot of extra coding, ties the application to a particular |
| 114 |
Web server, and introduces problems of maintainability, scalability, and security. |
| 115 |
</P> |
| 116 |
<P> |
| 117 |
<A NAME="8736"></A> We believe that FastCGI is the most general and flexible strategy for building long-lived |
| 118 |
Web applications. |
| 119 |
</P> |
| 120 |
<BR> |
| 121 |
<BR> |
| 122 |
<H2> |
| 123 |
Separating Application and Server |
| 124 |
</H2> |
| 125 |
<A NAME="8446"></A> |
| 126 |
<P> |
| 127 |
CGI applications must run on the same node as the Web server; FastCGI applications can run on any node that |
| 128 |
can be reached from your Web server using TCP/IP protocols. For example, you might want to run the FastCGI |
| 129 |
application on a high-speed computer server or database engine, and run the Web server on a different node. |
| 130 |
</P> |
| 131 |
<BR> |
| 132 |
<BR> |
| 133 |
<H2> |
| 134 |
FastCGI "Roles" |
| 135 |
</H2> |
| 136 |
<A NAME="8777"></A> |
| 137 |
<P> |
| 138 |
CGI and FastCGI applications are effective ways to allow an application to act as an extension to the Web |
| 139 |
server. CGI provides no explicit support for different kinds of applications: under CGI, every application |
| 140 |
receives an HTTP request, does something with it, and generates an HTTP response. FastCGI provides explicit |
| 141 |
support for several common "roles" that applications can play. |
| 142 |
</P> |
| 143 |
<P> |
| 144 |
<A NAME="8769"></A> The three roles supported by the WebServer 2.0 are: |
| 145 |
</P> |
| 146 |
<BR> |
| 147 |
<BR> |
| 148 |
<UL> |
| 149 |
<LI CLASS="c2"> |
| 150 |
<A NAME="8409"></A> |
| 151 |
</LI> |
| 152 |
<LI> |
| 153 |
Responder <A NAME="8410"></A> |
| 154 |
</LI> |
| 155 |
<LI> |
| 156 |
Filter <A NAME="8411"></A> |
| 157 |
</LI> |
| 158 |
<LI> |
| 159 |
Authorizer |
| 160 |
</LI> |
| 161 |
</UL> |
| 162 |
<H3> |
| 163 |
Responder Applications |
| 164 |
</H3> |
| 165 |
<A NAME="8679"></A> |
| 166 |
<P> |
| 167 |
A <EM>responder</EM> application is the most basic kind of FastCGI application: it receives the information |
| 168 |
associated with an HTTP request and generates an HTTP response. Responder is the role most similar to |
| 169 |
traditional CGI programming, and most FastCGI applications are responders. |
| 170 |
</P> |
| 171 |
<BR> |
| 172 |
<BR> |
| 173 |
<H3> |
| 174 |
Filter Applications |
| 175 |
</H3> |
| 176 |
<A NAME="8681"></A> |
| 177 |
<P> |
| 178 |
A <EM>filter</EM> FastCGI application receives the information associated with an HTTP request, plus an extra |
| 179 |
stream of data from a file stored on the Web server, and generates a "filtered" version of the data |
| 180 |
stream as an HTTP response. |
| 181 |
</P> |
| 182 |
<P> |
| 183 |
<A NAME="8421"></A> With filter applications, the system administrator maps a particular MIME-type to a |
| 184 |
particular filter FastCGI application. When a client requests a URL with that MIME-type, the Web server |
| 185 |
invokes the filter application, which processes the file at the specified URL and sends a response (usually |
| 186 |
HTML text) back to the client. |
| 187 |
</P> |
| 188 |
<P> |
| 189 |
<A NAME="8422"></A> For example, suppose you write a filter FastCGI application that converts SGML text to |
| 190 |
HTML, and map the extension .sgml (MIME-type SGML) to your filter FastCGI application. Now, suppose that a |
| 191 |
user requests the following URL: |
| 192 |
</P> |
| 193 |
<BR> |
| 194 |
<BR> |
| 195 |
<PRE> |
| 196 |
<A NAME="8423">/www.aerjug.com/docs/chap1.sgml |
| 197 |
</A> |
| 198 |
</PRE> |
| 199 |
<A NAME="8424"></A> |
| 200 |
<P> |
| 201 |
Given this URL, the Web server passes <CODE>chap1.sgml</CODE> as input to your filter FastCGI application, |
| 202 |
which processes <CODE>chap1.sgml</CODE> and returns an HTML version of it to the requesting client. |
| 203 |
</P> |
| 204 |
<BR> |
| 205 |
<BR> |
| 206 |
<H3> |
| 207 |
Authorizer Applications |
| 208 |
</H3> |
| 209 |
<A NAME="8426"></A> |
| 210 |
<P> |
| 211 |
An <EM>authorizer</EM> FastCGI application receives the information in an HTTP request header and generates a |
| 212 |
decision whether to authorize the request. |
| 213 |
</P> |
| 214 |
<P> |
| 215 |
<A NAME="8428"></A> To mark a FastCGI application as having the authorizer role, the system administrator |
| 216 |
names the application inside the server configuration file, using a directive called |
| 217 |
<CODE>AuthorizeRegion</CODE>. (See the Open Market Web Server manual for information on server configuration |
| 218 |
directives.) |
| 219 |
</P> |
| 220 |
<P> |
| 221 |
<A NAME="8429"></A> When a client requests a URL that meets the <CODE>AuthorizeRegion</CODE> criteria, the Web |
| 222 |
server calls your authorizer FastCGI application. If your application grants authorization (by returning a |
| 223 |
response code of 200), the Web server resumes execution of commands in the <CODE>AuthorizeRegion</CODE> |
| 224 |
section. If your application denies authorization (by returning any other response code), the Web server stops |
| 225 |
processing subsequent commands in the <CODE>AuthorizeRegion</CODE> section, and returns the response from your |
| 226 |
FastCGI application to the client. |
| 227 |
</P> |
| 228 |
<P> |
| 229 |
<A NAME="8431"></A> Authorizer applications can return headers containing environment variables. Other CGI or |
| 230 |
FastCGI programs accessing this request (including other authorizers) can access these environment variables. |
| 231 |
The headers must have the following format: |
| 232 |
</P> |
| 233 |
<BR> |
| 234 |
<BR> |
| 235 |
<PRE> |
| 236 |
<A NAME="8432">Variable-<EM>name</EM>: <EM>value</EM> |
| 237 |
</A> |
| 238 |
</PRE> |
| 239 |
<A NAME="8433"></A> |
| 240 |
<P> |
| 241 |
For example, the following header |
| 242 |
</P> |
| 243 |
<BR> |
| 244 |
<BR> |
| 245 |
<PRE> |
| 246 |
<A NAME="8434">Variable-AUTH_METHOD: database lookup |
| 247 |
</A> |
| 248 |
</PRE> |
| 249 |
<A NAME="8435"></A> |
| 250 |
<P> |
| 251 |
causes the environment variable <CODE>AUTH_METHOD</CODE> to be set to <CODE>"database lookup"</CODE> |
| 252 |
for this request. Other CGI or FastCGI applications running on this request can access the value of |
| 253 |
<CODE>AUTH_METHOD</CODE>. |
| 254 |
</P> |
| 255 |
<P> |
| 256 |
<A NAME="8437"></A> Authorizer applications cannot successfully read from standard input. Any attempts to read |
| 257 |
from standard input result in an immediate EOF. |
| 258 |
</P> |
| 259 |
<P> |
| 260 |
<A NAME="8438"></A> All data that authorizer applications write to standard error will get written to the |
| 261 |
traditional server error logs. |
| 262 |
</P> |
| 263 |
<BR> |
| 264 |
<BR> |
| 265 |
<H1> |
| 266 |
Writing FastCGI Applications |
| 267 |
</H1> |
| 268 |
<A NAME="9301"></A> |
| 269 |
<P> |
| 270 |
The work involved in writing a FastCGI application depends in large part on the I/O libraries that you use. |
| 271 |
This manual describes how to write FastCGI applications in terms of the Open Market libraries, which are |
| 272 |
available for C, Perl, and Tcl. FastCGI is an open standard and you are welcome to build your own libraries |
| 273 |
for other languages as well, but this manual focuses on building FastCGI applications in the context of the |
| 274 |
Open Market libraries. |
| 275 |
</P> |
| 276 |
<P> |
| 277 |
<A NAME="9443"></A> |
| 278 |
</P> |
| 279 |
<P> |
| 280 |
<A NAME="9450"></A> In general, the goal of the libraries is to make the job of writing a FastCGI application |
| 281 |
as much like writing a CGI application as possible. For example, you use the same techniques for query string |
| 282 |
decoding, HTML output to stdout, use of environment variables, and so on. When you use our libraries, porting |
| 283 |
CGI applications to FastCGI is mostly a matter of restructuring the code to take advantage of FastCGI features |
| 284 |
and libraries. |
| 285 |
</P> |
| 286 |
<BR> |
| 287 |
<BR> |
| 288 |
<H2> |
| 289 |
Code Structure |
| 290 |
</H2> |
| 291 |
<A NAME="9470"></A> |
| 292 |
<P> |
| 293 |
The main task of converting a CGI program into a FastCGI program is separating the initialization code from |
| 294 |
the code that needs to run for each request. The structure should look something like this: |
| 295 |
</P> |
| 296 |
<BR> |
| 297 |
<BR> |
| 298 |
<PRE> |
| 299 |
<A NAME="9471">Initialization code |
| 300 |
</A> |
| 301 |
<A NAME="9472">Start of response loop |
| 302 |
</A> |
| 303 |
<A NAME="9473"> body of response loop |
| 304 |
</A> |
| 305 |
<A NAME="9474">End of response loop |
| 306 |
</A> |
| 307 |
</PRE> |
| 308 |
<A NAME="9475"></A> |
| 309 |
<P> |
| 310 |
The <EM>initialization code</EM> is run exactly once, when the application is initialized. Initialization code |
| 311 |
usually performs time-consuming operations such as opening databases or calculating values for tables or |
| 312 |
bitmaps. |
| 313 |
</P> |
| 314 |
<P> |
| 315 |
<A NAME="9477"></A> The <EM>response loop</EM> runs continuously, waiting for client requests to arrive. The |
| 316 |
loop starts with a call to <CODE>FCGI_Accept</CODE>, a routine in the FastCGI library. The |
| 317 |
<CODE>FCGI_Accept</CODE> routine blocks program execution until a client requests the FastCGI application. |
| 318 |
When a client request comes in, <CODE>FCGI_Accept</CODE> unblocks, runs one iteration of the response loop |
| 319 |
body, and then blocks again waiting for another client request. The loop terminates only when the system |
| 320 |
administrator or the Web server kills the FastCGI application. |
| 321 |
</P> |
| 322 |
<BR> |
| 323 |
<BR> |
| 324 |
<H2> |
| 325 |
Initial Environment Variables |
| 326 |
</H2> |
| 327 |
<A NAME="9786"></A> |
| 328 |
<P> |
| 329 |
When a FastCGI process starts up, it has not yet accepted a request, and therefore none of the CGI environment |
| 330 |
variables are set. |
| 331 |
</P> |
| 332 |
<P> |
| 333 |
<A NAME="9787"></A> You set the initial environment of a FastCGI process started by the <CODE>AppClass</CODE> |
| 334 |
directive using the <CODE>-initial-env</CODE> option. The process would use this environment to configure its |
| 335 |
options and locate files or databases. |
| 336 |
</P> |
| 337 |
<P> |
| 338 |
<A NAME="9829"></A> In FastCGI processes started by the <CODE>AppClass</CODE> directive with the -affinity |
| 339 |
option, the <CODE>FCGI_PROCESS_ID</CODE> variable is set in the initial environment (not in the environment of |
| 340 |
a request). <CODE>FCGI_PROCESS_ID</CODE> is a decimal number in the range 0 to N - 1 where N is the number of |
| 341 |
processes (argument to the <CODE>-processes</CODE> option to <CODE>AppClass</CODE>). The process would use |
| 342 |
<CODE>FCGI_PROCESS_ID</CODE> in conjunction with other variables to locate session-related files or databases |
| 343 |
during restart. |
| 344 |
</P> |
| 345 |
<BR> |
| 346 |
<BR> |
| 347 |
<H2> |
| 348 |
Per-Request Environment Variables |
| 349 |
</H2> |
| 350 |
<A NAME="9481"></A> |
| 351 |
<P> |
| 352 |
In general, FastCGI uses the same per-request environment variables as CGI, and you access the values of |
| 353 |
environment variables in FastCGI applications just as you would in CGI applications. The only differences are |
| 354 |
as follows: |
| 355 |
</P> |
| 356 |
<BR> |
| 357 |
<BR> |
| 358 |
<UL> |
| 359 |
<LI CLASS="c2"> |
| 360 |
<A NAME="9483"></A> |
| 361 |
</LI> |
| 362 |
<LI> |
| 363 |
In Authorizer FastCGI applications, the Web server unsets the <CODE>PATH_INFO</CODE>, |
| 364 |
<CODE>PATH_TRANSLATED</CODE>, and <CODE>CONTENT_LENGTH</CODE> variables. <A NAME="9484"></A> |
| 365 |
</LI> |
| 366 |
<LI> |
| 367 |
In Filter FastCGI applications, the Web server sets two additional environment variables: |
| 368 |
<UL> |
| 369 |
<LI CLASS="c2"> |
| 370 |
<A NAME="9486"></A> |
| 371 |
</LI> |
| 372 |
<LI> |
| 373 |
<CODE>FILE_LAST_MOD</CODE>: The Web server sets <CODE>FILE_LAST_MOD</CODE> to the date and time that |
| 374 |
filter input file was last modified. The format is the number of seconds since midnight (UTC), |
| 375 |
January 1, 1970. <A NAME="9488"></A> |
| 376 |
</LI> |
| 377 |
<LI> |
| 378 |
<CODE>FCGI_DATA_LENGTH</CODE>: The application reads at most <CODE>FCGI_DATA_LENGTH</CODE> bytes from |
| 379 |
the data stream before receiving the end-of-stream indication. |
| 380 |
</LI> |
| 381 |
</UL> |
| 382 |
<A NAME="9490"></A> |
| 383 |
</LI> |
| 384 |
<LI> |
| 385 |
FastCGI sets <CODE>FCGI_ROLE</CODE> for each request to <CODE>RESPONDER</CODE>, <CODE>AUTHORIZER</CODE>, or |
| 386 |
<CODE>FILTER</CODE>. |
| 387 |
</LI> |
| 388 |
</UL> |
| 389 |
<H2> |
| 390 |
Building FastCGI Applications in C |
| 391 |
</H2> |
| 392 |
<A NAME="9049"></A> |
| 393 |
<P> |
| 394 |
The Software Development Toolkit that accompanies WebServer 2.0 contains two libraries, fcgi_stdio and |
| 395 |
fcgiapp, for building FastCGI applications in C. |
| 396 |
</P> |
| 397 |
<P> |
| 398 |
<A NAME="9723"></A> The fcgi_stdio library implements our philosophy of making FastCGI applications similar to |
| 399 |
CGI applications, and provides full binary compatibility between FastCGI applications and CGI applications: |
| 400 |
you can run the same C binary as either CGI or FastCGI. |
| 401 |
</P> |
| 402 |
<P> |
| 403 |
<A NAME="9545"></A> The fcgiapp library is more specific to FastCGI, and doesn't attempt the veneer of |
| 404 |
CGI. |
| 405 |
</P> |
| 406 |
<P> |
| 407 |
<A NAME="9731"></A> We recommend that you use the fcgi_stdio library, and this manual describes the routines |
| 408 |
in that library. The documentation for the fcgiapp library is in the code in the development kit. |
| 409 |
</P> |
| 410 |
<BR> |
| 411 |
<BR> |
| 412 |
<H2> |
| 413 |
Building FastCGI Applications in Perl |
| 414 |
</H2> |
| 415 |
<A NAME="9581"></A> |
| 416 |
<P> |
| 417 |
To build FastCGI applications in Perl, you need a FastCGI-savvy version of Perl, plus the FastCGI extension to |
| 418 |
Perl. We build FastCGI-savvy versions of the Perl interpreter for several common platforms and make them |
| 419 |
available on our Website. For details and examples, see Chapter <A HREF="ch3perl.htm#3659">3, "Developing |
| 420 |
FastCGI Applications in Perl," on page 17</A>. |
| 421 |
</P> |
| 422 |
<BR> |
| 423 |
<BR> |
| 424 |
<H2> |
| 425 |
Building FastCGI Applications in Tcl |
| 426 |
</H2> |
| 427 |
<A NAME="9586"></A> |
| 428 |
<P> |
| 429 |
To build FastCGI applications in Tcl, you need a FastCGI-savvy version of Tcl. We build FastCGI-savvy versions |
| 430 |
of the Tcl interpreter for several common platforms and make them available on our Website. For details and |
| 431 |
examples, see Chapter <A HREF="ch4tcl.htm#3659">4, "Developing FastCGI Applications in Tcl," on page |
| 432 |
19</A>. |
| 433 |
</P> |
| 434 |
<BR> |
| 435 |
<BR> |
| 436 |
<H1> |
| 437 |
Implementation Details |
| 438 |
</H1> |
| 439 |
<A NAME="8066"></A> |
| 440 |
<P> |
| 441 |
The FastCGI application libraries are designed to shield you from the details of the FastCGI design. This |
| 442 |
section is designed for the curious reader who would like some low-level understanding. If you are not curious |
| 443 |
about the implementation, you can happily skip this section. |
| 444 |
</P> |
| 445 |
<P> |
| 446 |
<A NAME="8554"></A> As shown in the following figure, CGI applications use the three standard POSIX streams |
| 447 |
(<CODE>stdin</CODE>, <CODE>stdout</CODE>, and <CODE>stderr</CODE>), plus environment variables, to communicate |
| 448 |
with an HTTP server. |
| 449 |
</P> |
| 450 |
<P> |
| 451 |
<A NAME="8359"></A> <IMG ALT="error-file:TidyOut.log" SRC="ch1intra.gif"> |
| 452 |
</P> |
| 453 |
<P> |
| 454 |
<A NAME="4295"></A> |
| 455 |
</P> |
| 456 |
<BR> |
| 457 |
<BR> |
| 458 |
<H5> |
| 459 |
Figure 1: Flow of Data in CGI |
| 460 |
</H5> |
| 461 |
<A NAME="9001"></A> |
| 462 |
<P> |
| 463 |
The fundamental difference between FastCGI and CGI is that FastCGI applications are long-lived, which means |
| 464 |
that the Web Server needs to rendezvous with a running application, rather than starting the application in |
| 465 |
order to explicitly communicate with it. |
| 466 |
</P> |
| 467 |
<P> |
| 468 |
<A NAME="9110"></A> The FastCGI implementation basically creates a bidirectional connection between two |
| 469 |
processes that have no relationship. FastCGI uses a single connection for all the data associated with an |
| 470 |
application -- stdin, stdout, stderr, and environment variables. The data on the connection is encapsulated |
| 471 |
using a FastCGI protocol that allows stdin and the environment variables to share the same half connection (on |
| 472 |
the way in) and stdout and stderr to share the half connection (on the way out). |
| 473 |
</P> |
| 474 |
<P> |
| 475 |
<A NAME="9020"></A> On the input side, the FastCGI application receives data on the connection, unpacks it to |
| 476 |
separate stdin from the environment variables and then invokes the application. On the output side, FastCGI |
| 477 |
wraps stdout and stderr with appropriate protocol headers, and sends the encapsulated data out to the server. |
| 478 |
</P> |
| 479 |
<P> |
| 480 |
<A NAME="9032"></A> Since a FastCGI application does not always run on the same node as the HTTP server, we |
| 481 |
support two implementations of the connection: a <EM>stream pipe</EM><A HREF="#9645"><SUP>1</SUP></A>, for |
| 482 |
communications on the same machine, and TCP streams, for communication when the client and the server are on |
| 483 |
different machines. |
| 484 |
</P> |
| 485 |
<P> |
| 486 |
<A NAME="8576"></A> <IMG ALT="error-file:TidyOut.log" SRC="ch1inta1.gif"> |
| 487 |
</P> |
| 488 |
<BR> |
| 489 |
<BR> |
| 490 |
<H5> |
| 491 |
Figure 2: Flow of Data in FastCGI when server and application are on different machines |
| 492 |
</H5> |
| 493 |
<H2> |
| 494 |
The fcgi_stdio Library: I/O Compatibility |
| 495 |
</H2> |
| 496 |
<A NAME="8977"></A> |
| 497 |
<P> |
| 498 |
The implementation for I/O compatibility is that the library <CODE>fcgi_stdio.h</CODE> contains macros to |
| 499 |
translate the types and procedures defined in stdio.h into the appropriate FastCGI calls. For example, |
| 500 |
consider a FastCGI program written in C containing the following line of code: |
| 501 |
</P> |
| 502 |
<BR> |
| 503 |
<BR> |
| 504 |
<PRE> |
| 505 |
<A NAME="5877">fprintf(stdout, "<H2>Aerobic Juggling</H2>/n"); |
| 506 |
</A> |
| 507 |
</PRE> |
| 508 |
<A NAME="9659"></A> <CODE>fcgi_stdio.h</CODE> |
| 509 |
<P> |
| 510 |
header file contains the macro |
| 511 |
</P> |
| 512 |
<BR> |
| 513 |
<BR> |
| 514 |
<PRE> |
| 515 |
<A NAME="6403">#define fprintf FCGI_fprintf |
| 516 |
</A> |
| 517 |
</PRE> |
| 518 |
<A NAME="6402"></A> |
| 519 |
<P> |
| 520 |
So the preprocessor translates the <CODE>fprintf</CODE> call into the following call: |
| 521 |
</P> |
| 522 |
<BR> |
| 523 |
<BR> |
| 524 |
<PRE> |
| 525 |
<A NAME="6411">FCGI_fprintf(stdout, "<H2>Aerobic Juggling</H2>/n"); |
| 526 |
</A> |
| 527 |
</PRE> |
| 528 |
<A NAME="5888"></A> <CODE>FCGI_fprintf</CODE> |
| 529 |
<P> |
| 530 |
takes the same arguments as <CODE>fprintf</CODE>. |
| 531 |
</P> |
| 532 |
<P> |
| 533 |
<A NAME="9664"></A> The implementation of FCGI_fprintf tests the file to see if it is a normal C stream or a |
| 534 |
FastCGI stream, and calls the appropriate implementation. |
| 535 |
</P> |
| 536 |
<P> |
| 537 |
<A NAME="6463"></A> The <CODE>fcgi_stdio.h</CODE> header file contains macros to translate calls to all ISO |
| 538 |
stdio.h routines (and all conventional Posix additions, such as <CODE>fileno</CODE>, <CODE>fdopen</CODE>, |
| 539 |
<CODE>popen</CODE>, and <CODE>pclose</CODE>) into their FastCGI equivalents. |
| 540 |
</P> |
| 541 |
<BR> |
| 542 |
<BR> |
| 543 |
<H2> |
| 544 |
The fcgi_stdio Library: Binary compatibility |
| 545 |
</H2> |
| 546 |
<A NAME="9579"></A> |
| 547 |
<P> |
| 548 |
The fcgi_stdio library provides full binary compatibility between FastCGI applications and CGI applications: |
| 549 |
you can run the same C binary as either CGI or FastCGI. |
| 550 |
</P> |
| 551 |
<P> |
| 552 |
<A NAME="9580"></A> The implementation is in FCGI_Accept: the FCGI_Accept function tests its environment to |
| 553 |
determine whether the application was invoked as a CGI program or an FastCGI program. If it was invoked as a |
| 554 |
CGI program, the request loop will satisfy a single client request and then exit, producing CGI behavior. |
| 555 |
</P> |
| 556 |
<P> |
| 557 |
<A NAME="8957"></A> |
| 558 |
</P> |
| 559 |
<P> |
| 560 |
</P> |
| 561 |
<HR> |
| 562 |
<BR> |
| 563 |
<A HREF="cover.htm">[Top]</A> <A HREF="ap_guide.htm">[Prev]</A> <A HREF="ch2c.htm">[Next]</A> <A HREF= |
| 564 |
"ap_guida.htm">[Bottom]</A> |
| 565 |
<HR> |
| 566 |
<BR> |
| 567 |
<SUP>1</SUP><A NAME="9645"></A> |
| 568 |
<P> |
| 569 |
UNIX Network Programming, W. Richard Stevens, 1990 Prentice-Hall, Section 7.9 |
| 570 |
</P> |
| 571 |
<P> |
| 572 |
<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 --> |
| 573 |
<!-- --> |
| 574 |
<!-- For more information on how this document, and how the rest of --> |
| 575 |
<!-- this server was created, email [email protected] --> |
| 576 |
<!-- --> |
| 577 |
<!-- Last updated: 04/15/96 08:00:13 --> |
| 578 |
</P> |
| 579 |
</BODY> |
| 580 |
</HTML> |
| 581 |
|