4 * Definitions for FastCGI application server programs
7 * Copyright (c) 1996 Open Market, Inc.
9 * See the file "LICENSE.TERMS" for information on usage and redistribution
10 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
12 * $Id: fcgiapp.h,v 1.2 1999/07/26 04:28:10 roberts Exp $
18 #ifndef TCL_LIBRARY /* Hack to see if we are building TCL since TCL
19 * needs varargs not stdarg
23 #define DLLAPI __declspec(dllimport)
32 #endif /* TCL_LIBARARY */
33 #include "fcgi_config.h"
35 #if defined (c_plusplus) || defined (__cplusplus)
40 * Error codes. Assigned to avoid conflict with EOF and errno(2).
42 #define FCGX_UNSUPPORTED_VERSION -2
43 #define FCGX_PROTOCOL_ERROR -3
44 #define FCGX_PARAMS_ERROR -4
45 #define FCGX_CALL_SEQ_ERROR -5
48 * This structure defines the state of a FastCGI stream.
49 * Streams are modeled after the FILE type defined in stdio.h.
50 * (We wouldn't need our own if platform vendors provided a
51 * standard way to subclass theirs.)
52 * The state of a stream is private and should only be accessed
53 * by the procedures defined below.
55 typedef struct FCGX_Stream {
56 unsigned char *rdNext; /* reader: first valid byte
57 * writer: equals stop */
58 unsigned char *wrNext; /* writer: first free byte
59 * reader: equals stop */
60 unsigned char *stop; /* reader: last valid byte + 1
61 * writer: last free byte + 1 */
62 unsigned char *stopUnget; /* reader: first byte of current buffer
63 * fragment, for ungetc
64 * writer: undefined */
68 int FCGI_errno; /* error status */
69 void (*fillBuffProc) (struct FCGX_Stream *stream);
70 void (*emptyBuffProc) (struct FCGX_Stream *stream, int doClose);
75 * An environment (as defined by environ(7)): A NULL-terminated array
76 * of strings, each string having the form name=value.
78 typedef char **FCGX_ParamArray;
81 * State associated with a request.
83 * Its exposed for API simplicity, DON'T use it - it WILL change!
85 typedef struct FCGX_Request {
86 int ipcFd; /* < 0 means no connection */
87 int isBeginProcessed; /* FCGI_BEGIN_REQUEST seen */
88 int requestId; /* valid if isBeginProcessed */
89 int keepConnection; /* don't close ipcFd at end of request */
92 int nWriters; /* number of open writers (0..2) */
93 FCGX_Stream *inStream;
94 FCGX_Stream *outStream;
95 FCGX_Stream *errStream;
96 struct Params *paramsPtr;
101 *======================================================================
103 *======================================================================
107 *----------------------------------------------------------------------
111 * Returns TRUE iff this process appears to be a CGI process
112 * rather than a FastCGI process.
114 *----------------------------------------------------------------------
116 DLLAPI int FCGX_IsCGI(void);
119 *----------------------------------------------------------------------
123 * Initialize the FCGX library. Call in multi-threaded apps
124 * before calling FCGX_Accept_r().
126 * Returns 0 upon success.
128 *----------------------------------------------------------------------
130 DLLAPI int FCGX_Init(void);
133 *----------------------------------------------------------------------
135 * FCGX_InitRequest --
137 * Initialize a FCGX_Request for use with FCGX_Accept_r().
139 *----------------------------------------------------------------------
141 DLLAPI void FCGX_InitRequest(FCGX_Request *request);
144 *----------------------------------------------------------------------
148 * Accept a new request (multi-thread safe). Be sure to call
152 * 0 for successful call, -1 for error.
156 * Finishes the request accepted by (and frees any
157 * storage allocated by) the previous call to FCGX_Accept.
158 * Creates input, output, and error streams and
159 * assigns them to *in, *out, and *err respectively.
160 * Creates a parameters data structure to be accessed
161 * via getenv(3) (if assigned to environ) or by FCGX_GetParam
162 * and assigns it to *envp.
164 * DO NOT retain pointers to the envp array or any strings
165 * contained in it (e.g. to the result of calling FCGX_GetParam),
166 * since these will be freed by the next call to FCGX_Finish
169 * DON'T use the FCGX_Request, its structure WILL change.
171 *----------------------------------------------------------------------
173 DLLAPI int FCGX_Accept_r(
177 FCGX_ParamArray *envp,
178 FCGX_Request *request);
181 *----------------------------------------------------------------------
185 * Finish the request (multi-thread safe).
189 * Finishes the request accepted by (and frees any
190 * storage allocated by) the previous call to FCGX_Accept.
192 * DO NOT retain pointers to the envp array or any strings
193 * contained in it (e.g. to the result of calling FCGX_GetParam),
194 * since these will be freed by the next call to FCGX_Finish
197 *----------------------------------------------------------------------
199 DLLAPI void FCGX_Finish_r(FCGX_Request *request);
202 *----------------------------------------------------------------------
206 * Accept a new request (NOT multi-thread safe).
209 * 0 for successful call, -1 for error.
213 * Finishes the request accepted by (and frees any
214 * storage allocated by) the previous call to FCGX_Accept.
215 * Creates input, output, and error streams and
216 * assigns them to *in, *out, and *err respectively.
217 * Creates a parameters data structure to be accessed
218 * via getenv(3) (if assigned to environ) or by FCGX_GetParam
219 * and assigns it to *envp.
221 * DO NOT retain pointers to the envp array or any strings
222 * contained in it (e.g. to the result of calling FCGX_GetParam),
223 * since these will be freed by the next call to FCGX_Finish
226 *----------------------------------------------------------------------
228 DLLAPI int FCGX_Accept(
232 FCGX_ParamArray *envp);
235 *----------------------------------------------------------------------
239 * Finish the current request (NOT multi-thread safe).
243 * Finishes the request accepted by (and frees any
244 * storage allocated by) the previous call to FCGX_Accept.
246 * DO NOT retain pointers to the envp array or any strings
247 * contained in it (e.g. to the result of calling FCGX_GetParam),
248 * since these will be freed by the next call to FCGX_Finish
251 *----------------------------------------------------------------------
253 DLLAPI void FCGX_Finish(void);
256 *----------------------------------------------------------------------
258 * FCGX_StartFilterData --
260 * stream is an input stream for a FCGI_FILTER request.
261 * stream is positioned at EOF on FCGI_STDIN.
262 * Repositions stream to the start of FCGI_DATA.
263 * If the preconditions are not met (e.g. FCGI_STDIN has not
264 * been read to EOF) sets the stream error code to
265 * FCGX_CALL_SEQ_ERROR.
268 * 0 for a normal return, < 0 for error
270 *----------------------------------------------------------------------
272 DLLAPI int FCGX_StartFilterData(FCGX_Stream *stream);
275 *----------------------------------------------------------------------
277 * FCGX_SetExitStatus --
279 * Sets the exit status for stream's request. The exit status
280 * is the status code the request would have exited with, had
281 * the request been run as a CGI program. You can call
282 * SetExitStatus several times during a request; the last call
283 * before the request ends determines the value.
285 *----------------------------------------------------------------------
287 DLLAPI void FCGX_SetExitStatus(int status, FCGX_Stream *stream);
290 *======================================================================
292 *======================================================================
296 *----------------------------------------------------------------------
298 * FCGX_GetParam -- obtain value of FCGI parameter in environment
302 * Value bound to name, NULL if name not present in the
303 * environment envp. Caller must not mutate the result
304 * or retain it past the end of this request.
306 *----------------------------------------------------------------------
308 DLLAPI char *FCGX_GetParam(const char *name, FCGX_ParamArray envp);
311 *======================================================================
313 *======================================================================
317 *----------------------------------------------------------------------
321 * Reads a byte from the input stream and returns it.
324 * The byte, or EOF (-1) if the end of input has been reached.
326 *----------------------------------------------------------------------
328 DLLAPI int FCGX_GetChar(FCGX_Stream *stream);
331 *----------------------------------------------------------------------
335 * Pushes back the character c onto the input stream. One
336 * character of pushback is guaranteed once a character
337 * has been read. No pushback is possible for EOF.
340 * Returns c if the pushback succeeded, EOF if not.
342 *----------------------------------------------------------------------
344 DLLAPI int FCGX_UnGetChar(int c, FCGX_Stream *stream);
347 *----------------------------------------------------------------------
351 * Reads up to n consecutive bytes from the input stream
352 * into the character array str. Performs no interpretation
353 * of the input bytes.
356 * Number of bytes read. If result is smaller than n,
357 * the end of input has been reached.
359 *----------------------------------------------------------------------
361 DLLAPI int FCGX_GetStr(char *str, int n, FCGX_Stream *stream);
364 *----------------------------------------------------------------------
368 * Reads up to n-1 consecutive bytes from the input stream
369 * into the character array str. Stops before n-1 bytes
370 * have been read if '\n' or EOF is read. The terminating '\n'
371 * is copied to str. After copying the last byte into str,
372 * stores a '\0' terminator.
375 * NULL if EOF is the first thing read from the input stream,
378 *----------------------------------------------------------------------
380 DLLAPI char *FCGX_GetLine(char *str, int n, FCGX_Stream *stream);
383 *----------------------------------------------------------------------
387 * Returns EOF if end-of-file has been detected while reading
388 * from stream; otherwise returns 0.
390 * Note that FCGX_HasSeenEOF(s) may return 0, yet an immediately
391 * following FCGX_GetChar(s) may return EOF. This function, like
392 * the standard C stdio function feof, does not provide the
393 * ability to peek ahead.
396 * EOF if end-of-file has been detected, 0 if not.
398 *----------------------------------------------------------------------
401 DLLAPI int FCGX_HasSeenEOF(FCGX_Stream *stream);
404 *======================================================================
406 *======================================================================
410 *----------------------------------------------------------------------
414 * Writes a byte to the output stream.
417 * The byte, or EOF (-1) if an error occurred.
419 *----------------------------------------------------------------------
421 DLLAPI int FCGX_PutChar(int c, FCGX_Stream *stream);
424 *----------------------------------------------------------------------
428 * Writes n consecutive bytes from the character array str
429 * into the output stream. Performs no interpretation
430 * of the output bytes.
433 * Number of bytes written (n) for normal return,
434 * EOF (-1) if an error occurred.
436 *----------------------------------------------------------------------
438 DLLAPI int FCGX_PutStr(const char *str, int n, FCGX_Stream *stream);
441 *----------------------------------------------------------------------
445 * Writes a null-terminated character string to the output stream.
448 * number of bytes written for normal return,
449 * EOF (-1) if an error occurred.
451 *----------------------------------------------------------------------
453 DLLAPI int FCGX_PutS(const char *str, FCGX_Stream *stream);
456 *----------------------------------------------------------------------
458 * FCGX_FPrintF, FCGX_VFPrintF --
460 * Performs printf-style output formatting and writes the results
461 * to the output stream.
464 * number of bytes written for normal return,
465 * EOF (-1) if an error occurred.
467 *----------------------------------------------------------------------
469 DLLAPI int FCGX_FPrintF(FCGX_Stream *stream, const char *format, ...);
471 DLLAPI int FCGX_VFPrintF(FCGX_Stream *stream, const char *format, va_list arg);
474 *----------------------------------------------------------------------
478 * Flushes any buffered output.
480 * Server-push is a legitimate application of FCGX_FFlush.
481 * Otherwise, FCGX_FFlush is not very useful, since FCGX_Accept
482 * does it implicitly. Calling FCGX_FFlush in non-push applications
483 * results in extra writes and therefore reduces performance.
486 * EOF (-1) if an error occurred.
488 *----------------------------------------------------------------------
490 DLLAPI int FCGX_FFlush(FCGX_Stream *stream);
493 *======================================================================
494 * Both Readers and Writers
495 *======================================================================
499 *----------------------------------------------------------------------
503 * Closes the stream. For writers, flushes any buffered
506 * Close is not a very useful operation since FCGX_Accept
507 * does it implicitly. Closing the out stream before the
508 * err stream results in an extra write if there's nothing
509 * in the err stream, and therefore reduces performance.
512 * EOF (-1) if an error occurred.
514 *----------------------------------------------------------------------
516 DLLAPI int FCGX_FClose(FCGX_Stream *stream);
519 *----------------------------------------------------------------------
523 * Return the stream error code. 0 means no error, > 0
524 * is an errno(2) error, < 0 is an FastCGI error.
526 *----------------------------------------------------------------------
528 DLLAPI int FCGX_GetError(FCGX_Stream *stream);
531 *----------------------------------------------------------------------
535 * Clear the stream error code and end-of-file indication.
537 *----------------------------------------------------------------------
539 DLLAPI void FCGX_ClearError(FCGX_Stream *stream);
542 #if defined (__cplusplus) || defined (c_plusplus)
543 } /* terminate extern "C" { */
546 #endif /* _FCGIAPP_H */