[catagits/fcgi2.git] / doc / fastcgi-prog-guide / apaman.htm

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
   <HEAD>
      <TITLE>
         FCGI_Accept(2) Man Page
      </TITLE>
<STYLE TYPE="text/css">
 body {
  background-color: #ffffff;
 }
 li.c2 {list-style: none}
 div.c1 {text-align: center}
</STYLE>
   </HEAD>
   <BODY>
      <A HREF="cover.htm">[Top]</A> <A HREF="ch4tcl.htm">[Prev]</A> <A HREF="ap_guida.htm">[Next]</A> <A HREF=
      "ap_guida.htm">[Bottom]</A> 
      <HR>
      <BR>
       <A NAME="3601"></A>
      <DIV CLASS="c1">
         <H1>
            A FastCGI<BR>
            Reference Pages
         </H1>
      </DIV>
      <A NAME="95882"></A>
      <P>
         This appendix contains reference pages for the following FastCGI routines from the <CODE>fcgi_stdio</CODE>
         library:
      </P>
      <BR>
      <BR>
      <UL>
         <LI CLASS="c2">
            <A NAME="95884"></A>
         </LI>
         <LI>
            <CODE>FCGI_Accept</CODE> <A NAME="95885"></A>
         </LI>
         <LI>
            <CODE>FCGI_Start_Filter_Data</CODE> <A NAME="95859"></A>
         </LI>
         <LI>
            <CODE>FCGI_SetExitStatus</CODE>
         </LI>
      </UL>
      <H1>
         FCGI_Accept (3)
      </H1>
      <H2>
         Name
      </H2>
      <A NAME="95637"></A> <CODE>FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream</CODE>
      <P>
         - fcgi_stdio compatibility library
      </P>
      <BR>
      <BR>
      <H2>
         Synopsis
      </H2>
<PRE>
<A NAME="95669">#include &lt;fcgi_stdio.h&gt;
</A>
<A NAME="95653">int<BR>
 FCGI_Accept(void);
</A>
<A NAME="95654">FILE *<BR>
 FCGI_ToFILE(FCGI_FILE *);
</A>
<A NAME="95655">FCGI_Stream *<BR>
 FCGI_ToFcgiStream(FCGI_FILE *);
</A>
</PRE>
      <H2>
         Description
      </H2>
      <A NAME="95683"></A>
      <P>
         The FCGI_Accept function accepts a new request from the HTTP server and creates a CGI-compatible execution
         environment for the request.
      </P>
      <P>
         <A NAME="95657"></A> If the application was invoked as a CGI program, the first call to FCGI_Accept is
         essentially a no-op and the second call returns -1. This causes a correctly coded FastCGI application to run a
         single request and exit, giving CGI behavior.
      </P>
      <P>
         <A NAME="95658"></A> If the application was invoked as a FastCGI server, the first call to FCGI_Accept
         indicates that the application has completed its initialization and is ready to accept its first request.
         Subsequent calls to FCGI_Accept indicate that the application has completed processing its current request and
         is ready to accept a new request.
      </P>
      <P>
         <A NAME="95659"></A> In completing the current request, FCGI_Accept may detect errors, such as a broken pipe
         to a client who has disconnected early. FCGI_Accept ignores such errors. An application that wishes to handle
         such errors should explicitly call fclose(stderr), then fclose(stdout); an EOF return from either one
         indicates an error.
      </P>
      <P>
         <A NAME="95660"></A> After accepting a new request, FCGI_Accept assigns new values to the global variables
         stdin, stdout, stderr, and environ. After FCGI_Accept returns, these variables have the same interpretation as
         on entry to a CGI program.
      </P>
      <P>
         <A NAME="95661"></A> In addition to the standard CGI environment variables, the environment variable
         <CODE>FCGI_ROLE</CODE> is always set to the role of the current request. The roles currently defined are
         <CODE>RESPONDER, AUTHORIZER</CODE>, and <CODE>FILTER</CODE>.
      </P>
      <P>
         <A NAME="95662"></A> In the <CODE>FILTER</CODE> role, the additional variables <CODE>FCGI_DATA_LENGTH</CODE>
         and <CODE>FCGI_DATA_LAST_MOD</CODE> are also defined. See <CODE>FCGI_StartFilterData</CODE><CODE>(3</CODE>)
         for complete information.
      </P>
      <P>
         <A NAME="95663"></A> The macros <CODE>FCGI_ToFILE</CODE> and <CODE>FCGI_ToFcgiStream</CODE> are provided to
         allow escape to native functions that use the types <CODE>FILE</CODE> or <CODE>FCGI_Stream</CODE>. In the case
         of <CODE>FILE</CODE>, functions would have to be separately compiled, since <CODE>fcgi_stdio.h</CODE> replaces
         the standard <CODE>FILE</CODE> with <CODE>FCGI_FILE</CODE>.
      </P>
      <BR>
      <BR>
      <H2>
         Return Values
      </H2>
      <A NAME="95686"></A>
      <P>
         0 for successful call, -1 for error (application should exit).
      </P>
      <BR>
      <BR>
      <H1>
         FCGI_StartFilterData (3)
      </H1>
      <H2>
         Name
      </H2>
      <A NAME="95311"></A> <CODE>FCGI_StartFilterData</CODE>
      <P>
         -<CODE>fcgi_stdio</CODE> compatibility library
      </P>
      <BR>
      <BR>
      <H2>
         Synopsis
      </H2>
<PRE>
<A NAME="95313">#include &lt;fcgi_stdio.h&gt;
</A>
<A NAME="95314">int FCGI_StartFilterData(void)
</A>
</PRE>
      <H2>
         Description
      </H2>
      <A NAME="95728"></A>
      <P>
         Enables a FastCGI Filter application to begin reading its filter input data from <CODE>stdin</CODE>.
      </P>
      <P>
         <A NAME="95729"></A> In order to call <CODE>FCGI_StartFilterData</CODE>, the FastCGI application should have
         been invoked in the filter role (<CODE>getenv(&quot;FCGI_ROLE&quot;) == &quot;FILTER&quot;</CODE>), and should
         have read <CODE>stdin</CODE> to EOF, consuming the entire <CODE>FCGI_STDIN</CODE> data stream. The call to
         <CODE>FCGI_StartFilterData</CODE> positions stdin at the start of <CODE>FCGI_DATA</CODE>.
      </P>
      <P>
         <A NAME="95730"></A> If the preconditions are not met (e.g., the application has not read <CODE>stdin</CODE>
         to EOF), <CODE>FCGI_StartFilterData</CODE> returns a negative result, and the application will get EOF on
         attempts to read from <CODE>stdin</CODE>.
      </P>
      <P>
         <A NAME="95731"></A> The application can determine the number of bytes available on <CODE>FCGI_DATA</CODE> by
         performing <CODE>atoi(getenv(&quot;FCGI_DATA_LENGTH&quot;)</CODE>. If fewer than this many bytes are delivered
         on <CODE>stdin</CODE> after calling <CODE>FCGI_StartFilterData</CODE>, the application should perform an
         application-specific error response. If the application normally makes an update, most likely it should abort
         the update.
      </P>
      <P>
         <A NAME="95732"></A> The application can determine last modification time of the filter input data by
         performing <CODE>getenv(&quot;FCGI_DATA_LAST_MOD&quot;).</CODE> This allows applications to perform caching
         based on last modification time.
      </P>
      <BR>
      <BR>
      <H2>
         Return Values
      </H2>
      <A NAME="95322"></A>
      <P>
         Returns 0 on success and a negative integer on failure.
      </P>
      <BR>
      <BR>
      <H2>
         Example
      </H2>
      <A NAME="95363"></A>
      <P>
         The following example reads in all the client data, but ignores it. Then, the code calls
         <CODE>FCGI_StartFilterData</CODE>. Finally, the code reads in the file to be filtered and simply echos it back
         to the client.
      </P>
      <BR>
      <BR>
<PRE>
<A NAME="95324">while (FCGI_Accept() &gt;= 0) {
</A>
<A NAME="95325">...
</A>
 <A NAME="95364">/* Read data passed by client. */
</A>
 <A NAME="95358"> while (getchar () != OF) 
</A>
<A NAME="95935">{
</A>
<A NAME="95930">}
</A>
<A NAME="95359">
</A>
 <A NAME="95367">/* Adjust standard input stream. */
</A>
 <A NAME="95366"> status = FCGI_StartFilterData();
</A>
<A NAME="95369">
</A>
 <A NAME="95360">/* Read in filter data and echo it back to client. */
</A>
 <A NAME="95368"> while ((len = fread(tempBuffer, 1, 1024, stdin)) &gt; 0) 
</A>
 <A NAME="95361">   fwrite(tempBuffer, 1, len, stdout);
</A>
<A NAME="95844">
</A>
<A NAME="95845">} /* End FCGI_Accept loop */
</A>
</PRE>
      <H1>
         FCGI_SetExitStatus(3)
      </H1>
      <H2>
         Name
      </H2>
      <A NAME="95794"></A> <CODE>FCGI_SetExitStatus</CODE>
      <P>
         - <CODE>fcgi_stdio</CODE> compatibility library
      </P>
      <BR>
      <BR>
      <H2>
         Synopsis
      </H2>
<PRE>
<A NAME="95795">#include &lt;fcgi_stdio.h&gt;
</A>
<A NAME="95787">void FCGI_SetExitStatus(int status);
</A>
</PRE>
      <H2>
         Description
      </H2>
      <A NAME="95796"></A>
      <P>
         Sets the exit status for the current FastCGI request. The exit status is the status code the request would
         have exited with, had the request been run as a CGI program.
      </P>
      <P>
         <A NAME="95789"></A> You can call <CODE>FCGI_SetExitStatus</CODE> several times during a request; the last
         call before the request ends determines the value.
      </P>
      <P>
         <A NAME="95797"></A>
      </P>
      <P>
      </P>
      <HR>
      <BR>
       <A HREF="cover.htm">[Top]</A> <A HREF="ch4tcl.htm">[Prev]</A> <A HREF="ap_guida.htm">[Next]</A> <A HREF=
      "ap_guida.htm">[Bottom]</A> 
      <HR>
      <BR>
       <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
      <!-- -->
      <!-- For more information on how this document, and how the rest of -->
      <!-- this server was created, email yourEmail@xyzcorp.com -->
      <!-- -->
      <!-- Last updated: 04/15/96 08:00:20 -->
   </BODY>
</HTML>
Commit	Line	Data
852467e2	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
	2	<HTML>
	3	<HEAD>
	4	<TITLE>
	5	FCGI_Accept(2) Man Page
	6	</TITLE>
	7	<STYLE TYPE="text/css">
	8	body {
	9	background-color: #ffffff;
	10	}
	11	li.c2 {list-style: none}
	12	div.c1 {text-align: center}
	13	</STYLE>
	14	</HEAD>
	15	<BODY>
	16	<A HREF="cover.htm">[Top]</A> <A HREF="ch4tcl.htm">[Prev]</A> <A HREF="ap_guida.htm">[Next]</A> <A HREF=
	17	"ap_guida.htm">[Bottom]</A>
	18	<HR>
	19	<BR>
	20	<A NAME="3601"></A>
	21	<DIV CLASS="c1">
	22	<H1>
	23	A FastCGI<BR>
	24	Reference Pages
	25	</H1>
	26	</DIV>
	27	<A NAME="95882"></A>
	28	<P>
	29	This appendix contains reference pages for the following FastCGI routines from the <CODE>fcgi_stdio</CODE>
	30	library:
	31	</P>
	32	<BR>
	33	<BR>
	34	<UL>
	35	<LI CLASS="c2">
	36	<A NAME="95884"></A>
	37	</LI>
	38	<LI>
	39	<CODE>FCGI_Accept</CODE> <A NAME="95885"></A>
	40	</LI>
	41	<LI>
	42	<CODE>FCGI_Start_Filter_Data</CODE> <A NAME="95859"></A>
	43	</LI>
	44	<LI>
	45	<CODE>FCGI_SetExitStatus</CODE>
	46	</LI>
	47	</UL>
	48	<H1>
	49	FCGI_Accept (3)
	50	</H1>
	51	<H2>
	52	Name
	53	</H2>
	54	<A NAME="95637"></A> <CODE>FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream</CODE>
	55	<P>
	56	- fcgi_stdio compatibility library
	57	</P>
	58	<BR>
	59	<BR>
	60	<H2>
	61	Synopsis
	62	</H2>
	63	<PRE>
	64	<A NAME="95669">#include <fcgi_stdio.h>
65	</A>
66	<A NAME="95653">int<BR>
67	FCGI_Accept(void);
68	</A>
69	<A NAME="95654">FILE *<BR>
70	FCGI_ToFILE(FCGI_FILE *);
71	</A>
72	<A NAME="95655">FCGI_Stream *<BR>
73	FCGI_ToFcgiStream(FCGI_FILE *);
74	</A>
75	</PRE>
76	<H2>
77	Description
78	</H2>
79	<A NAME="95683"></A>
80	<P>
81	The FCGI_Accept function accepts a new request from the HTTP server and creates a CGI-compatible execution
82	environment for the request.
83	</P>
84	<P>
85	<A NAME="95657"></A> If the application was invoked as a CGI program, the first call to FCGI_Accept is
86	essentially a no-op and the second call returns -1. This causes a correctly coded FastCGI application to run a
87	single request and exit, giving CGI behavior.
88	</P>
89	<P>
90	<A NAME="95658"></A> If the application was invoked as a FastCGI server, the first call to FCGI_Accept
91	indicates that the application has completed its initialization and is ready to accept its first request.
92	Subsequent calls to FCGI_Accept indicate that the application has completed processing its current request and
93	is ready to accept a new request.
94	</P>
95	<P>
96	<A NAME="95659"></A> In completing the current request, FCGI_Accept may detect errors, such as a broken pipe
97	to a client who has disconnected early. FCGI_Accept ignores such errors. An application that wishes to handle
98	such errors should explicitly call fclose(stderr), then fclose(stdout); an EOF return from either one
99	indicates an error.
100	</P>
101	<P>
102	<A NAME="95660"></A> After accepting a new request, FCGI_Accept assigns new values to the global variables
103	stdin, stdout, stderr, and environ. After FCGI_Accept returns, these variables have the same interpretation as
104	on entry to a CGI program.
105	</P>
106	<P>
107	<A NAME="95661"></A> In addition to the standard CGI environment variables, the environment variable
108	<CODE>FCGI_ROLE</CODE> is always set to the role of the current request. The roles currently defined are
109	<CODE>RESPONDER, AUTHORIZER</CODE>, and <CODE>FILTER</CODE>.
110	</P>
111	<P>
112	<A NAME="95662"></A> In the <CODE>FILTER</CODE> role, the additional variables <CODE>FCGI_DATA_LENGTH</CODE>
113	and <CODE>FCGI_DATA_LAST_MOD</CODE> are also defined. See <CODE>FCGI_StartFilterData</CODE><CODE>(3</CODE>)
114	for complete information.
115	</P>
116	<P>
117	<A NAME="95663"></A> The macros <CODE>FCGI_ToFILE</CODE> and <CODE>FCGI_ToFcgiStream</CODE> are provided to
118	allow escape to native functions that use the types <CODE>FILE</CODE> or <CODE>FCGI_Stream</CODE>. In the case
119	of <CODE>FILE</CODE>, functions would have to be separately compiled, since <CODE>fcgi_stdio.h</CODE> replaces
120	the standard <CODE>FILE</CODE> with <CODE>FCGI_FILE</CODE>.
121	</P>
122	<BR>
123	<BR>
124	<H2>
125	Return Values
126	</H2>
127	<A NAME="95686"></A>
128	<P>
129	0 for successful call, -1 for error (application should exit).
130	</P>
131	<BR>
132	<BR>
133	<H1>
134	FCGI_StartFilterData (3)
135	</H1>
136	<H2>
137	Name
138	</H2>
139	<A NAME="95311"></A> <CODE>FCGI_StartFilterData</CODE>
140	<P>
141	-<CODE>fcgi_stdio</CODE> compatibility library
142	</P>
143	<BR>
144	<BR>
145	<H2>
146	Synopsis
147	</H2>
148	<PRE>
149	<A NAME="95313">#include <fcgi_stdio.h>
150	</A>
151	<A NAME="95314">int FCGI_StartFilterData(void)
152	</A>
153	</PRE>
154	<H2>
155	Description
156	</H2>
157	<A NAME="95728"></A>
158	<P>
159	Enables a FastCGI Filter application to begin reading its filter input data from <CODE>stdin</CODE>.
160	</P>
161	<P>
162	<A NAME="95729"></A> In order to call <CODE>FCGI_StartFilterData</CODE>, the FastCGI application should have
163	been invoked in the filter role (<CODE>getenv("FCGI_ROLE") == "FILTER"</CODE>), and should
164	have read <CODE>stdin</CODE> to EOF, consuming the entire <CODE>FCGI_STDIN</CODE> data stream. The call to
165	<CODE>FCGI_StartFilterData</CODE> positions stdin at the start of <CODE>FCGI_DATA</CODE>.
166	</P>
167	<P>
168	<A NAME="95730"></A> If the preconditions are not met (e.g., the application has not read <CODE>stdin</CODE>
169	to EOF), <CODE>FCGI_StartFilterData</CODE> returns a negative result, and the application will get EOF on
170	attempts to read from <CODE>stdin</CODE>.
171	</P>
172	<P>
173	<A NAME="95731"></A> The application can determine the number of bytes available on <CODE>FCGI_DATA</CODE> by
174	performing <CODE>atoi(getenv("FCGI_DATA_LENGTH")</CODE>. If fewer than this many bytes are delivered
175	on <CODE>stdin</CODE> after calling <CODE>FCGI_StartFilterData</CODE>, the application should perform an
176	application-specific error response. If the application normally makes an update, most likely it should abort
177	the update.
178	</P>
179	<P>
180	<A NAME="95732"></A> The application can determine last modification time of the filter input data by
181	performing <CODE>getenv("FCGI_DATA_LAST_MOD").</CODE> This allows applications to perform caching
182	based on last modification time.
183	</P>
184	<BR>
185	<BR>
186	<H2>
187	Return Values
188	</H2>
189	<A NAME="95322"></A>
190	<P>
191	Returns 0 on success and a negative integer on failure.
192	</P>
193	<BR>
194	<BR>
195	<H2>
196	Example
197	</H2>
198	<A NAME="95363"></A>
199	<P>
200	The following example reads in all the client data, but ignores it. Then, the code calls
201	<CODE>FCGI_StartFilterData</CODE>. Finally, the code reads in the file to be filtered and simply echos it back
202	to the client.
203	</P>
204	<BR>
205	<BR>
206	<PRE>
207	<A NAME="95324">while (FCGI_Accept() >= 0) {
208	</A>
209	<A NAME="95325">...
210	</A>
211	<A NAME="95364">/* Read data passed by client. */
212	</A>
213	<A NAME="95358"> while (getchar () != OF)
214	</A>
215	<A NAME="95935">{
216	</A>
217	<A NAME="95930">}
218	</A>
219	<A NAME="95359">
220	</A>
221	<A NAME="95367">/* Adjust standard input stream. */
222	</A>
223	<A NAME="95366"> status = FCGI_StartFilterData();
224	</A>
225	<A NAME="95369">
226	</A>
227	<A NAME="95360">/* Read in filter data and echo it back to client. */
228	</A>
229	<A NAME="95368"> while ((len = fread(tempBuffer, 1, 1024, stdin)) > 0)
230	</A>
231	<A NAME="95361"> fwrite(tempBuffer, 1, len, stdout);
232	</A>
233	<A NAME="95844">
234	</A>
235	<A NAME="95845">} /* End FCGI_Accept loop */
236	</A>
237	</PRE>
238	<H1>
239	FCGI_SetExitStatus(3)
240	</H1>
241	<H2>
242	Name
243	</H2>
244	<A NAME="95794"></A> <CODE>FCGI_SetExitStatus</CODE>
245	<P>
246	- <CODE>fcgi_stdio</CODE> compatibility library
247	</P>
248	<BR>
249	<BR>
250	<H2>
251	Synopsis
252	</H2>
253	<PRE>
254	<A NAME="95795">#include <fcgi_stdio.h>
255	</A>
256	<A NAME="95787">void FCGI_SetExitStatus(int status);
257	</A>
258	</PRE>
259	<H2>
260	Description
261	</H2>
262	<A NAME="95796"></A>
263	<P>
264	Sets the exit status for the current FastCGI request. The exit status is the status code the request would
265	have exited with, had the request been run as a CGI program.
266	</P>
267	<P>
268	<A NAME="95789"></A> You can call <CODE>FCGI_SetExitStatus</CODE> several times during a request; the last
269	call before the request ends determines the value.
270	</P>
271	<P>
272	<A NAME="95797"></A>
273	</P>
274	<P>
275	</P>
276	<HR>
277	<BR>
278	<A HREF="cover.htm">[Top]</A> <A HREF="ch4tcl.htm">[Prev]</A> <A HREF="ap_guida.htm">[Next]</A> <A HREF=
279	"ap_guida.htm">[Bottom]</A>
280	<HR>
281	<BR>
282	<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
283	<!-- -->
284	<!-- For more information on how this document, and how the rest of -->
285	<!-- this server was created, email yourEmail@xyzcorp.com -->
286	<!-- -->
287	<!-- Last updated: 04/15/96 08:00:20 -->
288	</BODY>
289	</HTML>
290