initial commit
[fcgi] / doc / FCGI_Accept.3
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.1.1 1997/09/16 15:36:25 stanleyg Exp $