[catagits/fcgi2.git] / doc / FCGI_Accept.3

NAME
     FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream
         - fcgi_stdio compatibility library

SYNOPSIS
     #include "fcgi_stdio.h"

     int
     FCGI_Accept(void);

     FILE *
     FCGI_ToFILE(FCGI_FILE *);

     FCGI_Stream *
     FCGI_ToFcgiStream(FCGI_FILE *);


DESCRIPTION
     The FCGI_Accept function accepts a new request from the HTTP server
     and creates a CGI-compatible execution environment for the request.

     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 Responder
     application to run a single request and exit, giving CGI
     behavior.

     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.  An application can complete the current request
     without accepting a new one by calling FCGI_Finish(3); later, when
     ready to accept a new request, the application calls FCGI_Accept.

     In completing the current request, FCGI_Accept may detect
     errors, e.g. 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.

     If the environment variable FCGI_WEB_SERVER_ADDRS is set when
     FCGI_Accept is called, it should contain a comma-separated list
     of IP addresses.  Each IP address is written as four decimal
     numbers in the range [0..255] separated by decimal points.
     (nslookup(8) translates the more familiar symbolic IP hostname
     into this form.)  So one legal binding for this variable is

         FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71

     FCGI_Accept checks the peer IP address of each new connection for
     membership in the list.  If the check fails (including the
     possibility that the connection didn't use TCP/IP transport),
     FCGI_Accept closes the connection and accepts another one
     (without returning in between).

     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.

     FCGI_Accept frees any storage allocated by the previous call
     to FCGI_Accept.  This has important consequences:

         DO NOT retain pointers to the environ array or any strings
         contained in it (e.g. to the result of calling getenv(3)),
         since these will be freed by the next call to FCGI_Finish or
         FCGI_Accept.

         DO NOT use setenv(3) or putenv(3) to modify the environ array
         created by FCGI_Accept, since this will either leak storage
         or cause the next call to FCGI_Finish or FCGI_Accept to free
         storage that should not be freed.

         If your application needs to use setenv or putenv to modify
         the environ array, it should follow this coding pattern:

             char **savedEnviron, **requestEnviron;
             int acceptStatus;

             savedEnviron = environ;
             acceptStatus = FCGI_Accept();
             requestEnviron = environ;
             environ = savedEnviron;
             if(acceptStatus >= 0 && !FCGX_IsCGI()) {
                 /*
                  * requestEnviron points to name-value pairs in
                  * storage allocated by FCGI_Accept.  OK to read,
                  * not OK to retain pointers -- make copies instead.
                  */
             }
             /*
              * OK to do setenv or putenv, but beware of storage leaks!
              */

     In addition to the standard CGI environment variables, the
     environment variable FCGI_ROLE is always set to the role
     of the current request.  The roles currently defined are
     RESPONDER, AUTHORIZER, and FILTER.

     In the FILTER role, the additional variables FCGI_DATA_LENGTH
     and FCGI_DATA_LAST_MOD are also defined.  See the manpage
     FCGI_StartFilterData(3) for complete information.

     The macros FCGI_ToFILE and FCGI_ToFcgiStream are provided
     to allow escape to native functions that use the types FILE or
     FCGI_Stream.  In the case of FILE, functions would have to
     be separately compiled, since fcgi_stdio.h replaces the standard
     FILE with FCGI_FILE.

     
RETURN VALUES
     0 for successful call, -1 for error (application should exit).

SEE ALSO
     FCGI_Finish(3)
     FCGI_StartFilterData(3)
     FCGI_SetExitStatus(3)
     cgi-fcgi(1)
     nslookup(8)

HISTORY
     Copyright (c) 1996 Open Market, Inc.
     See the file "LICENSE.TERMS" for information on usage and redistribution
     of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     $Id: FCGI_Accept.3,v 1.1 1997/09/16 15:36:25 stanleyg Exp $
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 $