1NAME
2     FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream
3         ‐ fcgi_stdio compatibility library
4
5SYNOPSIS
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
18DESCRIPTION
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
24     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
31     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
47     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
54     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
64         FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71
65
66     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
74     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
80     FCGI_Accept frees any storage allocated by the previous call
81     to FCGI_Accept.  This has important consequences:
82
83         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
91         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
99         If  your  application  needs  to use setenv or putenv to
100modify
101         the environ array, it should follow this coding pattern:
102
103             char **savedEnviron, **requestEnviron;
104             int acceptStatus;
105
106             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
124     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
129     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
134     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.
141
142
143RETURN VALUES
144     0 for successful call, ‐1 for error (application should  ex‐
145it).
146
147SEE ALSO
148     FCGI_Finish(3)
149     FCGI_StartFilterData(3)
150     FCGI_SetExitStatus(3)
151     cgi‐fcgi(1)
152     nslookup(8)
153
154HISTORY
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
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
Impressum