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" 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 $