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

<html><head><title>FCGI_Accept(2) Man Page</title></head>
<body bgcolor=#ffffff>
 
<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">
<center><h1>A FastCGI <br>Reference Pages</h1></center>
</a><a name="95882"></a>
This appendix contains reference pages for the following FastCGI routines from the <code>fcgi_stdio</code> library:<p>
<ul><a name="95884"></a>
<li><code>FCGI_Accept</code>
<a name="95885"></a>
<li><code>FCGI_Start_Filter_Data</code>
<a name="95859"></a>
<li><code>FCGI_SetExitStatus</code>
</ul><a name="95860">
<h1> FCGI_Accept (3)</h1>
</a><a name="95861">
<h2> Name</h2>
</a><a name="95637"></a>
<code>FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream</code> - fcgi_stdio compatibility library<p>
<a name="95652">
<h2> Synopsis</h2>
</a><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><a name="95656">
<h2> Description </h2>
</a><a name="95683"></a>
The FCGI_Accept function accepts a new request from the HTTP server and creates a CGI-compatible execution environment for the request.<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>
<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>
<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>
<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>
<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>
<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>
<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>
<a name="95664">
<h2> Return Values</h2>
</a><a name="95686"></a>
0 for successful call, -1 for error (application should exit).<p>
<a name="95309">
<h1> FCGI_StartFilterData (3)</h1>
</a><a name="95310">
<h2> Name</h2>
</a><a name="95311"></a>
<code>FCGI_StartFilterData</code> -<code>fcgi_stdio</code> compatibility library<p>
<a name="95312">
<h2> Synopsis</h2>
</a><pre><a name="95313">
#include &lt;fcgi_stdio.h&gt;
</a>
<a name="95314">
int FCGI_StartFilterData(void)
</a>
</pre><a name="95315">
<h2> Description</h2>
</a><a name="95728"></a>
Enables a FastCGI Filter application to begin reading its filter input data from <code>stdin</code>.<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("FCGI_ROLE") == "FILTER"</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>
<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>
<a name="95731"></a>
The application can determine the number of bytes available on <code>FCGI_DATA</code> by performing <code>atoi(getenv("FCGI_DATA_LENGTH")</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>
<a name="95732"></a>
The application can determine last modification time of the filter input data by performing <code>getenv("FCGI_DATA_LAST_MOD").</code> This allows applications to perform caching based on last modification time.<p>
<a name="95733">
<h2> Return Values</h2>
</a><a name="95322"></a>
Returns 0 on success and a negative integer on failure. <p>
<a name="95323">
<h2> Example</h2>
</a><a name="95363"></a>
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>
<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><a name="95846">
<h1> FCGI_SetExitStatus(3)</h1>
</a><a name="95793">
<h2> Name </h2>
</a><a name="95794"></a>
<code>FCGI_SetExitStatus</code> - <code>fcgi_stdio</code> compatibility library<p>
<a name="95786">
<h2> Synopsis </h2>
</a><pre><a name="95795">
#include &lt;fcgi_stdio.h&gt;
</a>
<a name="95787">
void FCGI_SetExitStatus(int status);
</a>
</pre><a name="95788">
<h2> Description </h2>
</a><a name="95796"></a>
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>
<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>
<a name="95797"></a>
<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
6791223e	1	<html><head><title>FCGI_Accept(2) Man Page</title></head>
0198fd3c	2	<body bgcolor=#ffffff>
	3
	4	<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>
	5	<hr><br>
	6
	7	<a name="3601">
	8	<center><h1>A FastCGI <br>Reference Pages</h1></center>
6791223e	9	</a><a name="95882"></a>
0198fd3c	10	This appendix contains reference pages for the following FastCGI routines from the <code>fcgi_stdio</code> library:<p>
6791223e	11	<ul><a name="95884"></a>
0198fd3c	12	<li><code>FCGI_Accept</code>
6791223e	13	<a name="95885"></a>
0198fd3c	14	<li><code>FCGI_Start_Filter_Data</code>
6791223e	15	<a name="95859"></a>
0198fd3c	16	<li><code>FCGI_SetExitStatus</code>
6791223e	17	</ul><a name="95860">
0198fd3c	18	<h1> FCGI_Accept (3)</h1>
	19	</a><a name="95861">
	20	<h2> Name</h2>
6791223e	21	</a><a name="95637"></a>
0198fd3c	22	<code>FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream</code> - fcgi_stdio compatibility library<p>
6791223e	23	<a name="95652">
0198fd3c	24	<h2> Synopsis</h2>
	25	</a><pre><a name="95669">
	26	#include <fcgi_stdio.h>
	27	</a>
	28	<a name="95653">
	29	int <br>FCGI_Accept(void);
	30	</a>
	31	<a name="95654">
	32	FILE * <br>FCGI_ToFILE(FCGI_FILE *);
	33	</a>
	34	<a name="95655">
	35	FCGI_Stream * <br>FCGI_ToFcgiStream(FCGI_FILE *);
	36	</a>
	37	</pre><a name="95656">
	38	<h2> Description </h2>
6791223e	39	</a><a name="95683"></a>
0198fd3c	40	The FCGI_Accept function accepts a new request from the HTTP server and creates a CGI-compatible execution environment for the request.<p>
6791223e	41	<a name="95657"></a>
0198fd3c	42	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>
6791223e	43	<a name="95658"></a>
0198fd3c	44	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>
6791223e	45	<a name="95659"></a>
0198fd3c	46	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>
6791223e	47	<a name="95660"></a>
0198fd3c	48	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>
6791223e	49	<a name="95661"></a>
0198fd3c	50	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>
6791223e	51	<a name="95662"></a>
0198fd3c	52	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>
6791223e	53	<a name="95663"></a>
0198fd3c	54	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>
6791223e	55	<a name="95664">
0198fd3c	56	<h2> Return Values</h2>
6791223e	57	</a><a name="95686"></a>
0198fd3c	58	0 for successful call, -1 for error (application should exit).<p>
6791223e	59	<a name="95309">
0198fd3c	60	<h1> FCGI_StartFilterData (3)</h1>
	61	</a><a name="95310">
	62	<h2> Name</h2>
6791223e	63	</a><a name="95311"></a>
0198fd3c	64	<code>FCGI_StartFilterData</code> -<code>fcgi_stdio</code> compatibility library<p>
6791223e	65	<a name="95312">
0198fd3c	66	<h2> Synopsis</h2>
	67	</a><pre><a name="95313">
	68	#include <fcgi_stdio.h>
	69	</a>
	70	<a name="95314">
	71	int FCGI_StartFilterData(void)
	72	</a>
	73	</pre><a name="95315">
	74	<h2> Description</h2>
6791223e	75	</a><a name="95728"></a>
0198fd3c	76	Enables a FastCGI Filter application to begin reading its filter input data from <code>stdin</code>.<p>
6791223e	77	<a name="95729"></a>
0198fd3c	78	In order to call <code>FCGI_StartFilterData</code>, the FastCGI application should have been invoked in the filter role (<code>getenv("FCGI_ROLE") == "FILTER"</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>
6791223e	79	<a name="95730"></a>
0198fd3c	80	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>
6791223e	81	<a name="95731"></a>
0198fd3c	82	The application can determine the number of bytes available on <code>FCGI_DATA</code> by performing <code>atoi(getenv("FCGI_DATA_LENGTH")</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>
6791223e	83	<a name="95732"></a>
0198fd3c	84	The application can determine last modification time of the filter input data by performing <code>getenv("FCGI_DATA_LAST_MOD").</code> This allows applications to perform caching based on last modification time.<p>
6791223e	85	<a name="95733">
0198fd3c	86	<h2> Return Values</h2>
6791223e	87	</a><a name="95322"></a>
0198fd3c	88	Returns 0 on success and a negative integer on failure. <p>
6791223e	89	<a name="95323">
0198fd3c	90	<h2> Example</h2>
6791223e	91	</a><a name="95363"></a>
0198fd3c	92	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>
6791223e	93	<pre><a name="95324">
0198fd3c	94	while (FCGI_Accept() >= 0) {
	95	</a>
	96	<a name="95325">
	97	...
	98	</a>
	99	<a name="95364">
	100	/* Read data passed by client. */
	101	</a>
	102	<a name="95358">
	103	while (getchar () != OF)
	104	</a>
	105	<a name="95935">
	106	{
	107	</a>
	108	<a name="95930">
	109	}
	110	</a>
	111	<a name="95359">
	112
	113	</a>
	114	<a name="95367">
	115	/* Adjust standard input stream. */
	116	</a>
	117	<a name="95366">
	118	status = FCGI_StartFilterData();
	119	</a>
	120	<a name="95369">
	121
	122	</a>
	123	<a name="95360">
	124	/* Read in filter data and echo it back to client. */
	125	</a>
	126	<a name="95368">
	127	while ((len = fread(tempBuffer, 1, 1024, stdin)) > 0)
	128	</a>
	129	<a name="95361">
	130	fwrite(tempBuffer, 1, len, stdout);
	131	</a>
	132	<a name="95844">
	133
	134	</a>
	135	<a name="95845">
	136	} /* End FCGI_Accept loop */
	137	</a>
	138	</pre><a name="95846">
	139	<h1> FCGI_SetExitStatus(3)</h1>
	140	</a><a name="95793">
	141	<h2> Name </h2>
6791223e	142	</a><a name="95794"></a>
0198fd3c	143	<code>FCGI_SetExitStatus</code> - <code>fcgi_stdio</code> compatibility library<p>
6791223e	144	<a name="95786">
0198fd3c	145	<h2> Synopsis </h2>
	146	</a><pre><a name="95795">
	147	#include <fcgi_stdio.h>
	148	</a>
	149	<a name="95787">
	150	void FCGI_SetExitStatus(int status);
	151	</a>
	152	</pre><a name="95788">
	153	<h2> Description </h2>
6791223e	154	</a><a name="95796"></a>
0198fd3c	155	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>
6791223e	156	<a name="95789"></a>
0198fd3c	157	You can call <code>FCGI_SetExitStatus</code> several times during a request; the last call before the request ends determines the value.<p>
6791223e	158	<a name="95797"></a>
0198fd3c	159	<p>
6791223e	160
0198fd3c	161	<hr><br>
	162
	163	<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>
	164	<hr><br>
	165
	166
	167
	168	<!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
	169	<!-- -->
	170	<!-- For more information on how this document, and how the rest of -->
	171	<!-- this server was created, email yourEmail@xyzcorp.com -->
	172	<!-- -->
	173	<!-- Last updated: 04/15/96 08:00:20 -->
	174
	175	</body>
	176	</html>