EIC code displayed by LXR master/​include/​fcgiapp.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2024-05-18 08:29:50

 /*
  * fcgiapp.h --
  *
  *      Definitions for FastCGI application server programs
  *
  *
  * Copyright (c) 1996 Open Market, Inc.
  *
  * See the file "LICENSE.TERMS" for information on usage and redistribution
  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  *
  * $Id: fcgiapp.h,v 1.14 2003/06/22 00:16:44 robs Exp $
  */
 
 #ifndef _FCGIAPP_H
 #define _FCGIAPP_H
 
 /* Hack to see if we are building Tcl - Tcl needs varargs not stdarg */
 #ifndef TCL_LIBRARY
 #include <stdarg.h>
 #else
 #include <varargs.h>
 #endif
 
 #ifndef DLLAPI
 #if defined (_WIN32) && defined (_MSC_VER)
 #define DLLAPI __declspec(dllimport)
 #else
 #define DLLAPI
 #endif
 #endif
 
 #if defined (c_plusplus) || defined (__cplusplus)
 extern "C" {
 #endif
 
 /*
  * Error codes.  Assigned to avoid conflict with EOF and errno(2).
  */
 #define FCGX_UNSUPPORTED_VERSION -2
 #define FCGX_PROTOCOL_ERROR -3
 #define FCGX_PARAMS_ERROR -4
 #define FCGX_CALL_SEQ_ERROR -5
 
 /*
  * This structure defines the state of a FastCGI stream.
  * Streams are modeled after the FILE type defined in stdio.h.
  * (We wouldn't need our own if platform vendors provided a
  * standard way to subclass theirs.)
  * The state of a stream is private and should only be accessed
  * by the procedures defined below.
  */
 typedef struct FCGX_Stream {
     unsigned char *rdNext;    /* reader: first valid byte
                                * writer: equals stop */
     unsigned char *wrNext;    /* writer: first free byte
                                * reader: equals stop */
     unsigned char *stop;      /* reader: last valid byte + 1
                                * writer: last free byte + 1 */
     unsigned char *stopUnget; /* reader: first byte of current buffer
                                * fragment, for ungetc
                                * writer: undefined */
     int isReader;
     int isClosed;
     int wasFCloseCalled;
     int FCGI_errno;                /* error status */
     void (*fillBuffProc) (struct FCGX_Stream *stream);
     void (*emptyBuffProc) (struct FCGX_Stream *stream, int doClose);
     void *data;
 } FCGX_Stream;
 
 /*
  * An environment (as defined by environ(7)): A NULL-terminated array
  * of strings, each string having the form name=value.
  */
 typedef char **FCGX_ParamArray;
 
 /*
  * FCGX_Request Flags
  *
  * Setting FCGI_FAIL_ACCEPT_ON_INTR prevents FCGX_Accept() from
  * restarting upon being interrupted.
  */
 #define FCGI_FAIL_ACCEPT_ON_INTR    1
 
 /*
  * FCGX_Request -- State associated with a request.
  *
  * Its exposed for API simplicity, I expect parts of it to change!
  */
 typedef struct FCGX_Request {
     int requestId;            /* valid if isBeginProcessed */
     int role;
     FCGX_Stream *in;
     FCGX_Stream *out;
     FCGX_Stream *err;
     char **envp;
 
     /* Don't use anything below here */
 
     struct Params *paramsPtr;
     int ipcFd;               /* < 0 means no connection */
     int isBeginProcessed;     /* FCGI_BEGIN_REQUEST seen */
     int keepConnection;       /* don't close ipcFd at end of request */
     int appStatus;
     int nWriters;             /* number of open writers (0..2) */
     int flags;
     int listen_sock;
     int detached;
 } FCGX_Request;
 
 
 /*
  *======================================================================
  * Control
  *======================================================================
  */
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_IsCGI --
  *
  *      Returns TRUE iff this process appears to be a CGI process
  *      rather than a FastCGI process.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_IsCGI(void);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_Init --
  *
  *      Initialize the FCGX library.  Call in multi-threaded apps
  *      before calling FCGX_Accept_r().
  *
  *      Returns 0 upon success.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_Init(void);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_OpenSocket --
  *
  *  Create a FastCGI listen socket.
  *
  *  path is the Unix domain socket (named pipe for WinNT), or a colon
  *  followed by a port number.  e.g. "/tmp/fastcgi/mysocket", ":5000"
  *
  *  backlog is the listen queue depth used in the listen() call.
  *
  *  Returns the socket's file descriptor or -1 on error.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_OpenSocket(const char *path, int backlog);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_InitRequest --
  *
  *  Initialize a FCGX_Request for use with FCGX_Accept_r().
  *
  *  sock is a file descriptor returned by FCGX_OpenSocket() or 0 (default).
  *  The only supported flag at this time is FCGI_FAIL_ON_INTR.
  *
  *  Returns 0 upon success.
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_InitRequest(FCGX_Request *request, int sock, int flags);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_Accept_r --
  *
  *      Accept a new request (multi-thread safe).  Be sure to call
  *  FCGX_Init() first.
  *
  * Results:
  *  0 for successful call, -1 for error.
  *
  * Side effects:
  *
  *      Finishes the request accepted by (and frees any
  *      storage allocated by) the previous call to FCGX_Accept.
  *      Creates input, output, and error streams and
  *      assigns them to *in, *out, and *err respectively.
  *      Creates a parameters data structure to be accessed
  *      via getenv(3) (if assigned to environ) or by FCGX_GetParam
  *      and assigns it to *envp.
  *
  *      DO NOT retain pointers to the envp array or any strings
  *      contained in it (e.g. to the result of calling FCGX_GetParam),
  *      since these will be freed by the next call to FCGX_Finish
  *      or FCGX_Accept.
  *
  *  DON'T use the FCGX_Request, its structure WILL change.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_Accept_r(FCGX_Request *request);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_Finish_r --
  *
  *      Finish the request (multi-thread safe).
  *
  * Side effects:
  *
  *      Finishes the request accepted by (and frees any
  *      storage allocated by) the previous call to FCGX_Accept.
  *
  *      DO NOT retain pointers to the envp array or any strings
  *      contained in it (e.g. to the result of calling FCGX_GetParam),
  *      since these will be freed by the next call to FCGX_Finish
  *      or FCGX_Accept.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI void FCGX_Finish_r(FCGX_Request *request);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_Free --
  *
  *      Free the memory and, if close is true, 
  *      IPC FD associated with the request (multi-thread safe).
  *
  *----------------------------------------------------------------------
  */
 DLLAPI void FCGX_Free(FCGX_Request * request, int close);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_Accept --
  *
  *      Accept a new request (NOT multi-thread safe).
  *
  * Results:
  *  0 for successful call, -1 for error.
  *
  * Side effects:
  *
  *      Finishes the request accepted by (and frees any
  *      storage allocated by) the previous call to FCGX_Accept.
  *      Creates input, output, and error streams and
  *      assigns them to *in, *out, and *err respectively.
  *      Creates a parameters data structure to be accessed
  *      via getenv(3) (if assigned to environ) or by FCGX_GetParam
  *      and assigns it to *envp.
  *
  *      DO NOT retain pointers to the envp array or any strings
  *      contained in it (e.g. to the result of calling FCGX_GetParam),
  *      since these will be freed by the next call to FCGX_Finish
  *      or FCGX_Accept.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_Accept(
         FCGX_Stream **in,
         FCGX_Stream **out,
         FCGX_Stream **err,
         FCGX_ParamArray *envp);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_Finish --
  *
  *      Finish the current request (NOT multi-thread safe).
  *
  * Side effects:
  *
  *      Finishes the request accepted by (and frees any
  *      storage allocated by) the previous call to FCGX_Accept.
  *
  *      DO NOT retain pointers to the envp array or any strings
  *      contained in it (e.g. to the result of calling FCGX_GetParam),
  *      since these will be freed by the next call to FCGX_Finish
  *      or FCGX_Accept.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI void FCGX_Finish(void);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_StartFilterData --
  *
  *      stream is an input stream for a FCGI_FILTER request.
  *      stream is positioned at EOF on FCGI_STDIN.
  *      Repositions stream to the start of FCGI_DATA.
  *      If the preconditions are not met (e.g. FCGI_STDIN has not
  *      been read to EOF) sets the stream error code to
  *      FCGX_CALL_SEQ_ERROR.
  *
  * Results:
  *      0 for a normal return, < 0 for error
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_StartFilterData(FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_SetExitStatus --
  *
  *      Sets the exit status for stream's 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
  *      SetExitStatus several times during a request; the last call
  *      before the request ends determines the value.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI void FCGX_SetExitStatus(int status, FCGX_Stream *stream);
 
 /*
  *======================================================================
  * Parameters
  *======================================================================
  */
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_GetParam -- obtain value of FCGI parameter in environment
  *
  *
  * Results:
  *  Value bound to name, NULL if name not present in the
  *      environment envp.  Caller must not mutate the result
  *      or retain it past the end of this request.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI char *FCGX_GetParam(const char *name, FCGX_ParamArray envp);
 
 /*
  *======================================================================
  * Readers
  *======================================================================
  */
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_GetChar --
  *
  *      Reads a byte from the input stream and returns it.
  *
  * Results:
  *  The byte, or EOF (-1) if the end of input has been reached.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_GetChar(FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_UnGetChar --
  *
  *      Pushes back the character c onto the input stream.  One
  *      character of pushback is guaranteed once a character
  *      has been read.  No pushback is possible for EOF.
  *
  * Results:
  *  Returns c if the pushback succeeded, EOF if not.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_UnGetChar(int c, FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_GetStr --
  *
  *      Reads up to n consecutive bytes from the input stream
  *      into the character array str.  Performs no interpretation
  *      of the input bytes.
  *
  * Results:
  *  Number of bytes read.  If result is smaller than n,
  *      the end of input has been reached.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_GetStr(char *str, int n, FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_GetLine --
  *
  *      Reads up to n-1 consecutive bytes from the input stream
  *      into the character array str.  Stops before n-1 bytes
  *      have been read if '\n' or EOF is read.  The terminating '\n'
  *      is copied to str.  After copying the last byte into str,
  *      stores a '\0' terminator.
  *
  * Results:
  *  NULL if EOF is the first thing read from the input stream,
  *      str otherwise.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI char *FCGX_GetLine(char *str, int n, FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_HasSeenEOF --
  *
  *      Returns EOF if end-of-file has been detected while reading
  *      from stream; otherwise returns 0.
  *
  *      Note that FCGX_HasSeenEOF(s) may return 0, yet an immediately
  *      following FCGX_GetChar(s) may return EOF.  This function, like
  *      the standard C stdio function feof, does not provide the
  *      ability to peek ahead.
  *
  * Results:
  *  EOF if end-of-file has been detected, 0 if not.
  *
  *----------------------------------------------------------------------
  */
 
 DLLAPI  int FCGX_HasSeenEOF(FCGX_Stream *stream);
 
 /*
  *======================================================================
  * Writers
  *======================================================================
  */
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_PutChar --
  *
  *      Writes a byte to the output stream.
  *
  * Results:
  *  The byte, or EOF (-1) if an error occurred.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_PutChar(int c, FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_PutStr --
  *
  *      Writes n consecutive bytes from the character array str
  *      into the output stream.  Performs no interpretation
  *      of the output bytes.
  *
  * Results:
  *      Number of bytes written (n) for normal return,
  *      EOF (-1) if an error occurred.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_PutStr(const char *str, int n, FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_PutS --
  *
  *      Writes a null-terminated character string to the output stream.
  *
  * Results:
  *      number of bytes written for normal return,
  *      EOF (-1) if an error occurred.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_PutS(const char *str, FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_FPrintF, FCGX_VFPrintF --
  *
  *      Performs printf-style output formatting and writes the results
  *      to the output stream.
  *
  * Results:
  *      number of bytes written for normal return,
  *      EOF (-1) if an error occurred.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_FPrintF(FCGX_Stream *stream, const char *format, ...);
 
 DLLAPI int FCGX_VFPrintF(FCGX_Stream *stream, const char *format, va_list arg);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_FFlush --
  *
  *      Flushes any buffered output.
  *
  *      Server-push is a legitimate application of FCGX_FFlush.
  *      Otherwise, FCGX_FFlush is not very useful, since FCGX_Accept
  *      does it implicitly.  Calling FCGX_FFlush in non-push applications
  *      results in extra writes and therefore reduces performance.
  *
  * Results:
  *      EOF (-1) if an error occurred.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_FFlush(FCGX_Stream *stream);
 
 /*
  *======================================================================
  * Both Readers and Writers
  *======================================================================
  */
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_FClose --
  *
  *      Closes the stream.  For writers, flushes any buffered
  *      output.
  *
  *      Close is not a very useful operation since FCGX_Accept
  *      does it implicitly.  Closing the out stream before the
  *      err stream results in an extra write if there's nothing
  *      in the err stream, and therefore reduces performance.
  *
  * Results:
  *      EOF (-1) if an error occurred.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_FClose(FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_GetError --
  *
  *      Return the stream error code.  0 means no error, > 0
  *      is an errno(2) error, < 0 is an FastCGI error.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI int FCGX_GetError(FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_ClearError --
  *
  *      Clear the stream error code and end-of-file indication.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI void FCGX_ClearError(FCGX_Stream *stream);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_CreateWriter --
  *
  *      Create a FCGX_Stream (used by cgi-fcgi).  This shouldn't 
  *      be needed by a FastCGI applictaion.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI FCGX_Stream *FCGX_CreateWriter(
         int socket,
         int requestId,
         int bufflen,
         int streamType);
 
 /*
  *----------------------------------------------------------------------
  *
  * FCGX_FreeStream --
  *
  *      Free a FCGX_Stream (used by cgi-fcgi).  This shouldn't 
  *      be needed by a FastCGI applictaion.
  *
  *----------------------------------------------------------------------
  */
 DLLAPI void FCGX_FreeStream(FCGX_Stream **stream);
 
 /* ----------------------------------------------------------------------
  *
  *  Prevent the lib from accepting any new requests.  Signal handler safe.
  *
  * ----------------------------------------------------------------------
  */
 DLLAPI void FCGX_ShutdownPending(void);
 
 
 /*
  *  Attach/Detach an accepted request from its listen socket.
  *  XXX This is not fully implemented at this time (patch welcome).
  */
 DLLAPI int FCGX_Attach(FCGX_Request * r);
 DLLAPI int FCGX_Detach(FCGX_Request * r);
 
 
 #if defined (__cplusplus) || defined (c_plusplus)
 } /* terminate extern "C" { */
 #endif
 
 #endif  /* _FCGIAPP_H */

This page was automatically generated by the 2.3.5 LXR engine. The LXR team