[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]