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