Commit | Line | Data |
344bf056 |
1 | /* |
0198fd3c |
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 | * |
2a7273a1 |
12 | * $Id: fcgiapp.h,v 1.14 2003/06/22 00:16:44 robs Exp $ |
0198fd3c |
13 | */ |
14 | |
15 | #ifndef _FCGIAPP_H |
16 | #define _FCGIAPP_H |
17 | |
344bf056 |
18 | /* Hack to see if we are building TCL - TCL needs varargs not stdarg */ |
19 | #ifndef TCL_LIBRARY |
0198fd3c |
20 | #include <stdarg.h> |
21 | #else |
22 | #include <varargs.h> |
344bf056 |
23 | #endif |
0198fd3c |
24 | |
1eed8866 |
25 | #ifndef DLLAPI |
26 | #ifdef _WIN32 |
27 | #define DLLAPI __declspec(dllimport) |
28 | #else |
29 | #define DLLAPI |
30 | #endif |
31 | #endif |
32 | |
0198fd3c |
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 | |
5a7cc494 |
78 | /* |
0b7c9662 |
79 | * FCGX_Request Flags |
5a7cc494 |
80 | * |
0b7c9662 |
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! |
5a7cc494 |
90 | */ |
91 | typedef struct FCGX_Request { |
0b7c9662 |
92 | int requestId; /* valid if isBeginProcessed */ |
93 | int role; |
94 | FCGX_Stream *in; |
95 | FCGX_Stream *out; |
96 | FCGX_Stream *err; |
5ac48a20 |
97 | char **envp; |
0b7c9662 |
98 | |
5ac48a20 |
99 | /* Don't use anything below here */ |
0b7c9662 |
100 | |
101 | struct Params *paramsPtr; |
5a7cc494 |
102 | int ipcFd; /* < 0 means no connection */ |
103 | int isBeginProcessed; /* FCGI_BEGIN_REQUEST seen */ |
5a7cc494 |
104 | int keepConnection; /* don't close ipcFd at end of request */ |
5a7cc494 |
105 | int appStatus; |
106 | int nWriters; /* number of open writers (0..2) */ |
5ac48a20 |
107 | int flags; |
108 | int listen_sock; |
2a7273a1 |
109 | int detached; |
5a7cc494 |
110 | } FCGX_Request; |
111 | |
0198fd3c |
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 | * |
5a7cc494 |
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 | * |
0b7c9662 |
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 | * |
5a7cc494 |
166 | * FCGX_InitRequest -- |
167 | * |
0b7c9662 |
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. |
5a7cc494 |
172 | * |
0b7c9662 |
173 | * Returns 0 upon success. |
5a7cc494 |
174 | *---------------------------------------------------------------------- |
175 | */ |
0b7c9662 |
176 | DLLAPI int FCGX_InitRequest(FCGX_Request *request, int sock, int flags); |
5a7cc494 |
177 | |
178 | /* |
179 | *---------------------------------------------------------------------- |
180 | * |
181 | * FCGX_Accept_r -- |
182 | * |
344bf056 |
183 | * Accept a new request (multi-thread safe). Be sure to call |
5a7cc494 |
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 | */ |
0b7c9662 |
208 | DLLAPI int FCGX_Accept_r(FCGX_Request *request); |
5a7cc494 |
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 | * |
8462b1ec |
234 | * FCGX_Free -- |
235 | * |
bef7e0fc |
236 | * Free the memory and, if close is true, |
237 | * IPC FD associated with the request (multi-thread safe). |
8462b1ec |
238 | * |
239 | *---------------------------------------------------------------------- |
240 | */ |
bef7e0fc |
241 | DLLAPI void FCGX_Free(FCGX_Request * request, int close); |
8462b1ec |
242 | |
243 | /* |
244 | *---------------------------------------------------------------------- |
245 | * |
0198fd3c |
246 | * FCGX_Accept -- |
247 | * |
5a7cc494 |
248 | * Accept a new request (NOT multi-thread safe). |
0198fd3c |
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 | * |
5a7cc494 |
281 | * Finish the current request (NOT multi-thread safe). |
0198fd3c |
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: |
344bf056 |
310 | * 0 for a normal return, < 0 for error |
0198fd3c |
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. |
344bf056 |
460 | * |
0198fd3c |
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. |
344bf056 |
477 | * |
0198fd3c |
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. |
344bf056 |
492 | * |
0198fd3c |
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. |
344bf056 |
508 | * |
0198fd3c |
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. |
344bf056 |
529 | * |
0198fd3c |
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. |
344bf056 |
555 | * |
0198fd3c |
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 | |
e4bb1ae0 |
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 | |
6c50b8b4 |
611 | /* ---------------------------------------------------------------------- |
612 | * |
613 | * Prevent the lib from accepting any new requests. Signal handler safe. |
614 | * |
615 | * ---------------------------------------------------------------------- |
616 | */ |
617 | DLLAPI void FCGX_ShutdownPending(void); |
618 | |
2a7273a1 |
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 | |
0198fd3c |
628 | #if defined (__cplusplus) || defined (c_plusplus) |
629 | } /* terminate extern "C" { */ |
630 | #endif |
631 | |
632 | #endif /* _FCGIAPP_H */ |