initial commit
[fcgi] / doc / fastcgi-prog-guide / ch2c.htm
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\r
2 <HTML>\r
3    <HEAD>\r
4       <TITLE>\r
5          FastCGI Programmer&#39;s Guide - Chapter 2, Developing FastCGI Applications in C\r
6       </TITLE>\r
7 <STYLE TYPE="text/css">\r
8  body {\r
9   background-color: #ffffff;\r
10  }\r
11  li.c2 {list-style: none}\r
12  div.c1 {text-align: center}\r
13 </STYLE>\r
14    </HEAD>\r
15    <BODY>\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
18       <HR>\r
19       <BR>\r
20        <A NAME="3659"></A>\r
21       <DIV CLASS="c1">\r
22          <H1>\r
23             2 Developing FastCGI<BR>\r
24             Applications in C\r
25          </H1>\r
26       </DIV>\r
27       <A NAME="917"></A>\r
28       <P>\r
29          This chapter explains how to code FastCGI applications in C and how to build them into executables.\r
30       </P>\r
31       <P>\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
34       </P>\r
35       <BR>\r
36       <BR>\r
37       <H1>\r
38          The I/O Libraries\r
39       </H1>\r
40       <A NAME="5384"></A>\r
41       <P>\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
45          program:\r
46       </P>\r
47       <BR>\r
48       <BR>\r
49       <UL>\r
50          <LI CLASS="c2">\r
51             <A NAME="5386"></A>\r
52          </LI>\r
53          <LI>\r
54             <CODE>fcgi_stdio.h</CODE> <A NAME="4237"></A>\r
55          </LI>\r
56          <LI>\r
57             <CODE>fcgiapp.h</CODE>\r
58          </LI>\r
59       </UL>\r
60       <A NAME="4199"></A>\r
61       <P>\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
65       </P>\r
66       <BR>\r
67       <BR>\r
68       <UL>\r
69          <LI CLASS="c2">\r
70             <A NAME="5811"></A>\r
71          </LI>\r
72          <LI>\r
73             Simplicity: there are only 3 new API calls to learn <A NAME="5828"></A>\r
74          </LI>\r
75          <LI>\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
80          </LI>\r
81          <LI>\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
84          </LI>\r
85       </UL>\r
86       <A NAME="5399"></A>\r
87       <P>\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
91       </P>\r
92       <BR>\r
93       <BR>\r
94       <H1>\r
95          Code Structure\r
96       </H1>\r
97       <A NAME="4240"></A>\r
98       <P>\r
99          To structure code for FastCGI, you separate your code into two sections:\r
100       </P>\r
101       <BR>\r
102       <BR>\r
103       <UL>\r
104          <LI CLASS="c2">\r
105             <A NAME="4200"></A>\r
106          </LI>\r
107          <LI>\r
108             Initialization section, which is executed only once. <A NAME="4201"></A>\r
109          </LI>\r
110          <LI>\r
111             Response loop section, which gets executed every time the FastCGI script gets called.\r
112          </LI>\r
113       </UL>\r
114       <A NAME="4202"></A>\r
115       <P>\r
116          A response loop typically has the following format:\r
117       </P>\r
118       <BR>\r
119       <BR>\r
120 <PRE>\r
121 <A NAME="4203">while (FCGI_Accept() &gt;= 0) {\r
122 </A>\r
123 <A NAME="4204"># body of response loop\r
124 </A>\r
125 <A NAME="4205">}\r
126 </A>\r
127 </PRE>\r
128       <A NAME="4206"></A>\r
129       <P>\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
132       </P>\r
133       <P>\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">&quot;FCGI_Accept\r
136          (3)&quot; on page  21</A> for details.)\r
137       </P>\r
138       <P>\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
142       </P>\r
143       <BR>\r
144       <BR>\r
145       <H1>\r
146          Example 1: TinyFastCGI\r
147       </H1>\r
148       <A NAME="4263">Here is a simple example of a responder FastCGI application written in C:</A><BR>\r
149       <BR>\r
150 <PRE>\r
151 #include &quot;fcgi_stdio.h&quot; /* fcgi library; put it first*/<BR>\r
152 #include &lt;stdlib.h&gt;\r
153 \r
154 int count;\r
155 \r
156 void initialize(void)\r
157 {\r
158   count=0;\r
159 }\r
160 \r
161 void main(void)\r
162 {\r
163 /* Initialization. */  \r
164   initialize();\r
165 \r
166 /* Response loop. */\r
167   while (FCGI_Accept() &gt;= 0)   {\r
168     printf(&quot;Content-type: text/html\r\n&quot;\r
169            &quot;\r\n&quot;\r
170            &quot;&lt;title&gt;FastCGI Hello! (C, fcgi_stdio library)&lt;/title&gt;&quot;\r
171            &quot;&lt;h1&gt;FastCGI Hello! (C, fcgi_stdio library)&lt;/h1&gt;&quot;\r
172            &quot;Request number %d running on host &lt;i&gt;%s&lt;/i&gt;\n&quot;,\r
173             ++count, getenv(&quot;SERVER_HOSTNAME&quot;));\r
174   }\r
175 }\r
176 </PRE>\r
177       <H1>\r
178          Example 2: Prime Number Generator\r
179       </H1>\r
180       <A NAME="4182"></A>\r
181       <P>\r
182          Consider a responder application that generates the n-th prime number.\r
183       </P>\r
184       <P>\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
190       </P>\r
191       <P>\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
196       </P>\r
197       <P>\r
198          <A NAME="4343"></A> Here is the code for the prime number example:\r
199       </P>\r
200       <BR>\r
201       <BR>\r
202 <PRE>\r
203 #include &quot;fcgi_stdio.h&quot;\r
204 #include &lt;stdlib.h&gt;\r
205 #include &lt;string.h&gt;\r
206 \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
211 \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
217 void\r
218 initialize_prime_table(void)\r
219 {\r
220  long int prime_counter=1;\r
221  long int current_prime=2, c, d; \r
222   \r
223   prime_table[prime_counter]=current_prime;\r
224 \r
225   while (current_prime &lt; VALS_IN_SIEVE_TABLE)   {\r
226    /* Mark off composite numbers. */\r
227      for (c = current_prime; c &lt;= VALS_IN_SIEVE_TABLE; \r
228           c += current_prime)  {\r
229         sieve_table[c] = COMPOSITE;  \r
230      }\r
231 \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
236      current_prime=d;\r
237   }\r
238 }\r
239 \r
240 \r
241 void main(void)\r
242 {\r
243     char *query_string;\r
244     long int n;\r
245 \r
246     initialize_prime_table();\r
247 \r
248     while(FCGI_Accept() &gt;= 0) {\r
249         /*\r
250          * Produce the necessary HTTP header.\r
251          */\r
252         printf(&quot;Content-type: text/html\r\n&quot;\r
253                &quot;\r\n&quot;);\r
254         /*\r
255          * Produce the constant part of the HTML document.\r
256          */\r
257         printf(&quot;&lt;title&gt;Prime FastCGI&lt;/title&gt;\n&quot;\r
258                &quot;&lt;h1&gt;Prime FastCGI&lt;/h1&gt;\n&quot;);\r
259         /*\r
260          * Read the query string and produce the variable part\r
261          * of the HTML document.\r
262          */\r
263         query_string = getenv(&quot;QUERY_STRING&quot;);\r
264         if(query_string == NULL) {\r
265             printf(&quot;Usage: Specify a positive number in the query string.\n&quot;);\r
266         } else {\r
267             query_string = strchr(query_string, `=&#39;) + 1;\r
268             n = strtol(query_string);\r
269             if(n &lt; 1) {\r
270                 printf(&quot;The query string `%s&#39; is not a positive number.\n&quot;,\r
271                        query_string);\r
272             } else if(n &gt; MAX_NUMBER_OF_PRIME_NUMBERS) {\r
273                 printf(&quot;The number %d is too large for this program.\n&quot;, n);\r
274             } else\r
275                 printf(&quot;The %ldth prime number is %ld.\n&quot;, n, prime_table[n]);\r
276             }\r
277         }\r
278     } /* while FCGI_Accept */\r
279 }\r
280 </PRE>\r
281       <A NAME="5349"></A>\r
282       <P>\r
283          This application has a noticeable start up cost while it initializes the table, but subsequent accesses are\r
284          fast.\r
285       </P>\r
286       <BR>\r
287       <BR>\r
288       <H1>\r
289          Building\r
290       </H1>\r
291       <A NAME="4630"></A>\r
292       <P>\r
293          This section explains how to build and debug FastCGI applications written in C.\r
294       </P>\r
295       <P>\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
298       </P>\r
299       <BR>\r
300       <BR>\r
301 <PRE>\r
302 <A NAME="4642"><EM>$toolkit</EM>/include/fcgi_stdio.h\r
303 </A>\r
304 </PRE>\r
305       <A NAME="4645"></A>\r
306       <P>\r
307          where <EM>$toolkit</EM> symbolizes the directory in which you have installed the Software Development Kit for\r
308          FastCGI.\r
309       </P>\r
310       <P>\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
313       </P>\r
314       <BR>\r
315       <BR>\r
316 <PRE>\r
317 <A NAME="4647"><EM>$toolkit</EM>/libfcgi/libfcgi.a \r
318 </A>\r
319 </PRE>\r
320       <A NAME="4648"></A>\r
321       <P>\r
322          If your linker does not search the Berkeley socket library, then you must add linker directives to force this\r
323          search.\r
324       </P>\r
325       <P>\r
326          <A NAME="4773"></A> We provide a sample application <CODE>Makefile</CODE> at the following pathname:\r
327       </P>\r
328       <BR>\r
329       <BR>\r
330 <PRE>\r
331 <A NAME="4649"><EM>$toolkit</EM>/examples/Makefile\r
332 </A>\r
333 </PRE>\r
334       <A NAME="4652"></A>\r
335       <P>\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
338       </P>\r
339       <BR>\r
340       <BR>\r
341 <PRE>\r
342 <A NAME="4653">$ ./configure<BR>\r
343 $ make \r
344 </A>\r
345 </PRE>\r
346       <H1>\r
347          Memory Leaks\r
348       </H1>\r
349       <A NAME="4178"></A>\r
350       <P>\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
354       </P>\r
355       <P>\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
358          Systems.\r
359       </P>\r
360       <P>\r
361          <A NAME="4972"></A>\r
362       </P>\r
363       <P>\r
364       </P>\r
365       <HR>\r
366       <BR>\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
369       <HR>\r
370       <BR>\r
371        <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->\r
372       <!-- -->\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
375       <!-- -->\r
376       <!-- Last updated: 04/15/96 08:00:16 -->\r
377    </BODY>\r
378 </HTML>\r
379 \r