JezK
Edit File: fcgiapp.h
/* * 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 */