Commit | Line | Data |
0198fd3c |
1 | NAME |
2 | FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream |
3 | - fcgi_stdio compatibility library |
4 | |
5 | SYNOPSIS |
6 | #include "fcgi_stdio.h" |
7 | |
8 | int |
9 | FCGI_Accept(void); |
10 | |
11 | FILE * |
12 | FCGI_ToFILE(FCGI_FILE *); |
13 | |
14 | FCGI_Stream * |
15 | FCGI_ToFcgiStream(FCGI_FILE *); |
16 | |
17 | |
18 | DESCRIPTION |
19 | The FCGI_Accept function accepts a new request from the HTTP server |
20 | and creates a CGI-compatible execution environment for the request. |
21 | |
22 | If the application was invoked as a CGI program, the first |
23 | call to FCGI_Accept is essentially a no-op and the second |
24 | call returns -1. This causes a correctly coded FastCGI Responder |
25 | application to run a single request and exit, giving CGI |
26 | behavior. |
27 | |
28 | If the application was invoked as a FastCGI server, the first |
29 | call to FCGI_Accept indicates that the application has completed |
30 | its initialization and is ready to accept its first request. |
31 | Subsequent calls to FCGI_Accept indicate that the application has |
32 | completed processing its current request and is ready to accept a |
33 | new request. An application can complete the current request |
34 | without accepting a new one by calling FCGI_Finish(3); later, when |
35 | ready to accept a new request, the application calls FCGI_Accept. |
36 | |
37 | In completing the current request, FCGI_Accept may detect |
38 | errors, e.g. a broken pipe to a client who has disconnected |
39 | early. FCGI_Accept ignores such errors. An application |
40 | that wishes to handle such errors should explicitly call |
41 | fclose(stderr), then fclose(stdout); an EOF return from |
42 | either one indicates an error. |
43 | |
44 | If the environment variable FCGI_WEB_SERVER_ADDRS is set when |
45 | FCGI_Accept is called, it should contain a comma-separated list |
46 | of IP addresses. Each IP address is written as four decimal |
47 | numbers in the range [0..255] separated by decimal points. |
48 | (nslookup(8) translates the more familiar symbolic IP hostname |
49 | into this form.) So one legal binding for this variable is |
50 | |
51 | FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71 |
52 | |
53 | FCGI_Accept checks the peer IP address of each new connection for |
54 | membership in the list. If the check fails (including the |
55 | possibility that the connection didn't use TCP/IP transport), |
56 | FCGI_Accept closes the connection and accepts another one |
57 | (without returning in between). |
58 | |
59 | After accepting a new request, FCGI_Accept assigns new values |
60 | to the global variables stdin, stdout, stderr, and environ. |
61 | After FCGI_Accept returns, these variables have the same |
62 | interpretation as on entry to a CGI program. |
63 | |
64 | FCGI_Accept frees any storage allocated by the previous call |
65 | to FCGI_Accept. This has important consequences: |
66 | |
67 | DO NOT retain pointers to the environ array or any strings |
68 | contained in it (e.g. to the result of calling getenv(3)), |
69 | since these will be freed by the next call to FCGI_Finish or |
70 | FCGI_Accept. |
71 | |
72 | DO NOT use setenv(3) or putenv(3) to modify the environ array |
73 | created by FCGI_Accept, since this will either leak storage |
74 | or cause the next call to FCGI_Finish or FCGI_Accept to free |
75 | storage that should not be freed. |
76 | |
77 | If your application needs to use setenv or putenv to modify |
78 | the environ array, it should follow this coding pattern: |
79 | |
80 | char **savedEnviron, **requestEnviron; |
81 | int acceptStatus; |
82 | |
83 | savedEnviron = environ; |
84 | acceptStatus = FCGI_Accept(); |
85 | requestEnviron = environ; |
86 | environ = savedEnviron; |
87 | if(acceptStatus >= 0 && !FCGX_IsCGI()) { |
88 | /* |
89 | * requestEnviron points to name-value pairs in |
90 | * storage allocated by FCGI_Accept. OK to read, |
91 | * not OK to retain pointers -- make copies instead. |
92 | */ |
93 | } |
94 | /* |
95 | * OK to do setenv or putenv, but beware of storage leaks! |
96 | */ |
97 | |
98 | In addition to the standard CGI environment variables, the |
99 | environment variable FCGI_ROLE is always set to the role |
100 | of the current request. The roles currently defined are |
101 | RESPONDER, AUTHORIZER, and FILTER. |
102 | |
103 | In the FILTER role, the additional variables FCGI_DATA_LENGTH |
104 | and FCGI_DATA_LAST_MOD are also defined. See the manpage |
105 | FCGI_StartFilterData(3) for complete information. |
106 | |
107 | The macros FCGI_ToFILE and FCGI_ToFcgiStream are provided |
108 | to allow escape to native functions that use the types FILE or |
109 | FCGI_Stream. In the case of FILE, functions would have to |
110 | be separately compiled, since fcgi_stdio.h replaces the standard |
111 | FILE with FCGI_FILE. |
112 | |
113 | |
114 | RETURN VALUES |
115 | 0 for successful call, -1 for error (application should exit). |
116 | |
117 | SEE ALSO |
118 | FCGI_Finish(3) |
119 | FCGI_StartFilterData(3) |
120 | FCGI_SetExitStatus(3) |
121 | cgi-fcgi(1) |
122 | nslookup(8) |
123 | |
124 | HISTORY |
125 | Copyright (c) 1996 Open Market, Inc. |
126 | See the file "LICENSE.TERMS" for information on usage and redistribution |
127 | of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
128 | $Id: FCGI_Accept.3,v 1.1 1997/09/16 15:36:25 stanleyg Exp $ |