1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
\r
5 FastCGI Programmer's Guide - Chapter 2, Developing FastCGI Applications in C
\r
7 <STYLE TYPE="text/css">
\r
9 background-color: #ffffff;
\r
11 li.c2 {list-style: none}
\r
12 div.c1 {text-align: center}
\r
16 <A HREF="cover.htm">[Top]</A> <A HREF="ch1intro.htm">[Prev]</A> <A HREF="ch3perl.htm">[Next]</A> <A HREF=
\r
17 "ap_guida.htm">[Bottom]</A>
\r
23 2 Developing FastCGI<BR>
\r
29 This chapter explains how to code FastCGI applications in C and how to build them into executables.
\r
32 <A NAME="4230"></A> If you are converting a CGI application into a FastCGI application, in many cases you will
\r
33 only need to add a few lines of code. For more complex applications, you may also need to rearrange some code.
\r
42 The FastCGI Software Development Kit that accompanies Open Market WebServer 2.0 includes I/O libraries to
\r
43 simplify the job of converting existing CGI applications to FastCGI or writing new FastCGI applications. There
\r
44 are two libraries in the kit: fcgi_stdio and fcgiapp. You must include one of these header files in your
\r
54 <CODE>fcgi_stdio.h</CODE> <A NAME="4237"></A>
\r
57 <CODE>fcgiapp.h</CODE>
\r
62 The <CODE>fcgi_stdio</CODE> library is a layer on top of the <CODE>fcgiapp</CODE> library, and we recommend
\r
63 strongly that you use it, both for converting existing CGI applications and for writing new FastCGI
\r
64 applications. The fcgi_stdio library offers several advantages:
\r
73 Simplicity: there are only 3 new API calls to learn <A NAME="5828"></A>
\r
76 Familiarity: If you are converting a CGI application to FastCGI, you will find few changes between CGI and
\r
77 FastCGI. We designed our library to make the job of building a FastCGI application as similar as possible
\r
78 to that of building a FastCGI application: you use the same environment variables, same techniques for
\r
79 parsing query strings, the same I/O routines, and so on. <A NAME="5817"></A>
\r
82 Convenience: the library provides full binary compatibility between CGI and FastCGI. That is, you can run
\r
83 the same binary as either CGI or FastCGI.
\r
88 The fcgiapp library is more specific to FastCGI, without trying to provide the veneer of familiarity with CGI.
\r
89 This manual describes the fcgi_stdio library; the fcgiapp library is documented in the header files that
\r
90 accompany the development kit.
\r
99 To structure code for FastCGI, you separate your code into two sections:
\r
105 <A NAME="4200"></A>
\r
108 Initialization section, which is executed only once. <A NAME="4201"></A>
\r
111 Response loop section, which gets executed every time the FastCGI script gets called.
\r
114 <A NAME="4202"></A>
\r
116 A response loop typically has the following format:
\r
121 <A NAME="4203">while (FCGI_Accept() >= 0) {
\r
123 <A NAME="4204"># body of response loop
\r
128 <A NAME="4206"></A>
\r
130 The <CODE>FCGI_Accept</CODE> blocks until a client request comes in, and then returns 0. If there is a system
\r
131 failure, or the system administrator terminates the process, Accept will return -1.
\r
134 <A NAME="5852"></A> If the application was invoked as a CGI program, the first call to Accept returns 0 and
\r
135 the second always returns -1, producing CGI behavior. (See <A HREF="apaman.htm#95683">"FCGI_Accept
\r
136 (3)" on page 21</A> for details.)
\r
139 <A NAME="5909"></A> Also note that the CGI world encourages small scripts, whereas FastCGI encourages
\r
140 combining scripts. You may choose to rethink the overall structure of your applications to take better
\r
141 advantage of FastCGI performance gains.
\r
146 Example 1: TinyFastCGI
\r
148 <A NAME="4263">Here is a simple example of a responder FastCGI application written in C:</A><BR>
\r
151 #include "fcgi_stdio.h" /* fcgi library; put it first*/<BR>
\r
152 #include <stdlib.h>
\r
156 void initialize(void)
\r
163 /* Initialization. */
\r
166 /* Response loop. */
\r
167 while (FCGI_Accept() >= 0) {
\r
168 printf("Content-type: text/html\r\n"
\r
170 "<title>FastCGI Hello! (C, fcgi_stdio library)</title>"
\r
171 "<h1>FastCGI Hello! (C, fcgi_stdio library)</h1>"
\r
172 "Request number %d running on host <i>%s</i>\n",
\r
173 ++count, getenv("SERVER_HOSTNAME"));
\r
178 Example 2: Prime Number Generator
\r
180 <A NAME="4182"></A>
\r
182 Consider a responder application that generates the n-th prime number.
\r
185 <A NAME="5217"></A> A CGI application would have no efficient way of solving this problem. For example, if the
\r
186 user asks for the 50,000th prime number, a CGI application would have to calculate the first prime number,
\r
187 then the second, and so on, up until the 50,000th. The application would then terminate, taking with it all
\r
188 its hard-earned calculations. If a client then asks for the 49,000th prime number, the server will have to
\r
189 spawn a new CGI application which will have to start calculating prime numbers from scratch.
\r
192 <A NAME="4315"></A> FastCGI applications can be much more efficient at this sort of problem, since they can
\r
193 maintain state. A FastCGI application can calculate an extensive table of prime numbers in its initialization
\r
194 phase and then keep the table around indefinitely. Whenever a client requests a particular prime number, the
\r
195 response loop merely needs to look it up in the table.
\r
198 <A NAME="4343"></A> Here is the code for the prime number example:
\r
203 #include "fcgi_stdio.h"
\r
204 #include <stdlib.h>
\r
205 #include <string.h>
\r
207 #define POTENTIALLY_PRIME 0
\r
208 #define COMPOSITE 1
\r
209 #define VALS_IN_SIEVE_TABLE 1000000
\r
210 #define MAX_NUMBER_OF_PRIME_NUMBERS 78600
\r
212 /* All initialized to POTENTIALLY_PRIME */
\r
213 long int sieve_table[VALS_IN_SIEVE_TABLE];
\r
214 long int prime_table[MAX_NUMBER_OF_PRIME_NUMBERS];
\r
215 /* Use Sieve of Erastothenes method of building
\r
216 a prime number table. */
\r
218 initialize_prime_table(void)
\r
220 long int prime_counter=1;
\r
221 long int current_prime=2, c, d;
\r
223 prime_table[prime_counter]=current_prime;
\r
225 while (current_prime < VALS_IN_SIEVE_TABLE) {
\r
226 /* Mark off composite numbers. */
\r
227 for (c = current_prime; c <= VALS_IN_SIEVE_TABLE;
\r
228 c += current_prime) {
\r
229 sieve_table[c] = COMPOSITE;
\r
232 /* Find the next prime number. */
\r
233 for (d=current_prime+1; sieve_table[d] == COMPOSITE; d++);
\r
234 /* Put the new prime number into the table. */
\r
235 prime_table[++prime_counter]=d;
\r
243 char *query_string;
\r
246 initialize_prime_table();
\r
248 while(FCGI_Accept() >= 0) {
\r
250 * Produce the necessary HTTP header.
\r
252 printf("Content-type: text/html\r\n"
\r
255 * Produce the constant part of the HTML document.
\r
257 printf("<title>Prime FastCGI</title>\n"
\r
258 "<h1>Prime FastCGI</h1>\n");
\r
260 * Read the query string and produce the variable part
\r
261 * of the HTML document.
\r
263 query_string = getenv("QUERY_STRING");
\r
264 if(query_string == NULL) {
\r
265 printf("Usage: Specify a positive number in the query string.\n");
\r
267 query_string = strchr(query_string, `=') + 1;
\r
268 n = strtol(query_string);
\r
270 printf("The query string `%s' is not a positive number.\n",
\r
272 } else if(n > MAX_NUMBER_OF_PRIME_NUMBERS) {
\r
273 printf("The number %d is too large for this program.\n", n);
\r
275 printf("The %ldth prime number is %ld.\n", n, prime_table[n]);
\r
278 } /* while FCGI_Accept */
\r
281 <A NAME="5349"></A>
\r
283 This application has a noticeable start up cost while it initializes the table, but subsequent accesses are
\r
291 <A NAME="4630"></A>
\r
293 This section explains how to build and debug FastCGI applications written in C.
\r
296 <A NAME="4629"></A> The C preprocessor needs to know the location of the <CODE>fcgi_stdio.h</CODE> header
\r
297 file, which is at the following pathname:
\r
302 <A NAME="4642"><EM>$toolkit</EM>/include/fcgi_stdio.h
\r
305 <A NAME="4645"></A>
\r
307 where <EM>$toolkit</EM> symbolizes the directory in which you have installed the Software Development Kit for
\r
311 <A NAME="4760"></A> The linker needs to know the location of the <CODE>libfcgi.a</CODE> library file, which is
\r
312 at the following pathname:
\r
317 <A NAME="4647"><EM>$toolkit</EM>/libfcgi/libfcgi.a
\r
320 <A NAME="4648"></A>
\r
322 If your linker does not search the Berkeley socket library, then you must add linker directives to force this
\r
326 <A NAME="4773"></A> We provide a sample application <CODE>Makefile</CODE> at the following pathname:
\r
331 <A NAME="4649"><EM>$toolkit</EM>/examples/Makefile
\r
334 <A NAME="4652"></A>
\r
336 This <CODE>Makefile</CODE> contains the necessary rules and pathnames to build the C FastCGI applications
\r
337 accompanying the toolkit. To build all the applications, type:
\r
342 <A NAME="4653">$ ./configure<BR>
\r
349 <A NAME="4178"></A>
\r
351 Memory leaks are seldom a problem in CGI programming because CGI applications rarely run long enough to be
\r
352 concerned with leaks. However, memory leaks can become a problem in FastCGI applications, particularly if each
\r
353 call to a popular FastCGI application causes additional memory to leak.
\r
356 <A NAME="4785"></A> When converting to FastCGI, you can either use a tool such as Purify from Pure Software to
\r
357 discover and fix storage leaks or you can run a C garbage collector such as Great Circle from Geodesic
\r
361 <A NAME="4972"></A>
\r
367 <A HREF="cover.htm">[Top]</A> <A HREF="ch1intro.htm">[Prev]</A> <A HREF="ch3perl.htm">[Next]</A> <A HREF=
\r
368 "ap_guida.htm">[Bottom]</A>
\r
371 <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
\r
373 <!-- For more information on how this document, and how the rest of -->
\r
374 <!-- this server was created, email yourEmail@xyzcorp.com -->
\r
376 <!-- Last updated: 04/15/96 08:00:16 -->
\r
projects / catagits/fcgi2.git / blob