initial commit
[fcgi] / include / fcgiapp.h
1 /*
2  * fcgiapp.h --
3  *
4  *      Definitions for FastCGI application server programs
5  *
6  *
7  * Copyright (c) 1996 Open Market, Inc.
8  *
9  * See the file "LICENSE.TERMS" for information on usage and redistribution
10  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
11  *
12  * $Id: fcgiapp.h,v 1.14 2003/06/22 00:16:44 robs Exp $
13  */
14
15 #ifndef _FCGIAPP_H
16 #define _FCGIAPP_H
17
18 /* Hack to see if we are building TCL - TCL needs varargs not stdarg */
19 #ifndef TCL_LIBRARY
20 #include <stdarg.h>
21 #else
22 #include <varargs.h>
23 #endif
24
25 #ifndef DLLAPI
26 #ifdef _WIN32
27 #define DLLAPI __declspec(dllimport)
28 #else
29 #define DLLAPI
30 #endif
31 #endif
32
33 #if defined (c_plusplus) || defined (__cplusplus)
34 extern "C" {
35 #endif
36
37 /*
38  * Error codes.  Assigned to avoid conflict with EOF and errno(2).
39  */
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
44
45 /*
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.
52  */
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 */
63     int isReader;
64     int isClosed;
65     int wasFCloseCalled;
66     int FCGI_errno;                /* error status */
67     void (*fillBuffProc) (struct FCGX_Stream *stream);
68     void (*emptyBuffProc) (struct FCGX_Stream *stream, int doClose);
69     void *data;
70 } FCGX_Stream;
71
72 /*
73  * An environment (as defined by environ(7)): A NULL-terminated array
74  * of strings, each string having the form name=value.
75  */
76 typedef char **FCGX_ParamArray;
77
78 /*
79  * FCGX_Request Flags
80  *
81  * Setting FCGI_FAIL_ACCEPT_ON_INTR prevents FCGX_Accept() from
82  * restarting upon being interrupted.
83  */
84 #define FCGI_FAIL_ACCEPT_ON_INTR        1
85
86 /*
87  * FCGX_Request -- State associated with a request.
88  *
89  * Its exposed for API simplicity, I expect parts of it to change!
90  */
91 typedef struct FCGX_Request {
92     int requestId;            /* valid if isBeginProcessed */
93     int role;
94     FCGX_Stream *in;
95     FCGX_Stream *out;
96     FCGX_Stream *err;
97     char **envp;
98
99     /* Don't use anything below here */
100
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 */
105     int appStatus;
106     int nWriters;             /* number of open writers (0..2) */
107     int flags;
108     int listen_sock;
109     int detached;
110 } FCGX_Request;
111
112 \f
113 /*
114  *======================================================================
115  * Control
116  *======================================================================
117  */
118
119 /*
120  *----------------------------------------------------------------------
121  *
122  * FCGX_IsCGI --
123  *
124  *      Returns TRUE iff this process appears to be a CGI process
125  *      rather than a FastCGI process.
126  *
127  *----------------------------------------------------------------------
128  */
129 DLLAPI int FCGX_IsCGI(void);
130
131 /*
132  *----------------------------------------------------------------------
133  *
134  * FCGX_Init --
135  *
136  *      Initialize the FCGX library.  Call in multi-threaded apps
137  *      before calling FCGX_Accept_r().
138  *
139  *      Returns 0 upon success.
140  *
141  *----------------------------------------------------------------------
142  */
143 DLLAPI int FCGX_Init(void);
144
145 /*
146  *----------------------------------------------------------------------
147  *
148  * FCGX_OpenSocket --
149  *
150  *      Create a FastCGI listen socket.
151  *
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"
154  *
155  *      backlog is the listen queue depth used in the listen() call.
156  *
157  *  Returns the socket's file descriptor or -1 on error.
158  *
159  *----------------------------------------------------------------------
160  */
161 DLLAPI int FCGX_OpenSocket(const char *path, int backlog);
162
163 /*
164  *----------------------------------------------------------------------
165  *
166  * FCGX_InitRequest --
167  *
168  *      Initialize a FCGX_Request for use with FCGX_Accept_r().
169  *
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.
172  *
173  *      Returns 0 upon success.
174  *----------------------------------------------------------------------
175  */
176 DLLAPI int FCGX_InitRequest(FCGX_Request *request, int sock, int flags);
177
178 /*
179  *----------------------------------------------------------------------
180  *
181  * FCGX_Accept_r --
182  *
183  *      Accept a new request (multi-thread safe).  Be sure to call
184  *      FCGX_Init() first.
185  *
186  * Results:
187  *      0 for successful call, -1 for error.
188  *
189  * Side effects:
190  *
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.
198  *
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
202  *      or FCGX_Accept.
203  *
204  *      DON'T use the FCGX_Request, its structure WILL change.
205  *
206  *----------------------------------------------------------------------
207  */
208 DLLAPI int FCGX_Accept_r(FCGX_Request *request);
209
210 /*
211  *----------------------------------------------------------------------
212  *
213  * FCGX_Finish_r --
214  *
215  *      Finish the request (multi-thread safe).
216  *
217  * Side effects:
218  *
219  *      Finishes the request accepted by (and frees any
220  *      storage allocated by) the previous call to FCGX_Accept.
221  *
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
225  *      or FCGX_Accept.
226  *
227  *----------------------------------------------------------------------
228  */
229 DLLAPI void FCGX_Finish_r(FCGX_Request *request);
230
231 /*
232  *----------------------------------------------------------------------
233  *
234  * FCGX_Free --
235  *
236  *      Free the memory and, if close is true, 
237  *          IPC FD associated with the request (multi-thread safe).
238  *
239  *----------------------------------------------------------------------
240  */
241 DLLAPI void FCGX_Free(FCGX_Request * request, int close);
242
243 /*
244  *----------------------------------------------------------------------
245  *
246  * FCGX_Accept --
247  *
248  *      Accept a new request (NOT multi-thread safe).
249  *
250  * Results:
251  *      0 for successful call, -1 for error.
252  *
253  * Side effects:
254  *
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.
262  *
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
266  *      or FCGX_Accept.
267  *
268  *----------------------------------------------------------------------
269  */
270 DLLAPI int FCGX_Accept(
271         FCGX_Stream **in,
272         FCGX_Stream **out,
273         FCGX_Stream **err,
274         FCGX_ParamArray *envp);
275
276 /*
277  *----------------------------------------------------------------------
278  *
279  * FCGX_Finish --
280  *
281  *      Finish the current request (NOT multi-thread safe).
282  *
283  * Side effects:
284  *
285  *      Finishes the request accepted by (and frees any
286  *      storage allocated by) the previous call to FCGX_Accept.
287  *
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
291  *      or FCGX_Accept.
292  *
293  *----------------------------------------------------------------------
294  */
295 DLLAPI void FCGX_Finish(void);
296
297 /*
298  *----------------------------------------------------------------------
299  *
300  * FCGX_StartFilterData --
301  *
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.
308  *
309  * Results:
310  *      0 for a normal return, < 0 for error
311  *
312  *----------------------------------------------------------------------
313  */
314 DLLAPI int FCGX_StartFilterData(FCGX_Stream *stream);
315
316 /*
317  *----------------------------------------------------------------------
318  *
319  * FCGX_SetExitStatus --
320  *
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.
326  *
327  *----------------------------------------------------------------------
328  */
329 DLLAPI void FCGX_SetExitStatus(int status, FCGX_Stream *stream);
330 \f
331 /*
332  *======================================================================
333  * Parameters
334  *======================================================================
335  */
336
337 /*
338  *----------------------------------------------------------------------
339  *
340  * FCGX_GetParam -- obtain value of FCGI parameter in environment
341  *
342  *
343  * Results:
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.
347  *
348  *----------------------------------------------------------------------
349  */
350 DLLAPI char *FCGX_GetParam(const char *name, FCGX_ParamArray envp);
351 \f
352 /*
353  *======================================================================
354  * Readers
355  *======================================================================
356  */
357
358 /*
359  *----------------------------------------------------------------------
360  *
361  * FCGX_GetChar --
362  *
363  *      Reads a byte from the input stream and returns it.
364  *
365  * Results:
366  *      The byte, or EOF (-1) if the end of input has been reached.
367  *
368  *----------------------------------------------------------------------
369  */
370 DLLAPI int FCGX_GetChar(FCGX_Stream *stream);
371
372 /*
373  *----------------------------------------------------------------------
374  *
375  * FCGX_UnGetChar --
376  *
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.
380  *
381  * Results:
382  *      Returns c if the pushback succeeded, EOF if not.
383  *
384  *----------------------------------------------------------------------
385  */
386 DLLAPI int FCGX_UnGetChar(int c, FCGX_Stream *stream);
387
388 /*
389  *----------------------------------------------------------------------
390  *
391  * FCGX_GetStr --
392  *
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.
396  *
397  * Results:
398  *      Number of bytes read.  If result is smaller than n,
399  *      the end of input has been reached.
400  *
401  *----------------------------------------------------------------------
402  */
403 DLLAPI int FCGX_GetStr(char *str, int n, FCGX_Stream *stream);
404
405 /*
406  *----------------------------------------------------------------------
407  *
408  * FCGX_GetLine --
409  *
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.
415  *
416  * Results:
417  *      NULL if EOF is the first thing read from the input stream,
418  *      str otherwise.
419  *
420  *----------------------------------------------------------------------
421  */
422 DLLAPI char *FCGX_GetLine(char *str, int n, FCGX_Stream *stream);
423
424 /*
425  *----------------------------------------------------------------------
426  *
427  * FCGX_HasSeenEOF --
428  *
429  *      Returns EOF if end-of-file has been detected while reading
430  *      from stream; otherwise returns 0.
431  *
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.
436  *
437  * Results:
438  *      EOF if end-of-file has been detected, 0 if not.
439  *
440  *----------------------------------------------------------------------
441  */
442
443 DLLAPI  int FCGX_HasSeenEOF(FCGX_Stream *stream);
444 \f
445 /*
446  *======================================================================
447  * Writers
448  *======================================================================
449  */
450
451 /*
452  *----------------------------------------------------------------------
453  *
454  * FCGX_PutChar --
455  *
456  *      Writes a byte to the output stream.
457  *
458  * Results:
459  *      The byte, or EOF (-1) if an error occurred.
460  *
461  *----------------------------------------------------------------------
462  */
463 DLLAPI int FCGX_PutChar(int c, FCGX_Stream *stream);
464
465 /*
466  *----------------------------------------------------------------------
467  *
468  * FCGX_PutStr --
469  *
470  *      Writes n consecutive bytes from the character array str
471  *      into the output stream.  Performs no interpretation
472  *      of the output bytes.
473  *
474  * Results:
475  *      Number of bytes written (n) for normal return,
476  *      EOF (-1) if an error occurred.
477  *
478  *----------------------------------------------------------------------
479  */
480 DLLAPI int FCGX_PutStr(const char *str, int n, FCGX_Stream *stream);
481
482 /*
483  *----------------------------------------------------------------------
484  *
485  * FCGX_PutS --
486  *
487  *      Writes a null-terminated character string to the output stream.
488  *
489  * Results:
490  *      number of bytes written for normal return,
491  *      EOF (-1) if an error occurred.
492  *
493  *----------------------------------------------------------------------
494  */
495 DLLAPI int FCGX_PutS(const char *str, FCGX_Stream *stream);
496
497 /*
498  *----------------------------------------------------------------------
499  *
500  * FCGX_FPrintF, FCGX_VFPrintF --
501  *
502  *      Performs printf-style output formatting and writes the results
503  *      to the output stream.
504  *
505  * Results:
506  *      number of bytes written for normal return,
507  *      EOF (-1) if an error occurred.
508  *
509  *----------------------------------------------------------------------
510  */
511 DLLAPI int FCGX_FPrintF(FCGX_Stream *stream, const char *format, ...);
512
513 DLLAPI int FCGX_VFPrintF(FCGX_Stream *stream, const char *format, va_list arg);
514
515 /*
516  *----------------------------------------------------------------------
517  *
518  * FCGX_FFlush --
519  *
520  *      Flushes any buffered output.
521  *
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.
526  *
527  * Results:
528  *      EOF (-1) if an error occurred.
529  *
530  *----------------------------------------------------------------------
531  */
532 DLLAPI int FCGX_FFlush(FCGX_Stream *stream);
533 \f
534 /*
535  *======================================================================
536  * Both Readers and Writers
537  *======================================================================
538  */
539
540 /*
541  *----------------------------------------------------------------------
542  *
543  * FCGX_FClose --
544  *
545  *      Closes the stream.  For writers, flushes any buffered
546  *      output.
547  *
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.
552  *
553  * Results:
554  *      EOF (-1) if an error occurred.
555  *
556  *----------------------------------------------------------------------
557  */
558 DLLAPI int FCGX_FClose(FCGX_Stream *stream);
559
560 /*
561  *----------------------------------------------------------------------
562  *
563  * FCGX_GetError --
564  *
565  *      Return the stream error code.  0 means no error, > 0
566  *      is an errno(2) error, < 0 is an FastCGI error.
567  *
568  *----------------------------------------------------------------------
569  */
570 DLLAPI int FCGX_GetError(FCGX_Stream *stream);
571
572 /*
573  *----------------------------------------------------------------------
574  *
575  * FCGX_ClearError --
576  *
577  *      Clear the stream error code and end-of-file indication.
578  *
579  *----------------------------------------------------------------------
580  */
581 DLLAPI void FCGX_ClearError(FCGX_Stream *stream);
582
583 /*
584  *----------------------------------------------------------------------
585  *
586  * FCGX_CreateWriter --
587  *
588  *      Create a FCGX_Stream (used by cgi-fcgi).  This shouldn't 
589  *      be needed by a FastCGI applictaion.
590  *
591  *----------------------------------------------------------------------
592  */
593 DLLAPI FCGX_Stream *FCGX_CreateWriter(
594         int socket,
595         int requestId,
596         int bufflen,
597         int streamType);
598
599 /*
600  *----------------------------------------------------------------------
601  *
602  * FCGX_FreeStream --
603  *
604  *      Free a FCGX_Stream (used by cgi-fcgi).  This shouldn't 
605  *      be needed by a FastCGI applictaion.
606  *
607  *----------------------------------------------------------------------
608  */
609 DLLAPI void FCGX_FreeStream(FCGX_Stream **stream);
610
611 /* ----------------------------------------------------------------------
612  *
613  *  Prevent the lib from accepting any new requests.  Signal handler safe.
614  *
615  * ----------------------------------------------------------------------
616  */
617 DLLAPI void FCGX_ShutdownPending(void);
618
619
620 /*
621  *  Attach/Detach an accepted request from its listen socket.
622  *  XXX This is not fully implemented at this time (patch welcome).
623  */
624 DLLAPI int FCGX_Attach(FCGX_Request * r);
625 DLLAPI int FCGX_Detach(FCGX_Request * r);
626
627
628 #if defined (__cplusplus) || defined (c_plusplus)
629 } /* terminate extern "C" { */
630 #endif
631
632 #endif  /* _FCGIAPP_H */