Commit | Line | Data |
e88ae2ce |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">\r |
2 | <HTML>\r |
3 | <HEAD>\r |
4 | <TITLE>\r |
5 | FastCGI Developer's Kit\r |
6 | </TITLE>\r |
7 | <STYLE TYPE="text/css">\r |
8 | body {\r |
9 | background-color: #FFFFFF;\r |
10 | color: #000000;\r |
11 | }\r |
12 | :link { color: #cc0000 }\r |
13 | :visited { color: #555555 }\r |
14 | :active { color: #000011 }\r |
15 | h5.c3 {text-align: center}\r |
16 | h3.c2 {text-align: center}\r |
17 | p.c1 {text-align: center}\r |
18 | </STYLE>\r |
19 | </HEAD>\r |
20 | <BODY>\r |
21 | <P CLASS="c1">\r |
22 | <IMG BORDER="0" SRC="../images/fcgi-hd.gif" ALT="[[FastCGI]]"><BR CLEAR="all">\r |
23 | </P>\r |
24 | <H3 CLASS="c2">\r |
25 | FastCGI Developer's Kit\r |
26 | </H3>\r |
27 | <!--Copyright (c) 1996 Open Market, Inc. -->\r |
28 | <!--See the file "LICENSE.TERMS" for information on usage and redistribution-->\r |
29 | <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->\r |
30 | <P CLASS="c1">\r |
31 | Mark R. Brown<BR>\r |
32 | Open Market, Inc.<BR>\r |
33 | </P>\r |
34 | <P CLASS="c1">\r |
35 | Document Version: 1.08<BR>\r |
36 | 11 June 1996<BR>\r |
37 | </P>\r |
38 | <H5 CLASS="c3">\r |
39 | Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.<BR>\r |
40 | Tel: 617-621-9500 Fax: 617-621-1703 URL: <A HREF=\r |
41 | "http://www.openmarket.com/">http://www.openmarket.com/</A><BR>\r |
bb59d4c2 |
42 | $Id: fcgi-devel-kit.htm,v 1.5 2001/11/27 03:06:17 robs Exp $<BR>\r |
e88ae2ce |
43 | </H5>\r |
44 | <HR>\r |
45 | <UL TYPE="square">\r |
46 | <LI>\r |
47 | <A HREF="#S1">1. Introduction</A>\r |
48 | </LI>\r |
49 | <LI>\r |
50 | <A HREF="#S2">2. Getting started</A>\r |
51 | </LI>\r |
52 | <LI>\r |
53 | <A HREF="#S3">3. Writing applications</A> \r |
54 | <UL TYPE="square">\r |
55 | <LI>\r |
56 | <A HREF="#S3.1">3.1 Using the <TT>fcgi_stdio</TT> library</A>\r |
57 | </LI>\r |
58 | <LI>\r |
59 | <A HREF="#S3.2">3.2 Using the <TT>fcgiapp</TT> library</A>\r |
60 | </LI>\r |
61 | <LI>\r |
62 | <A HREF="#S3.3">3.3 Using Perl and Tcl</A>\r |
63 | </LI>\r |
64 | <LI>\r |
65 | <A HREF="#S3.4">3.4 Using Java</A>\r |
66 | </LI>\r |
67 | </UL>\r |
68 | </LI>\r |
69 | <LI>\r |
70 | <A HREF="#S4">4. Running applications</A> \r |
71 | <UL TYPE="square">\r |
72 | <LI>\r |
73 | <A HREF="#S4.1">4.1 Using a Web server that supports FastCGI</A>\r |
74 | </LI>\r |
75 | <LI>\r |
76 | <A HREF="#S4.2">4.2 Using <TT>cgi-fcgi</TT> with any Web server</A>\r |
77 | </LI>\r |
78 | </UL>\r |
79 | </LI>\r |
80 | <LI>\r |
81 | <A HREF="#S5">5. Known problems</A>\r |
82 | </LI>\r |
83 | <LI>\r |
84 | <A HREF="#S6">6. Getting support</A>\r |
85 | </LI>\r |
86 | </UL>\r |
87 | <HR>\r |
88 | <H3>\r |
89 | <A NAME="S1">1. Introduction</A>\r |
90 | </H3>\r |
91 | <P>\r |
92 | FastCGI is an open extension to CGI that provides high performance for all Internet applications without the\r |
93 | penalties of Web server APIs.\r |
94 | </P>\r |
95 | <P>\r |
96 | FastCGI is designed to be layered on top of existing Web server APIs. For instance, the <TT>mod_fastcgi</TT>\r |
97 | Apache module adds FastCGI support to the Apache server. FastCGI can also be used, with reduced functionality\r |
98 | and reduced performance, on any Web server that supports CGI.\r |
99 | </P>\r |
100 | <P>\r |
101 | This FastCGI Developer's Kit is designed to make developing FastCGI applications easy. The kit currently\r |
102 | supports FastCGI applications written in C/C++, Perl, Tcl, and Java.\r |
103 | </P>\r |
104 | <P>\r |
105 | This document:\r |
106 | </P>\r |
107 | <UL TYPE="square">\r |
108 | <LI>\r |
109 | Describes how to configure and build the kit for your development platform.\r |
110 | </LI>\r |
111 | <LI>\r |
112 | Tells how to write applications using the libraries in the kit.\r |
113 | </LI>\r |
114 | <LI>\r |
115 | Tells how to run applications using Web servers that support FastCGI or using any Web server and\r |
116 | <TT>cgi-fcgi</TT>.\r |
117 | </LI>\r |
118 | </UL>\r |
119 | <P>\r |
120 | The kit includes a <A HREF="fastcgi-whitepaper/fastcgi.htm">technical white paper</A>,\r |
121 | <TT>doc/fastcgi-whitepaper/fastcgi.htm</TT>. You should read at least the first three sections of the\r |
122 | technical white paper before starting to write FastCGI applications. The <A HREF="fcgi-perf.htm">performance\r |
123 | paper</A> will help you understand how application design affects performance with FastCGI.\r |
124 | </P>\r |
125 | <P>\r |
126 | The <A HREF="fcgi-spec.html">FastCGI Specification</A>, <TT>doc/fcgi-spec.html</TT>, defines the interface\r |
127 | between a FastCGI application and a Web server that supports FastCGI. The software in the kit implements the\r |
128 | specification. You don't need to read the specification in order to write applications.\r |
129 | </P>\r |
130 | <P>\r |
131 | Additional information is provided in the <A HREF="http://fastcgi.com/docs/faq.html">FAQ</A> document, which\r |
132 | contains frequently asked questions about application development using FastCGI, as well as some general\r |
133 | information.\r |
134 | </P>\r |
135 | <P>\r |
136 | Experience with CGI programming will be extremely valuable in writing FastCGI applications. If you don't\r |
137 | have enough experience with CGI programming, you should read one of the popular books on the topic or study\r |
138 | the <A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">NCSA CGI page</A>. For a more formal treatment of CGI/1.1 see\r |
139 | the <A HREF="http://cgi-spec.golux.com/">Internet Draft CGI 1.1 Specification</A>.\r |
140 | </P>\r |
141 | <H3>\r |
142 | <A NAME="S2">2. Getting started</A>\r |
143 | </H3>\r |
144 | <P>\r |
145 | The kit is a compressed tar (tar.Z) file, distributed via the <A HREF="http://fastcgi.com/">fastcgi.com</A>\r |
146 | Web page. Unpacking the tar file creates a new directory <TT>fcgi-devel-kit</TT>.\r |
147 | </P>\r |
148 | <P>\r |
149 | Open the kit's index page, <TT>fcgi-devel-kit/index.html</TT>, using the "Open File" command in\r |
150 | your Web browser. The index page gives you an overview of the kit structure and helps you navigate the kit.\r |
151 | The index page also contains links that run some example applications, but the applications won't work\r |
152 | when index.html is opened using the "Open File" command because they aren't aren't being\r |
153 | accessed through a Web server.\r |
154 | </P>\r |
155 | <P>\r |
156 | In order to use the kit in earnest you'll need a Web server that you control, a Web server running with\r |
157 | your user ID. The Web server will be starting FastCGI applications that you will need to debug; this will be a\r |
158 | lot more convenient for you if these processes run with your user ID. It is best to have a Web server that\r |
159 | supports FastCGI. <A HREF="#S4">Section 4</A> discusses Web server issues.\r |
160 | </P>\r |
161 | <P>\r |
162 | If you can, keep the kit on a file system accessible from your personal workstation, do your builds on your\r |
163 | workstation, and run your Web server on your workstation. If that's not possible, arrange a configuration\r |
164 | such that the kit is accessible from the machine that's going to run your Web server, and build the kit\r |
165 | and your applications on a machine that's configured exactly the same way (same processor architecture,\r |
166 | operating system, etc.) as the machine that's going to run your Web server.\r |
167 | </P>\r |
168 | <P>\r |
169 | To build the kit you execute this sequence of commands in the <TT>fcgi-devel-kit</TT> directory:\r |
170 | </P>\r |
171 | <PRE>\r |
172 | % ./configure\r |
173 | % make\r |
174 | </PRE>\r |
175 | <P>\r |
176 | We've built and exercised the kit on these platforms (listed in alphabetical order):\r |
177 | </P>\r |
178 | <UL TYPE="square">\r |
179 | <LI>\r |
180 | BSD/OS 1.1 (Intel Pentium), gcc\r |
181 | </LI>\r |
182 | <LI>\r |
183 | Digital UNIX V3.2 148 (Alpha), gcc/cc\r |
184 | </LI>\r |
185 | <LI>\r |
186 | Hewlett-Packard HP-UX A.09.05 C and B.10.01 A (PA-RISC), gcc/cc\r |
187 | </LI>\r |
188 | <LI>\r |
189 | IBM AIX 1 4 (RS/6000), gcc\r |
190 | </LI>\r |
191 | <LI>\r |
192 | Silicon Graphics IRIX 5.3 11091812 (MIPS), gcc\r |
193 | </LI>\r |
194 | <LI>\r |
195 | Sun Solaris 2.4 and 2.5 (SPARC), gcc/cc\r |
196 | </LI>\r |
197 | <LI>\r |
198 | Sun SunOS 4.1.4 (SPARC), gcc\r |
199 | </LI>\r |
200 | </UL>\r |
201 | <P>\r |
202 | Once you've built the kit, follow the directions in <A HREF="#S4">Section 4</A> to bring up your Web\r |
203 | server and run the example applications.\r |
204 | </P>\r |
205 | <H3>\r |
206 | <A NAME="S3">3. Writing applications</A>\r |
207 | </H3>\r |
208 | <H4>\r |
209 | <A NAME="S3.1">3.1 Using the <TT>fcgi_stdio</TT> library</A>\r |
210 | </H4>\r |
211 | <P>\r |
212 | The <TT>fcgi_stdio</TT> library provides the easiest transition for C CGI programs and C CGI programmers to\r |
213 | FastCGI. Using this library your application can run using either CGI or FastCGI, with the same binary for\r |
214 | both situations.\r |
215 | </P>\r |
216 | <P>\r |
217 | To introduce the <TT>fcgi_stdio</TT> library we give a pair of examples: a tiny CGI program and the\r |
218 | translation of this program to FastCGI. These two example programs are included in the kit.\r |
219 | </P>\r |
220 | <P>\r |
221 | The CGI program is <TT>examples/tiny-cgi.c</TT>:\r |
222 | </P>\r |
223 | <PRE>\r |
224 | #include <stdio.h>\r |
225 | #include <stdlib.h>\r |
226 | \r |
227 | void main(void)\r |
228 | {\r |
229 | int count = 0;\r |
230 | printf("Content-type: text/html\r\n"\r |
231 | "\r\n"\r |
232 | "<title>CGI Hello!</title>"\r |
233 | "<h1>CGI Hello!</h1>"\r |
234 | "Request number %d running on host <i>%s</i>\n",\r |
235 | ++count, getenv("SERVER_NAME"));\r |
236 | }\r |
237 | </PRE>\r |
238 | <P>\r |
239 | The key features of this tiny CGI program are:\r |
240 | </P>\r |
241 | <UL TYPE="square">\r |
242 | <LI>\r |
243 | The program sends data to the Web server by writing to <TT>stdout</TT>, using <TT>printf</TT> in this\r |
244 | example. The CGI program first sends a <TT>Content-type</TT> header, then a small HTML document. The\r |
245 | program includes <TT>stdio.h</TT> in order to get access to the <TT>printf</TT> function.\r |
246 | </LI>\r |
247 | <LI>\r |
248 | The program obtains parameters provided by the Web server by reading environment variables. The CGI program\r |
249 | reads the <TT>SERVER_NAME</TT> variable using <TT>getenv</TT> and includes the value in the HTML document.\r |
250 | The program includes <TT>stdlib.h</TT> in order to get access to the <TT>getenv</TT> function.\r |
251 | </LI>\r |
252 | </UL>\r |
253 | <P>\r |
254 | The <TT>count</TT> variable is degenerate in this example; the CGI program runs a single request, so the\r |
255 | request number is always one. This variable will be more interesting in the FastCGI example.\r |
256 | </P>\r |
257 | <P>\r |
258 | <A NAME="S3.1.1">The</A> corresponding FastCGI program is <TT>examples/tiny-fcgi.c</TT>:\r |
259 | </P>\r |
260 | <PRE>\r |
261 | #include "fcgi_stdio.h"\r |
262 | #include <stdlib.h>\r |
263 | \r |
264 | void main(void)\r |
265 | {\r |
266 | int count = 0;\r |
267 | while(FCGI_Accept() >= 0)\r |
268 | printf("Content-type: text/html\r\n"\r |
269 | "\r\n"\r |
270 | "<title>FastCGI Hello!</title>"\r |
271 | "<h1>FastCGI Hello!</h1>"\r |
272 | "Request number %d running on host <i>%s</i>\n",\r |
273 | ++count, getenv("SERVER_NAME"));\r |
274 | }\r |
275 | </PRE>\r |
276 | <P>\r |
277 | The key features of this tiny FastCGI program are:\r |
278 | </P>\r |
279 | <UL TYPE="square">\r |
280 | <LI>\r |
281 | The program is structured as a loop that begins by calling the function <TT>FCGI_Accept</TT>. The\r |
282 | <TT>FCGI_Accept</TT> function blocks until a new request arrives for the program to execute. The program\r |
283 | includes <TT>fcgi_stdio.h</TT> in order to get access to the <TT>FCGI_Accept</TT> function.\r |
284 | </LI>\r |
285 | <LI>\r |
286 | Within the loop, <TT>FCGI_Accept</TT> creates a CGI-compatible world. <TT>printf</TT> and <TT>getenv</TT>\r |
287 | operate just as in the CGI program. <TT>stdin</TT> and <TT>stderr</TT>, not used by this tiny program, also\r |
288 | operate just as in a CGI program.\r |
289 | </LI>\r |
290 | </UL>\r |
291 | <P>\r |
292 | The <TT>count</TT> variable increments each time through the loop, so the program displays a new request\r |
293 | number each time. You can use the reload button in your browser to demonstrate this, once you've got the\r |
294 | program built and running.\r |
295 | </P>\r |
296 | <H4>\r |
297 | Building the program\r |
298 | </H4>\r |
299 | <P>\r |
300 | If you can build <TT>examples/tiny-cgi.c</TT>, it will be straightforward for you to build\r |
301 | <TT>examples/tiny-fcgi.c</TT>. You need to:\r |
302 | </P>\r |
303 | <UL TYPE="square">\r |
304 | <LI>\r |
305 | Add the directory containing the <TT>fcgi_stdio.h</TT> header to the compiler's include search path.\r |
306 | The kit calls this directory <TT>include</TT>.\r |
307 | </LI>\r |
308 | <LI>\r |
309 | Add the library <TT>libfcgi.a</TT> to the linker's command line so that it will be searched when\r |
310 | linking. The <TT>libfcgi.a</TT> library implements the functions defined in <TT>fcgi_stdio.h</TT>. The kit\r |
311 | calls the directory containing this library <TT>libfcgi</TT>.\r |
312 | </LI>\r |
313 | <LI>\r |
314 | Determine whether or not the linker on your platform searches the Berkeley socket library by default, and\r |
315 | if not, add linker directives to force this search.\r |
316 | </LI>\r |
317 | </UL>\r |
318 | <P>\r |
319 | See <TT>examples/Makefile</TT> (created by <TT>configure</TT>) for a Makefile that builds both programs.\r |
320 | Autoconf handles the platform-dependent linking issues; to see how, examine <TT>configure.in</TT> and\r |
321 | <TT>examples/Makefile.in</TT>.\r |
322 | </P>\r |
323 | <H4>\r |
324 | Running the program\r |
325 | </H4>\r |
326 | <P>\r |
327 | <A HREF="#S4">Section 4</A> is all about how to run FastCGI applications.\r |
328 | </P>\r |
329 | <P>\r |
330 | You can use CGI to run application binaries built with the <TT>fcgi_stdio</TT> library. The\r |
331 | <TT>FCGI_Accept</TT> function tests its environment to determine how the application was invoked. If it was\r |
332 | invoked as a CGI program, the first call to FCGI_Accept is essentially a no-op and the second call returns\r |
333 | <TT>-1</TT>. In effect, the request loop disappears.\r |
334 | </P>\r |
335 | <P>\r |
336 | Of course, when a FastCGI application is run using CGI it does not get the benefits of FastCGI. For instance,\r |
337 | the application exits after servicing a single request, so it cannot maintain cached information.\r |
338 | </P>\r |
339 | <H4>\r |
340 | Implementation details\r |
341 | </H4>\r |
342 | <P>\r |
343 | <TT>fcgi_stdio.h</TT> works by first including <TT>stdio.h</TT>, then defining macros to replace essentially\r |
344 | all of the types and procedures defined in <TT>stdio.h</TT>. (<TT>stdio.h</TT> defines a few procedures that\r |
345 | have nothing to do with <TT>FILE *</TT>, such as <TT>sprintf</TT> and <TT>sscanf</TT>; <TT>fcgi_stdio.h</TT>\r |
346 | doesn't replace these.) For instance, <TT>FILE</TT> becomes <TT>FCGI_FILE</TT> and <TT>printf</TT> becomes\r |
347 | <TT>FCGI_printf</TT>. You'll only see these new names if you read <TT>fcgi_stdio.h</TT> or examine your C\r |
348 | source code after preprocessing.\r |
349 | </P>\r |
350 | <P>\r |
351 | Here are some consequences of this implementation technique:\r |
352 | </P>\r |
353 | <UL TYPE="square">\r |
354 | <LI>\r |
355 | On some platforms the implementation will break if you include <TT>stdio.h</TT> after including\r |
356 | <TT>fcgi_stdio.h</TT>, because <TT>stdio.h</TT> often defines macros for functions such as <TT>getc</TT>\r |
357 | and <TT>putc</TT>. Fortunately, on most platforms <TT>stdio.h</TT> is protected against multiple includes\r |
358 | by lines near the top of the file that look like \r |
359 | <PRE>\r |
360 | #ifndef _STDIO_H\r |
361 | #define _STDIO_H\r |
362 | \r |
363 | </PRE>\r |
364 | <P>\r |
365 | The specific symbol used for multiple-include protection, <TT>_STDIO_H</TT> in this example, varies from\r |
366 | platform to platform. As long as your platform protects <TT>stdio.h</TT> against multiple includes, you\r |
367 | can forget about this issue.\r |
368 | </P>\r |
369 | </LI>\r |
370 | <LI>\r |
371 | If your application passes <TT>FILE *</TT> to functions implemented in libraries for which you have source\r |
372 | code, then you'll want to recompile these libraries with <TT>fcgi_stdio.h</TT> included. Most C\r |
373 | compilers provide a command-line option for including headers in a program being compiled; using such a\r |
374 | compiler feature allows you to rebuild your libraries without making source changes. For instance the gcc\r |
375 | command line \r |
376 | <PRE>\r |
377 | gcc -include /usr/local/include/fcgi_stdio.h wonderlib.c\r |
378 | \r |
379 | </PRE>\r |
380 | <P>\r |
381 | causes gcc to include <TT>fcgi_stdio.h</TT> before it even begins to read the module\r |
382 | <TT>wonderlib.c</TT>.\r |
383 | </P>\r |
384 | </LI>\r |
385 | <LI>\r |
386 | If your application passes <TT>FILE *</TT> to functions implemented in libraries for which you do not have\r |
387 | source code, then you'll need to include the headers for these libraries <I>before</I> you include\r |
388 | <TT>fcgi_stdio.h</TT>. You can't pass the <TT>stdin</TT>, <TT>stdout</TT>, or <TT>stderr</TT> streams\r |
389 | produced by <TT>FCGI_Accept</TT> to any functions implemented by these libraries. You can pass a stream on\r |
390 | a Unix file to a library function by following this pattern: \r |
391 | <PRE>\r |
392 | FILE *myStream = fopen(path, "r");\r |
393 | answer = MungeStream(FCGI_ToFile(myStream));\r |
394 | \r |
395 | </PRE>\r |
396 | <P>\r |
397 | Here <TT>MungeStream</TT> is a library function that you can't recompile and <TT>FCGI_ToFile</TT> is\r |
398 | a macro that converts from <TT>FCGI_FILE *</TT> to <TT>FILE *</TT>. The macro <TT>FCGI_ToFile</TT> is\r |
399 | defined in <TT>fcgi_stdio.h</TT>.\r |
400 | </P>\r |
401 | </LI>\r |
402 | </UL>\r |
403 | <H4>\r |
404 | Converting CGI programs\r |
405 | </H4>\r |
406 | <P>\r |
407 | The main task in converting a CGI program into a FastCGI program is separating the code that needs to execute\r |
408 | once, initializing the program, from the code that needs to run for each request. In our tiny example,\r |
409 | initializing the <TT>count</TT> variable is outside the loop, while incrementing the <TT>count</TT> variable\r |
410 | goes inside.\r |
411 | </P>\r |
412 | <P>\r |
413 | Retained application state may be an issue. You must ensure that any application state created in processing\r |
414 | one request has no unintended effects on later requests. FastCGI offers the possibility of significant\r |
415 | application performance improvements, through caching; it is up to you to make the caches work correctly.\r |
416 | </P>\r |
417 | <P>\r |
418 | Storage leaks may be an issue. Many CGI programs don't worry about storage leaks because the programs\r |
419 | don't run for long enough for bloating to be a problem. When converting to FastCGI, you can either use a\r |
420 | tool such as <A HREF="http://www.pure.com/"><I>Purify</I></A> from Pure Software to discover and fix storage\r |
421 | leaks, or you can run a C garbage collector such as <A HREF="http://www.geodesic.com/"><I>Great Circle</I></A>\r |
422 | from Geodesic Systems.\r |
423 | </P>\r |
424 | <H4>\r |
425 | Limitations\r |
426 | </H4>\r |
427 | <P>\r |
428 | Currently there are some limits to the compatibility provided by the <TT>fcgi_stdio</TT> library:\r |
429 | </P>\r |
430 | <UL TYPE="square">\r |
431 | <LI>\r |
432 | The library does not provide FastCGI versions of the functions <TT>fscanf</TT> and <TT>scanf</TT>. If you\r |
433 | wish to apply <TT>fscanf</TT> or <TT>scanf</TT> to <TT>stdin</TT> of a FastCGI program, the workaround is\r |
434 | to read lines or other natural units into memory and then call <TT>sscanf</TT>. If you wish to apply\r |
435 | <TT>fscanf</TT> to a stream on a Unix file, the workaround is to follow the pattern: \r |
436 | <PRE>\r |
437 | FILE *myStream = fopen(path, "r");\r |
438 | count = fscanf(FCGI_ToFile(myStream), format, ...);\r |
439 | \r |
440 | </PRE>\r |
441 | </LI>\r |
442 | </UL>\r |
443 | <H4>\r |
444 | Reference documentation\r |
445 | </H4>\r |
446 | <P>\r |
447 | The <A HREF="FCGI_Accept.3"><TT>FCGI_Accept</TT> manpage</A>, <TT>doc/FCGI_Accept.3</TT>, describes the\r |
448 | function in the traditional format.\r |
449 | </P>\r |
450 | <P>\r |
451 | The <A HREF="FCGI_Finish.3"><TT>FCGI_Finish</TT></A> (<TT>doc/FCGI_Finish.3</TT>), <A HREF=\r |
452 | "FCGI_SetExitStatus.3"><TT>FCGI_SetExitStatus</TT></A> (<TT>doc/FCGI_SetExitStatus.3</TT>), and <A HREF=\r |
453 | "FCGI_StartFilterData.3"><TT>FCGI_StartFilterData</TT></A> (<TT>doc/FCGI_StartFilterData.3</TT>) manpages\r |
454 | document capabilities of the <TT>fcgi-stdio</TT> library that are not illustrated above.\r |
455 | </P>\r |
456 | <H4>\r |
457 | <A NAME="S3.2">3.2 Using the <TT>fcgiapp</TT> library</A>\r |
458 | </H4>\r |
459 | <P>\r |
460 | The <TT>fcgiapp</TT> library is a second C library for FastCGI. It does not provide the high degree of source\r |
461 | code compatibility provided by <TT>fcgi_stdio</TT>; in return, it does not make such heavy use of\r |
462 | <TT>#define</TT>. <TT>fcgi_stdio</TT> is implemented as a thin layer on top of <TT>fcgiapp</TT>.\r |
463 | </P>\r |
464 | <P>\r |
465 | Applications built using the <TT>fcgiapp</TT> library cannot run as CGI programs; that feature is provided at\r |
466 | the <TT>fcgi_stdio</TT> level.\r |
467 | </P>\r |
468 | <P>\r |
469 | Functions defined in <TT>fcgiapp</TT> are named using the prefix <TT>FCGX_</TT> rather than <TT>FCGI_</TT>.\r |
470 | For instance, <TT>FCGX_Accept</TT> is the <TT>fcgiapp</TT> version of <TT>FCGI_Accept</TT>.\r |
471 | </P>\r |
472 | <P>\r |
473 | Documentation of the <TT>fcgiapp</TT> library takes the form of extensive comments in the header file\r |
474 | <TT>include/fcgiapp.h</TT>. The sample programs <TT>examples/tiny-fcgi2.c</TT> and <TT>examples/echo2.c</TT>\r |
475 | illustrate how to use <TT>fcgiapp</TT>.\r |
476 | </P>\r |
477 | <H4>\r |
478 | <A NAME="S3.3">3.3 Using Perl and Tcl</A>\r |
479 | </H4>\r |
480 | <P>\r |
481 | A major advantage of the FastCGI approach to high-performance Web applications is its language-neutrality. CGI\r |
482 | scripts written in popular languages such as Perl and Tcl can be evolved into high-performance FastCGI\r |
483 | applications.\r |
484 | </P>\r |
485 | <P>\r |
486 | We have produced FastCGI-integrated Perl and Tcl interpreters. Doing so was easy, since Perl and Tcl are\r |
487 | conventional C applications and <TT>fcgi_stdio</TT> was designed for converting conventional C applications.\r |
488 | Essentially no source code changes were required in these programs; a small amount of code was added in order\r |
489 | to make <TT>FCGI_Accept</TT> and other FastCGI primitives available in these languages. And because these\r |
490 | interpreters were developed using <TT>fcgi_stdio</TT>, they run standard Perl and Tcl applications (e.g. CGI\r |
491 | scripts) as well as FastCGI applications.\r |
492 | </P>\r |
493 | <P>\r |
494 | See the <A HREF="http://fastcgi.com">fastcgi.com</A> Web page for more information about the Perl and Tcl\r |
495 | libraries.\r |
496 | </P>\r |
497 | <P>\r |
498 | Here are the Perl and Tcl versions of <TT>tiny-fcgi</TT>:\r |
499 | </P>\r |
500 | <PRE>\r |
501 | #!./perl\r |
502 | use FCGI;\r |
503 | $count = 0;\r |
504 | while(FCGI::accept() >= 0) {\r |
505 | print("Content-type: text/html\r\n\r\n",\r |
506 | "<title>FastCGI Hello! (Perl)</title>\n",\r |
507 | "<h1>FastCGI Hello! (Perl)</h1>\n";\r |
508 | "Request number ", ++$count,\r |
509 | " running on host <i>";$env(SERVER_NAME)</i>");\r |
510 | }\r |
511 | </PRE>\r |
512 | <PRE>\r |
513 | #!./tclsh\r |
514 | set count 0 \r |
515 | while {[FCGI_Accept] >= 0 } {\r |
516 | incr count\r |
517 | puts -nonewline "Content-type: text/html\r\n\r\n"\r |
518 | puts "<title>FastCGI Hello! (Tcl)</title>"\r |
519 | puts "<h1>FastCGI Hello! (Tcl)</h1>"\r |
520 | puts "Request number $count running on host <i>$env(SERVER_NAME)</i>"\r |
521 | }\r |
522 | </PRE>\r |
523 | <P>\r |
524 | Converting a Perl or Tcl CGI application to FastCGI is not fundamentally different from converting a C CGI\r |
525 | application to FastCGI. You separate the portion of the application that performs one-time initialization from\r |
526 | the portion that performs per-request processing. You put the per-request processing into a loop controlled by\r |
527 | <TT>FCGI::accept</TT> (Perl) or <TT>FCGI_Accept</TT> (Tcl).\r |
528 | </P>\r |
529 | <H4>\r |
530 | <A NAME="S3.4">3.4 Using Java</A>\r |
531 | </H4>\r |
532 | <P>\r |
533 | Java is not just for browser-based applets. It is already suitable for writing some Web server applications,\r |
534 | and its range of applicability will only grow as Java compilers and other Java tools improve. Java's\r |
535 | modules, garbage collection, and threads are especially valuable for writing long-lived application servers.\r |
536 | </P>\r |
537 | <P>\r |
538 | The <TT>FCGIInterface</TT> class provides facilities for Java applications analogous to what\r |
539 | <TT>fcgi_stdio</TT> provides for C applications. Using this library your Java application can run using either\r |
540 | CGI or FastCGI.\r |
541 | </P>\r |
542 | <P>\r |
543 | The kit includes separate companion document on <A HREF="fcgi-java.htm">using FastCGI with Java</A>. The\r |
544 | source code for FastCGI classes is contained in directory <TT>java/src</TT> and the compiled code in\r |
545 | <TT>java/classes</TT>.\r |
546 | </P>\r |
547 | <P>\r |
548 | Here is the Java version of <TT>tiny-fcgi</TT>:\r |
549 | </P>\r |
550 | <PRE>\r |
551 | import FCGIInterface;\r |
552 | \r |
553 | class TinyFCGI { \r |
554 | public static void main (String args[]) { \r |
555 | int count = 0;\r |
556 | while(new FCGIInterface().FCGIaccept()>= 0) {\r |
557 | count ++;\r |
558 | System.out.println("Content-type: text/html\r\n\r\n");\r |
559 | System.out.println(\r |
560 | "<title>FastCGI Hello! (Java)</title>");\r |
561 | System.out.println("<h1>FastCGI Hello! (Java)</h1>");\r |
562 | System.out.println(\r |
563 | "request number " + count + " running on host <i>" +\r |
564 | System.getProperty("SERVER_NAME") + "</i>");\r |
565 | }\r |
566 | }\r |
567 | }\r |
568 | </PRE>\r |
569 | <H3>\r |
570 | <A NAME="S4">4. Running applications</A>\r |
571 | </H3>\r |
572 | <H3>\r |
573 | <A NAME="S4.1">4.1 Using a Web server that supports FastCGI</A>\r |
574 | </H3>\r |
575 | <P>\r |
576 | For a current listing of Web servers that support FastCGI, see the <A HREF=\r |
577 | "http://fastcgi.com">fastcgi.com</A> Web page.\r |
578 | </P>\r |
579 | <P>\r |
580 | Some of the Web servers that support FastCGI perform management of FastCGI applications. You don't need to\r |
581 | start and stop FastCGI applications; the Web server takes care of this. If an application process should\r |
582 | crash, the Web server restarts it.\r |
583 | </P>\r |
584 | <P>\r |
585 | Web servers support FastCGI via new configuration directives. Since these directives are server-specific, get\r |
586 | more information from the documentation that accompanies each server.\r |
587 | </P>\r |
588 | <H3>\r |
589 | <A NAME="S4.2">4.2 Using <TT>cgi-fcgi</TT> with any Web server</A>\r |
590 | </H3>\r |
591 | <P>\r |
592 | The program <TT>cgi-fcgi</TT> allows you to run FastCGI applications using any Web server that supports CGI.\r |
593 | </P>\r |
594 | <P>\r |
595 | Here is how <TT>cgi-fcgi</TT> works. <TT>cgi-fcgi</TT> is a standard CGI program that uses Unix domain or\r |
596 | TCP/IP sockets to communicate with a FastCGI application. <TT>cgi-fcgi</TT> takes the path name or host/port\r |
597 | name of a listening socket as a parameter and <TT>connect</TT>s to the FastCGI application listening on that\r |
598 | socket. <TT>cgi-fcgi</TT> then forwards the CGI environment variables and <TT>stdin</TT> data to the FastCGI\r |
599 | application, and forwards the <TT>stdout</TT> and <TT>stderr</TT> data from the FastCGI application to the Web\r |
600 | server. When the FastCGI application signals the end of its response, <TT>cgi-fcgi</TT> flushes its buffers\r |
601 | and exits.\r |
602 | </P>\r |
603 | <P>\r |
604 | Obviously, having <TT>cgi-fcgi</TT> is not as good as having a server with integrated FastCGI support:\r |
605 | </P>\r |
606 | <UL>\r |
607 | <LI>\r |
608 | Communication is slower than with a Web server that avoids the fork/exec overhead on every FastCGI request.\r |
609 | </LI>\r |
610 | <LI>\r |
611 | <TT>cgi-fcgi</TT> does not perform application management, so you need to provide this yourself.\r |
612 | </LI>\r |
613 | <LI>\r |
614 | <TT>cgi-fcgi</TT> supports only the Responder role.\r |
615 | </LI>\r |
616 | </UL>\r |
617 | <P>\r |
618 | But <TT>cgi-fcgi</TT> does allow you to develop applications that retain state in memory between connections,\r |
619 | which often provides a major performance boost over normal CGI. And all the applications you develop using\r |
620 | <TT>cgi-fcgi</TT> will work with Web servers that have integrated support for FastCGI.\r |
621 | </P>\r |
622 | <P>\r |
623 | The file <TT>examples/tiny-fcgi.cgi</TT> demonstrates a way to use <TT>cgi-fcgi</TT> to run a typical\r |
624 | application, in this case the <TT>examples/tiny-fcgi</TT> application:\r |
625 | </P>\r |
626 | <PRE>\r |
627 | #!../cgi-fcgi/cgi-fcgi -f\r |
628 | -connect sockets/tiny-fcgi tiny-fcgi\r |
629 | </PRE>\r |
630 | <P>\r |
631 | On most Unix platforms, executing this command-interpreter file runs <TT>cgi-fcgi</TT> with arguments\r |
632 | <TT>-f</TT> and <TT>examples/tiny-fcgi.cgi</TT>. (Beware: On some Unix platforms, including HP-UX, the first\r |
633 | line of a command-interpreter file cannot contain more than 32 characters, including the newline; you may need\r |
634 | to install the <TT>cgi-fcgi</TT> application in a standard place like <TT>/usr/local/bin</TT> or create a\r |
635 | symbolic link to the <TT>cgi-fcgi</TT> application in the directory containing your application.) The\r |
636 | <TT>cgi-fcgi</TT> program reads the command-interpreter file and connects to the FastCGI application whose\r |
637 | listening socket is <TT>examples/sockets/tiny-fcgi</TT>.\r |
638 | </P>\r |
639 | <P>\r |
640 | Continuing the example, if <TT>cgi-fcgi</TT>'s connection attempt fails, it creates a new process running\r |
641 | the program <TT>examples/tiny-fcgi</TT> and listening on socket <TT>examples/sockets/tiny-fcgi</TT>. Then\r |
642 | <TT>cgi-fcgi</TT> retries the connection attempt, which now should succeed.\r |
643 | </P>\r |
644 | <P>\r |
645 | The <TT>cgi-fcgi</TT> program has two other modes of operation. In one mode it connects to applications but\r |
646 | does not start them; in the other it starts applications but does not connect to them. These modes are\r |
647 | required when using TCP/IP. The <A HREF="cgi-fcgi.1"><TT>cgi-fcgi</TT> manpage</A>, <TT>doc/cgi-fcgi.1</TT>,\r |
648 | tells the full story.\r |
649 | </P>\r |
650 | <P>\r |
651 | To run the example applications using <TT>cgi-fcgi</TT>, start your Web server and give it the directory\r |
652 | <TT>fcgi-devel-kit</TT> as the root of its URL space. If the machine running your server is called\r |
653 | <TT>bowser</TT> and your server is running on port <TT>8888</TT>, you'd then open the URL\r |
654 | <TT>http://bowser:8888/index.html</TT> to reach the kit's index page. Now the links on the index page that\r |
655 | run example applications via <TT>cgi-fcgi</TT> should be active.\r |
656 | </P>\r |
657 | <H3>\r |
658 | <A NAME="S5">5. Known problems</A>\r |
659 | </H3>\r |
660 | <P>\r |
661 | On Digital UNIX 3.0 there's a problem with Unix domain listening sockets on NFS file systems. The symptom\r |
662 | when using cgi-fcgi is an exit status of 38 (<TT>ENOTSOCK</TT>: socket operation on non-socket), but cgi-fcgi\r |
663 | may dump core in this case when compiled optimized. Work-around: Store your Unix domain listening sockets on a\r |
664 | non NFS file system, upgrade to Digital UNIX 3.2, or use TCP sockets.\r |
665 | </P>\r |
666 | <P>\r |
667 | On AIX there's a problem with shared listening sockets. The symptoms can include application core dumps\r |
668 | and kernel panic. Work-around: Run a single FastCGI application server per listening socket.\r |
669 | </P>\r |
670 | <H3>\r |
671 | <A NAME="S6">6. Getting support</A>\r |
672 | </H3>\r |
673 | <P>\r |
bb59d4c2 |
674 | The mailing list <TT>fastcgi-developers</TT> is used for discussions of issues in developing FastCGI\r |
e88ae2ce |
675 | applications. Topics include announcement of FastCGI-capable Web servers or changes to such servers,\r |
676 | announcement of new application libraries or changes to such libraries, announcement of known bugs, discussion\r |
677 | of design trade-offs in FastCGI application programming, and discussion of development plans and experiences.\r |
bb59d4c2 |
678 | To join the list, see <A HREF=\r |
679 | "http://fastcgi.com/fastcgi-developers">http://fastcgi.com/fastcgi-developers</A>.\r |
e88ae2ce |
680 | </P>\r |
681 | <P>\r |
682 | A link to a mail archive can be found on the FastCGI home page, <A HREF=\r |
683 | "http://www.fastcgi.com">http://www.fastcgi.com</A>\r |
684 | </P>\r |
685 | <HR>\r |
686 | <ADDRESS>\r |
687 | © 1996, Open Market, Inc. / mbrown@openmarket.com\r |
688 | </ADDRESS>\r |
689 | </BODY>\r |
690 | </HTML>\r |
691 | \r |