FCGI_Accept.3

命名
     FCGI_Accept, FCGI_ToFILE, FCGI_ToFcgiStream
         - fcgi_stdio兼容库

摘要
     #include "fcgi_stdio.h"

     int
     FCGI_Accept(void);

     FILE *
     FCGI_ToFILE(FCGI_FILE *);

     FCGI_Stream *
     FCGI_ToFcgiStream(FCGI_FILE *);


说明
     FCGI_Accept函数接收来自HTTP服务器的新请求，
     并为之创建CGI兼容的执行环境。

     如果应用作为CGI程序被调用，对FCGI_Accept的首次调用根本是个空操作，
     而且第二次调用返回-1。这使正确编码的FastCGI响应器应用运行单个请求
     并退出，产生CGI行为。

     如果应用作为FastCGI服务器被调用，对FCGI_Accept的首次调用表明
     应用已经完成其初始化并且准备接受其第一个请求。对FCGI_Accept的
     后续调用表明应用已经完成了对其当前请求的处理并准备接受新请求。
     应用能通过调用FCGI_Finish(3)完成当前请求而不接受新请求；
     随后，当准备接受新请求时，应用调用FCGI_Accept。

     在完成当前请求期间，FCGI_Accept可以检测错误，例如到早前已经
     切断线路的客户端的断掉的管道。FCGI_Accept忽略这类错误。
     希望处理这类错误的应用应当显式地调用fclose(stderr)，
     然后fclose(stdout)；任何一个返回EOF则表示一个错误。

     当FCGI_Accept被调用时，如果环境变量FCGI_WEB_SERVER_ADDRS已经设置，
     后者应当包含逗号分隔的IP地址列表。每个IP地址写作由小数点分隔的
     [0..255]区间内的四个十进制数。（nslookup(8)把更常见的符号，
     IP主机名（hostname），转换为该形式。）所以改变量的一个合法绑定是

         FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71

     FCGI_Accept为每个新线路的同级（peer）IP地址检查列表中的成员。
     如果检查失败（包括连路不是用的TCP/IP传输这种可能），
     FCGI_Accept关闭线路并接受另一个（二者之间并不返回）。

     在收到新请求后，FCGI_Accept为全局变量stdin、stdout、stderr和environ
     赋新值。在FCGI_Accept返回后，这些变量具有同CGI入口处一样的解释。

     FCGI_Accept释放以前调用FCGI_Accept分配的任何内存。这很重要：

         不要 保留指向数组或其中的任何字符串（例如调用getenv(3)的结果），
         因为这些将被下次调用FCGI_Finish或FCGI_Accept释放。

         不要 使用setenv(3)或putenv(3)修改FCGI_Accept创建的environ数组，
         因为这将泄漏内存或致使下次调用FCGI_Finish或FCGI_Accept去释放
         不该释放的内存。

         如果你的应用需要使用setenv或putenv修改environ数组，
         则它应当遵循这种编码模式：

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

             savedEnviron = environ;
             acceptStatus = FCGI_Accept();
             requestEnviron = environ;
             environ = savedEnviron;
             if(acceptStatus >= 0 && !FCGX_IsCGI()) {
                 /*
                  * requestEnviron指向FCGI_Accept分配的内存中的名-值对。
                  * 可以读取，不可保留指针 -- 改为获得拷贝。
                  */
             }
             /*
              * 可以setenv或putenv，但是小心内存泄漏！
              */

     除了标准的CGI环境变量，环境变量FCGI_ROLE总是设为当前请求的角色。
     当前定义的角色有RESPONDER、AUTHORIZER和FILTER。

     在FILTER角色中，也定义了额外的变量FCGI_DATA_LENGTH和
     FCGI_DATA_LAST_MOD。完备的信息可见man页FCGI_StartFilterData(3)。

     提供的宏FCGI_ToFILE和FCGI_ToFcgiStream允许转义为使用类型FILE或
     FCGI_Stream的原生函数。在FILE的情形中，函数将必须被分别编译，
     因为fcgi_stdio.h用FCGI_FILE替换了标准的FILE。

     
返回值
     成功调用时为0，出错时为-1（应用将会退出）。

请参阅
     FCGI_Finish(3)
     FCGI_StartFilterData(3)
     FCGI_SetExitStatus(3)
     cgi-fcgi(1)
     nslookup(8)

历史记录
     Copyright (c) 1996 Open Market, Inc.
     关于本文件的用法和再分发信息，以及无担保说明，请参阅。
     $Id: FCGI_Accept.3,v 1.1.1.1 1997/09/16 15:36:25 stanleyg Exp $