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.14 2003/06/22 00:16:44 robs Exp $
18 /* Hack to see if we are building TCL - TCL needs varargs not stdarg */
27 #define DLLAPI __declspec(dllimport)
33 #if defined (c_plusplus) || defined (__cplusplus)
38 * Error codes. Assigned to avoid conflict with EOF and errno(2).
40 #define FCGX_UNSUPPORTED_VERSION -2
41 #define FCGX_PROTOCOL_ERROR -3
42 #define FCGX_PARAMS_ERROR -4
43 #define FCGX_CALL_SEQ_ERROR -5
46 * This structure defines the state of a FastCGI stream.
47 * Streams are modeled after the FILE type defined in stdio.h.
48 * (We wouldn't need our own if platform vendors provided a
49 * standard way to subclass theirs.)
50 * The state of a stream is private and should only be accessed
51 * by the procedures defined below.
53 typedef struct FCGX_Stream {
54 unsigned char *rdNext; /* reader: first valid byte
55 * writer: equals stop */
56 unsigned char *wrNext; /* writer: first free byte
57 * reader: equals stop */
58 unsigned char *stop; /* reader: last valid byte + 1
59 * writer: last free byte + 1 */
60 unsigned char *stopUnget; /* reader: first byte of current buffer
61 * fragment, for ungetc
62 * writer: undefined */
66 int FCGI_errno; /* error status */
67 void (*fillBuffProc) (struct FCGX_Stream *stream);
68 void (*emptyBuffProc) (struct FCGX_Stream *stream, int doClose);
73 * An environment (as defined by environ(7)): A NULL-terminated array
74 * of strings, each string having the form name=value.
76 typedef char **FCGX_ParamArray;
81 * Setting FCGI_FAIL_ACCEPT_ON_INTR prevents FCGX_Accept() from
82 * restarting upon being interrupted.
84 #define FCGI_FAIL_ACCEPT_ON_INTR 1
87 * FCGX_Request -- State associated with a request.
89 * Its exposed for API simplicity, I expect parts of it to change!
91 typedef struct FCGX_Request {
92 int requestId; /* valid if isBeginProcessed */
99 /* Don't use anything below here */
101 struct Params *paramsPtr;
102 int ipcFd; /* < 0 means no connection */
103 int isBeginProcessed; /* FCGI_BEGIN_REQUEST seen */
104 int keepConnection; /* don't close ipcFd at end of request */
106 int nWriters; /* number of open writers (0..2) */
114 *======================================================================
116 *======================================================================
120 *----------------------------------------------------------------------
124 * Returns TRUE iff this process appears to be a CGI process
125 * rather than a FastCGI process.
127 *----------------------------------------------------------------------
129 DLLAPI int FCGX_IsCGI(void);
132 *----------------------------------------------------------------------
136 * Initialize the FCGX library. Call in multi-threaded apps
137 * before calling FCGX_Accept_r().
139 * Returns 0 upon success.
141 *----------------------------------------------------------------------
143 DLLAPI int FCGX_Init(void);
146 *----------------------------------------------------------------------
150 * Create a FastCGI listen socket.
152 * path is the Unix domain socket (named pipe for WinNT), or a colon
153 * followed by a port number. e.g. "/tmp/fastcgi/mysocket", ":5000"
155 * backlog is the listen queue depth used in the listen() call.
157 * Returns the socket's file descriptor or -1 on error.
159 *----------------------------------------------------------------------
161 DLLAPI int FCGX_OpenSocket(const char *path, int backlog);
164 *----------------------------------------------------------------------
166 * FCGX_InitRequest --
168 * Initialize a FCGX_Request for use with FCGX_Accept_r().
170 * sock is a file descriptor returned by FCGX_OpenSocket() or 0 (default).
171 * The only supported flag at this time is FCGI_FAIL_ON_INTR.
173 * Returns 0 upon success.
174 *----------------------------------------------------------------------
176 DLLAPI int FCGX_InitRequest(FCGX_Request *request, int sock, int flags);
179 *----------------------------------------------------------------------
183 * Accept a new request (multi-thread safe). Be sure to call
187 * 0 for successful call, -1 for error.
191 * Finishes the request accepted by (and frees any
192 * storage allocated by) the previous call to FCGX_Accept.
193 * Creates input, output, and error streams and
194 * assigns them to *in, *out, and *err respectively.
195 * Creates a parameters data structure to be accessed
196 * via getenv(3) (if assigned to environ) or by FCGX_GetParam
197 * and assigns it to *envp.
199 * DO NOT retain pointers to the envp array or any strings
200 * contained in it (e.g. to the result of calling FCGX_GetParam),
201 * since these will be freed by the next call to FCGX_Finish
204 * DON'T use the FCGX_Request, its structure WILL change.
206 *----------------------------------------------------------------------
208 DLLAPI int FCGX_Accept_r(FCGX_Request *request);
211 *----------------------------------------------------------------------
215 * Finish the request (multi-thread safe).
219 * Finishes the request accepted by (and frees any
220 * storage allocated by) the previous call to FCGX_Accept.
222 * DO NOT retain pointers to the envp array or any strings
223 * contained in it (e.g. to the result of calling FCGX_GetParam),
224 * since these will be freed by the next call to FCGX_Finish
227 *----------------------------------------------------------------------
229 DLLAPI void FCGX_Finish_r(FCGX_Request *request);
232 *----------------------------------------------------------------------
236 * Free the memory and, if close is true,
237 * IPC FD associated with the request (multi-thread safe).
239 *----------------------------------------------------------------------
241 DLLAPI void FCGX_Free(FCGX_Request * request, int close);
244 *----------------------------------------------------------------------
248 * Accept a new request (NOT multi-thread safe).
251 * 0 for successful call, -1 for error.
255 * Finishes the request accepted by (and frees any
256 * storage allocated by) the previous call to FCGX_Accept.
257 * Creates input, output, and error streams and
258 * assigns them to *in, *out, and *err respectively.
259 * Creates a parameters data structure to be accessed
260 * via getenv(3) (if assigned to environ) or by FCGX_GetParam
261 * and assigns it to *envp.
263 * DO NOT retain pointers to the envp array or any strings
264 * contained in it (e.g. to the result of calling FCGX_GetParam),
265 * since these will be freed by the next call to FCGX_Finish
268 *----------------------------------------------------------------------
270 DLLAPI int FCGX_Accept(
274 FCGX_ParamArray *envp);
277 *----------------------------------------------------------------------
281 * Finish the current request (NOT multi-thread safe).
285 * Finishes the request accepted by (and frees any
286 * storage allocated by) the previous call to FCGX_Accept.
288 * DO NOT retain pointers to the envp array or any strings
289 * contained in it (e.g. to the result of calling FCGX_GetParam),
290 * since these will be freed by the next call to FCGX_Finish
293 *----------------------------------------------------------------------
295 DLLAPI void FCGX_Finish(void);
298 *----------------------------------------------------------------------
300 * FCGX_StartFilterData --
302 * stream is an input stream for a FCGI_FILTER request.
303 * stream is positioned at EOF on FCGI_STDIN.
304 * Repositions stream to the start of FCGI_DATA.
305 * If the preconditions are not met (e.g. FCGI_STDIN has not
306 * been read to EOF) sets the stream error code to
307 * FCGX_CALL_SEQ_ERROR.
310 * 0 for a normal return, < 0 for error
312 *----------------------------------------------------------------------
314 DLLAPI int FCGX_StartFilterData(FCGX_Stream *stream);
317 *----------------------------------------------------------------------
319 * FCGX_SetExitStatus --
321 * Sets the exit status for stream's request. The exit status
322 * is the status code the request would have exited with, had
323 * the request been run as a CGI program. You can call
324 * SetExitStatus several times during a request; the last call
325 * before the request ends determines the value.
327 *----------------------------------------------------------------------
329 DLLAPI void FCGX_SetExitStatus(int status, FCGX_Stream *stream);
332 *======================================================================
334 *======================================================================
338 *----------------------------------------------------------------------
340 * FCGX_GetParam -- obtain value of FCGI parameter in environment
344 * Value bound to name, NULL if name not present in the
345 * environment envp. Caller must not mutate the result
346 * or retain it past the end of this request.
348 *----------------------------------------------------------------------
350 DLLAPI char *FCGX_GetParam(const char *name, FCGX_ParamArray envp);
353 *======================================================================
355 *======================================================================
359 *----------------------------------------------------------------------
363 * Reads a byte from the input stream and returns it.
366 * The byte, or EOF (-1) if the end of input has been reached.
368 *----------------------------------------------------------------------
370 DLLAPI int FCGX_GetChar(FCGX_Stream *stream);
373 *----------------------------------------------------------------------
377 * Pushes back the character c onto the input stream. One
378 * character of pushback is guaranteed once a character
379 * has been read. No pushback is possible for EOF.
382 * Returns c if the pushback succeeded, EOF if not.
384 *----------------------------------------------------------------------
386 DLLAPI int FCGX_UnGetChar(int c, FCGX_Stream *stream);
389 *----------------------------------------------------------------------
393 * Reads up to n consecutive bytes from the input stream
394 * into the character array str. Performs no interpretation
395 * of the input bytes.
398 * Number of bytes read. If result is smaller than n,
399 * the end of input has been reached.
401 *----------------------------------------------------------------------
403 DLLAPI int FCGX_GetStr(char *str, int n, FCGX_Stream *stream);
406 *----------------------------------------------------------------------
410 * Reads up to n-1 consecutive bytes from the input stream
411 * into the character array str. Stops before n-1 bytes
412 * have been read if '\n' or EOF is read. The terminating '\n'
413 * is copied to str. After copying the last byte into str,
414 * stores a '\0' terminator.
417 * NULL if EOF is the first thing read from the input stream,
420 *----------------------------------------------------------------------
422 DLLAPI char *FCGX_GetLine(char *str, int n, FCGX_Stream *stream);
425 *----------------------------------------------------------------------
429 * Returns EOF if end-of-file has been detected while reading
430 * from stream; otherwise returns 0.
432 * Note that FCGX_HasSeenEOF(s) may return 0, yet an immediately
433 * following FCGX_GetChar(s) may return EOF. This function, like
434 * the standard C stdio function feof, does not provide the
435 * ability to peek ahead.
438 * EOF if end-of-file has been detected, 0 if not.
440 *----------------------------------------------------------------------
443 DLLAPI int FCGX_HasSeenEOF(FCGX_Stream *stream);
446 *======================================================================
448 *======================================================================
452 *----------------------------------------------------------------------
456 * Writes a byte to the output stream.
459 * The byte, or EOF (-1) if an error occurred.
461 *----------------------------------------------------------------------
463 DLLAPI int FCGX_PutChar(int c, FCGX_Stream *stream);
466 *----------------------------------------------------------------------
470 * Writes n consecutive bytes from the character array str
471 * into the output stream. Performs no interpretation
472 * of the output bytes.
475 * Number of bytes written (n) for normal return,
476 * EOF (-1) if an error occurred.
478 *----------------------------------------------------------------------
480 DLLAPI int FCGX_PutStr(const char *str, int n, FCGX_Stream *stream);
483 *----------------------------------------------------------------------
487 * Writes a null-terminated character string to the output stream.
490 * number of bytes written for normal return,
491 * EOF (-1) if an error occurred.
493 *----------------------------------------------------------------------
495 DLLAPI int FCGX_PutS(const char *str, FCGX_Stream *stream);
498 *----------------------------------------------------------------------
500 * FCGX_FPrintF, FCGX_VFPrintF --
502 * Performs printf-style output formatting and writes the results
503 * to the output stream.
506 * number of bytes written for normal return,
507 * EOF (-1) if an error occurred.
509 *----------------------------------------------------------------------
511 DLLAPI int FCGX_FPrintF(FCGX_Stream *stream, const char *format, ...);
513 DLLAPI int FCGX_VFPrintF(FCGX_Stream *stream, const char *format, va_list arg);
516 *----------------------------------------------------------------------
520 * Flushes any buffered output.
522 * Server-push is a legitimate application of FCGX_FFlush.
523 * Otherwise, FCGX_FFlush is not very useful, since FCGX_Accept
524 * does it implicitly. Calling FCGX_FFlush in non-push applications
525 * results in extra writes and therefore reduces performance.
528 * EOF (-1) if an error occurred.
530 *----------------------------------------------------------------------
532 DLLAPI int FCGX_FFlush(FCGX_Stream *stream);
535 *======================================================================
536 * Both Readers and Writers
537 *======================================================================
541 *----------------------------------------------------------------------
545 * Closes the stream. For writers, flushes any buffered
548 * Close is not a very useful operation since FCGX_Accept
549 * does it implicitly. Closing the out stream before the
550 * err stream results in an extra write if there's nothing
551 * in the err stream, and therefore reduces performance.
554 * EOF (-1) if an error occurred.
556 *----------------------------------------------------------------------
558 DLLAPI int FCGX_FClose(FCGX_Stream *stream);
561 *----------------------------------------------------------------------
565 * Return the stream error code. 0 means no error, > 0
566 * is an errno(2) error, < 0 is an FastCGI error.
568 *----------------------------------------------------------------------
570 DLLAPI int FCGX_GetError(FCGX_Stream *stream);
573 *----------------------------------------------------------------------
577 * Clear the stream error code and end-of-file indication.
579 *----------------------------------------------------------------------
581 DLLAPI void FCGX_ClearError(FCGX_Stream *stream);
584 *----------------------------------------------------------------------
586 * FCGX_CreateWriter --
588 * Create a FCGX_Stream (used by cgi-fcgi). This shouldn't
589 * be needed by a FastCGI applictaion.
591 *----------------------------------------------------------------------
593 DLLAPI FCGX_Stream *FCGX_CreateWriter(
600 *----------------------------------------------------------------------
604 * Free a FCGX_Stream (used by cgi-fcgi). This shouldn't
605 * be needed by a FastCGI applictaion.
607 *----------------------------------------------------------------------
609 DLLAPI void FCGX_FreeStream(FCGX_Stream **stream);
611 /* ----------------------------------------------------------------------
613 * Prevent the lib from accepting any new requests. Signal handler safe.
615 * ----------------------------------------------------------------------
617 DLLAPI void FCGX_ShutdownPending(void);
621 * Attach/Detach an accepted request from its listen socket.
622 * XXX This is not fully implemented at this time (patch welcome).
624 DLLAPI int FCGX_Attach(FCGX_Request * r);
625 DLLAPI int FCGX_Detach(FCGX_Request * r);
628 #if defined (__cplusplus) || defined (c_plusplus)
629 } /* terminate extern "C" { */
632 #endif /* _FCGIAPP_H */