Viewing file:  apaman.htm (9.3 KB) -rw-r--r--
Select action/file-type:
 (+) |  (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
FCGI_Accept(2) Man Page
[Top] [Prev] [Next] [Bottom]
A FastCGI
Reference Pages
This appendix contains reference pages for the following FastCGI routines from the fcgi_stdio
library:
-
-
FCGI_Accept
-
FCGI_Start_Filter_Data
-
FCGI_SetExitStatus
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 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.
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.
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.
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 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).
FCGI_StartFilterData (3)
Name
FCGI_StartFilterData
-fcgi_stdio compatibility library
Synopsis
#include <fcgi_stdio.h>
int FCGI_StartFilterData(void)
Description
Enables a FastCGI Filter application to begin reading its filter input data from stdin.
In order to call FCGI_StartFilterData, the FastCGI application should have
been invoked in the filter role (getenv("FCGI_ROLE") == "FILTER"), and should
have read stdin to EOF, consuming the entire FCGI_STDIN data stream. The call to
FCGI_StartFilterData positions stdin at the start of FCGI_DATA.
If the preconditions are not met (e.g., the application has not read stdin
to EOF), FCGI_StartFilterData returns a negative result, and the application will get EOF on
attempts to read from stdin.
The application can determine the number of bytes available on FCGI_DATA by
performing atoi(getenv("FCGI_DATA_LENGTH"). If fewer than this many bytes are delivered
on stdin after calling FCGI_StartFilterData, the application should perform an
application-specific error response. If the application normally makes an update, most likely it should abort
the update.
The application can determine last modification time of the filter input data by
performing getenv("FCGI_DATA_LAST_MOD"). This allows applications to perform caching
based on last modification time.
Return Values
Returns 0 on success and a negative integer on failure.
Example
The following example reads in all the client data, but ignores it. Then, the code calls
FCGI_StartFilterData. Finally, the code reads in the file to be filtered and simply echos it back
to the client.
while (FCGI_Accept() >= 0) {
...
/* Read data passed by client. */
while (getchar () != OF)
{
}
/* Adjust standard input stream. */
status = FCGI_StartFilterData();
/* Read in filter data and echo it back to client. */
while ((len = fread(tempBuffer, 1, 1024, stdin)) > 0)
fwrite(tempBuffer, 1, len, stdout);
} /* End FCGI_Accept loop */
FCGI_SetExitStatus(3)
Name
FCGI_SetExitStatus
- fcgi_stdio compatibility library
Synopsis
#include <fcgi_stdio.h>
void FCGI_SetExitStatus(int status);
Description
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.
You can call FCGI_SetExitStatus several times during a request; the last
call before the request ends determines the value.
[Top] [Prev] [Next] [Bottom]
|