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.11 2001/11/17 03:58:30 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\r
  26 #ifdef _WIN32\r
  27 #define DLLAPI __declspec(dllimport)\r
  28 #else\r
  29 #define DLLAPI\r
  30 #endif\r
  31 #endif\r
  32 \r
  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 } FCGX_Request;
 110
 111 \f
 112 /*
 113  *======================================================================
 114  * Control
 115  *======================================================================
 116  */
 117
 118 /*
 119  *----------------------------------------------------------------------
 120  *
 121  * FCGX_IsCGI --
 122  *
 123  *      Returns TRUE iff this process appears to be a CGI process
 124  *      rather than a FastCGI process.
 125  *
 126  *----------------------------------------------------------------------
 127  */
 128 DLLAPI int FCGX_IsCGI(void);
 129
 130 /*
 131  *----------------------------------------------------------------------
 132  *
 133  * FCGX_Init --
 134  *
 135  *      Initialize the FCGX library.  Call in multi-threaded apps
 136  *      before calling FCGX_Accept_r().
 137  *
 138  *      Returns 0 upon success.
 139  *
 140  *----------------------------------------------------------------------
 141  */
 142 DLLAPI int FCGX_Init(void);
 143
 144 /*
 145  *----------------------------------------------------------------------
 146  *
 147  * FCGX_OpenSocket --
 148  *
 149  *      Create a FastCGI listen socket.
 150  *
 151  *      path is the Unix domain socket (named pipe for WinNT), or a colon
 152  *      followed by a port number.  e.g. "/tmp/fastcgi/mysocket", ":5000"
 153  *
 154  *      backlog is the listen queue depth used in the listen() call.
 155  *
 156  *  Returns the socket's file descriptor or -1 on error.
 157  *
 158  *----------------------------------------------------------------------
 159  */
 160 DLLAPI int FCGX_OpenSocket(const char *path, int backlog);
 161
 162 /*
 163  *----------------------------------------------------------------------
 164  *
 165  * FCGX_InitRequest --
 166  *
 167  *      Initialize a FCGX_Request for use with FCGX_Accept_r().
 168  *
 169  *      sock is a file descriptor returned by FCGX_OpenSocket() or 0 (default).
 170  *      The only supported flag at this time is FCGI_FAIL_ON_INTR.
 171  *
 172  *      Returns 0 upon success.
 173  *----------------------------------------------------------------------
 174  */
 175 DLLAPI int FCGX_InitRequest(FCGX_Request *request, int sock, int flags);
 176
 177 /*
 178  *----------------------------------------------------------------------
 179  *
 180  * FCGX_Accept_r --
 181  *
 182  *      Accept a new request (multi-thread safe).  Be sure to call
 183  *      FCGX_Init() first.
 184  *
 185  * Results:
 186  *      0 for successful call, -1 for error.
 187  *
 188  * Side effects:
 189  *
 190  *      Finishes the request accepted by (and frees any
 191  *      storage allocated by) the previous call to FCGX_Accept.
 192  *      Creates input, output, and error streams and
 193  *      assigns them to *in, *out, and *err respectively.
 194  *      Creates a parameters data structure to be accessed
 195  *      via getenv(3) (if assigned to environ) or by FCGX_GetParam
 196  *      and assigns it to *envp.
 197  *
 198  *      DO NOT retain pointers to the envp array or any strings
 199  *      contained in it (e.g. to the result of calling FCGX_GetParam),
 200  *      since these will be freed by the next call to FCGX_Finish
 201  *      or FCGX_Accept.
 202  *
 203  *      DON'T use the FCGX_Request, its structure WILL change.
 204  *
 205  *----------------------------------------------------------------------
 206  */
 207 DLLAPI int FCGX_Accept_r(FCGX_Request *request);
 208
 209 /*
 210  *----------------------------------------------------------------------
 211  *
 212  * FCGX_Finish_r --
 213  *
 214  *      Finish the request (multi-thread safe).
 215  *
 216  * Side effects:
 217  *
 218  *      Finishes the request accepted by (and frees any
 219  *      storage allocated by) the previous call to FCGX_Accept.
 220  *
 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
 224  *      or FCGX_Accept.
 225  *
 226  *----------------------------------------------------------------------
 227  */
 228 DLLAPI void FCGX_Finish_r(FCGX_Request *request);
 229
 230 /*
 231  *----------------------------------------------------------------------
 232  *
 233  * FCGX_Free --
 234  *
 235  *      Free the memory and, if close is true,
 236  *          IPC FD associated with the request (multi-thread safe).
 237  *
 238  *----------------------------------------------------------------------
 239  */
 240 DLLAPI void FCGX_Free(FCGX_Request * request, int close);
 241
 242 /*
 243  *----------------------------------------------------------------------
 244  *
 245  * FCGX_Accept --
 246  *
 247  *      Accept a new request (NOT multi-thread safe).
 248  *
 249  * Results:
 250  *      0 for successful call, -1 for error.
 251  *
 252  * Side effects:
 253  *
 254  *      Finishes the request accepted by (and frees any
 255  *      storage allocated by) the previous call to FCGX_Accept.
 256  *      Creates input, output, and error streams and
 257  *      assigns them to *in, *out, and *err respectively.
 258  *      Creates a parameters data structure to be accessed
 259  *      via getenv(3) (if assigned to environ) or by FCGX_GetParam
 260  *      and assigns it to *envp.
 261  *
 262  *      DO NOT retain pointers to the envp array or any strings
 263  *      contained in it (e.g. to the result of calling FCGX_GetParam),
 264  *      since these will be freed by the next call to FCGX_Finish
 265  *      or FCGX_Accept.
 266  *
 267  *----------------------------------------------------------------------
 268  */
 269 DLLAPI int FCGX_Accept(
 270         FCGX_Stream **in,
 271         FCGX_Stream **out,
 272         FCGX_Stream **err,
 273         FCGX_ParamArray *envp);
 274
 275 /*
 276  *----------------------------------------------------------------------
 277  *
 278  * FCGX_Finish --
 279  *
 280  *      Finish the current request (NOT multi-thread safe).
 281  *
 282  * Side effects:
 283  *
 284  *      Finishes the request accepted by (and frees any
 285  *      storage allocated by) the previous call to FCGX_Accept.
 286  *
 287  *      DO NOT retain pointers to the envp array or any strings
 288  *      contained in it (e.g. to the result of calling FCGX_GetParam),
 289  *      since these will be freed by the next call to FCGX_Finish
 290  *      or FCGX_Accept.
 291  *
 292  *----------------------------------------------------------------------
 293  */
 294 DLLAPI void FCGX_Finish(void);
 295
 296 /*
 297  *----------------------------------------------------------------------
 298  *
 299  * FCGX_StartFilterData --
 300  *
 301  *      stream is an input stream for a FCGI_FILTER request.
 302  *      stream is positioned at EOF on FCGI_STDIN.
 303  *      Repositions stream to the start of FCGI_DATA.
 304  *      If the preconditions are not met (e.g. FCGI_STDIN has not
 305  *      been read to EOF) sets the stream error code to
 306  *      FCGX_CALL_SEQ_ERROR.
 307  *
 308  * Results:
 309  *      0 for a normal return, < 0 for error
 310  *
 311  *----------------------------------------------------------------------
 312  */
 313 DLLAPI int FCGX_StartFilterData(FCGX_Stream *stream);
 314
 315 /*
 316  *----------------------------------------------------------------------
 317  *
 318  * FCGX_SetExitStatus --
 319  *
 320  *      Sets the exit status for stream's request. The exit status
 321  *      is the status code the request would have exited with, had
 322  *      the request been run as a CGI program.  You can call
 323  *      SetExitStatus several times during a request; the last call
 324  *      before the request ends determines the value.
 325  *
 326  *----------------------------------------------------------------------
 327  */
 328 DLLAPI void FCGX_SetExitStatus(int status, FCGX_Stream *stream);
 329 \f
 330 /*
 331  *======================================================================
 332  * Parameters
 333  *======================================================================
 334  */
 335
 336 /*
 337  *----------------------------------------------------------------------
 338  *
 339  * FCGX_GetParam -- obtain value of FCGI parameter in environment
 340  *
 341  *
 342  * Results:
 343  *      Value bound to name, NULL if name not present in the
 344  *      environment envp.  Caller must not mutate the result
 345  *      or retain it past the end of this request.
 346  *
 347  *----------------------------------------------------------------------
 348  */
 349 DLLAPI char *FCGX_GetParam(const char *name, FCGX_ParamArray envp);
 350 \f
 351 /*
 352  *======================================================================
 353  * Readers
 354  *======================================================================
 355  */
 356
 357 /*
 358  *----------------------------------------------------------------------
 359  *
 360  * FCGX_Peek --
 361  *
 362  *      Return the next byte without removing it from the stream.
 363  *
 364  * Results:
 365  *      The byte, or EOF if the end of input has been reached.
 366  *
 367  *----------------------------------------------------------------------
 368  */
 369 DLLAPI int FCGX_Peek(FCGX_Stream * stream);\r
 370
 371 /*
 372  *----------------------------------------------------------------------
 373  *
 374  * FCGX_GetChar --
 375  *
 376  *      Reads a byte from the input stream and returns it.
 377  *
 378  * Results:
 379  *      The byte, or EOF (-1) if the end of input has been reached.
 380  *
 381  *----------------------------------------------------------------------
 382  */
 383 DLLAPI int FCGX_GetChar(FCGX_Stream *stream);
 384
 385 /*
 386  *----------------------------------------------------------------------
 387  *
 388  * FCGX_UnGetChar --
 389  *
 390  *      Pushes back the character c onto the input stream.  One
 391  *      character of pushback is guaranteed once a character
 392  *      has been read.  No pushback is possible for EOF.
 393  *
 394  * Results:
 395  *      Returns c if the pushback succeeded, EOF if not.
 396  *
 397  *----------------------------------------------------------------------
 398  */
 399 DLLAPI int FCGX_UnGetChar(int c, FCGX_Stream *stream);
 400
 401 /*
 402  *----------------------------------------------------------------------
 403  *
 404  * FCGX_GetStr --
 405  *
 406  *      Reads up to n consecutive bytes from the input stream
 407  *      into the character array str.  Performs no interpretation
 408  *      of the input bytes.
 409  *
 410  * Results:
 411  *      Number of bytes read.  If result is smaller than n,
 412  *      the end of input has been reached.
 413  *
 414  *----------------------------------------------------------------------
 415  */
 416 DLLAPI int FCGX_GetStr(char *str, int n, FCGX_Stream *stream);
 417
 418 /*
 419  *----------------------------------------------------------------------
 420  *
 421  * FCGX_GetLine --
 422  *
 423  *      Reads up to n-1 consecutive bytes from the input stream
 424  *      into the character array str.  Stops before n-1 bytes
 425  *      have been read if '\n' or EOF is read.  The terminating '\n'
 426  *      is copied to str.  After copying the last byte into str,
 427  *      stores a '\0' terminator.
 428  *
 429  * Results:
 430  *      NULL if EOF is the first thing read from the input stream,
 431  *      str otherwise.
 432  *
 433  *----------------------------------------------------------------------
 434  */
 435 DLLAPI char *FCGX_GetLine(char *str, int n, FCGX_Stream *stream);
 436
 437 /*
 438  *----------------------------------------------------------------------
 439  *
 440  * FCGX_HasSeenEOF --
 441  *
 442  *      Returns EOF if end-of-file has been detected while reading
 443  *      from stream; otherwise returns 0.
 444  *
 445  *      Note that FCGX_HasSeenEOF(s) may return 0, yet an immediately
 446  *      following FCGX_GetChar(s) may return EOF.  This function, like
 447  *      the standard C stdio function feof, does not provide the
 448  *      ability to peek ahead.
 449  *
 450  * Results:
 451  *      EOF if end-of-file has been detected, 0 if not.
 452  *
 453  *----------------------------------------------------------------------
 454  */
 455
 456 DLLAPI  int FCGX_HasSeenEOF(FCGX_Stream *stream);
 457 \f
 458 /*
 459  *======================================================================
 460  * Writers
 461  *======================================================================
 462  */
 463
 464 /*
 465  *----------------------------------------------------------------------
 466  *
 467  * FCGX_PutChar --
 468  *
 469  *      Writes a byte to the output stream.
 470  *
 471  * Results:
 472  *      The byte, or EOF (-1) if an error occurred.
 473  *
 474  *----------------------------------------------------------------------
 475  */
 476 DLLAPI int FCGX_PutChar(int c, FCGX_Stream *stream);
 477
 478 /*
 479  *----------------------------------------------------------------------
 480  *
 481  * FCGX_PutStr --
 482  *
 483  *      Writes n consecutive bytes from the character array str
 484  *      into the output stream.  Performs no interpretation
 485  *      of the output bytes.
 486  *
 487  * Results:
 488  *      Number of bytes written (n) for normal return,
 489  *      EOF (-1) if an error occurred.
 490  *
 491  *----------------------------------------------------------------------
 492  */
 493 DLLAPI int FCGX_PutStr(const char *str, int n, FCGX_Stream *stream);
 494
 495 /*
 496  *----------------------------------------------------------------------
 497  *
 498  * FCGX_PutS --
 499  *
 500  *      Writes a null-terminated character string to the output stream.
 501  *
 502  * Results:
 503  *      number of bytes written for normal return,
 504  *      EOF (-1) if an error occurred.
 505  *
 506  *----------------------------------------------------------------------
 507  */
 508 DLLAPI int FCGX_PutS(const char *str, FCGX_Stream *stream);
 509
 510 /*
 511  *----------------------------------------------------------------------
 512  *
 513  * FCGX_FPrintF, FCGX_VFPrintF --
 514  *
 515  *      Performs printf-style output formatting and writes the results
 516  *      to the output stream.
 517  *
 518  * Results:
 519  *      number of bytes written for normal return,
 520  *      EOF (-1) if an error occurred.
 521  *
 522  *----------------------------------------------------------------------
 523  */
 524 DLLAPI int FCGX_FPrintF(FCGX_Stream *stream, const char *format, ...);
 525
 526 DLLAPI int FCGX_VFPrintF(FCGX_Stream *stream, const char *format, va_list arg);
 527
 528 /*
 529  *----------------------------------------------------------------------
 530  *
 531  * FCGX_FFlush --
 532  *
 533  *      Flushes any buffered output.
 534  *
 535  *      Server-push is a legitimate application of FCGX_FFlush.
 536  *      Otherwise, FCGX_FFlush is not very useful, since FCGX_Accept
 537  *      does it implicitly.  Calling FCGX_FFlush in non-push applications
 538  *      results in extra writes and therefore reduces performance.
 539  *
 540  * Results:
 541  *      EOF (-1) if an error occurred.
 542  *
 543  *----------------------------------------------------------------------
 544  */
 545 DLLAPI int FCGX_FFlush(FCGX_Stream *stream);
 546 \f
 547 /*
 548  *======================================================================
 549  * Both Readers and Writers
 550  *======================================================================
 551  */
 552
 553 /*
 554  *----------------------------------------------------------------------
 555  *
 556  * FCGX_FClose --
 557  *
 558  *      Closes the stream.  For writers, flushes any buffered
 559  *      output.
 560  *
 561  *      Close is not a very useful operation since FCGX_Accept
 562  *      does it implicitly.  Closing the out stream before the
 563  *      err stream results in an extra write if there's nothing
 564  *      in the err stream, and therefore reduces performance.
 565  *
 566  * Results:
 567  *      EOF (-1) if an error occurred.
 568  *
 569  *----------------------------------------------------------------------
 570  */
 571 DLLAPI int FCGX_FClose(FCGX_Stream *stream);
 572
 573 /*
 574  *----------------------------------------------------------------------
 575  *
 576  * FCGX_GetError --
 577  *
 578  *      Return the stream error code.  0 means no error, > 0
 579  *      is an errno(2) error, < 0 is an FastCGI error.
 580  *
 581  *----------------------------------------------------------------------
 582  */
 583 DLLAPI int FCGX_GetError(FCGX_Stream *stream);
 584
 585 /*
 586  *----------------------------------------------------------------------
 587  *
 588  * FCGX_ClearError --
 589  *
 590  *      Clear the stream error code and end-of-file indication.
 591  *
 592  *----------------------------------------------------------------------
 593  */
 594 DLLAPI void FCGX_ClearError(FCGX_Stream *stream);
 595
 596 /*
 597  *----------------------------------------------------------------------
 598  *
 599  * FCGX_CreateWriter --
 600  *
 601  *      Create a FCGX_Stream (used by cgi-fcgi).  This shouldn't
 602  *      be needed by a FastCGI applictaion.
 603  *
 604  *----------------------------------------------------------------------
 605  */
 606 DLLAPI FCGX_Stream *FCGX_CreateWriter(
 607         int socket,
 608         int requestId,
 609         int bufflen,
 610         int streamType);
 611
 612 /*
 613  *----------------------------------------------------------------------
 614  *
 615  * FCGX_FreeStream --
 616  *
 617  *      Free a FCGX_Stream (used by cgi-fcgi).  This shouldn't
 618  *      be needed by a FastCGI applictaion.
 619  *
 620  *----------------------------------------------------------------------
 621  */
 622 DLLAPI void FCGX_FreeStream(FCGX_Stream **stream);
 623
 624 /* ----------------------------------------------------------------------
 625  *
 626  *  Prevent the lib from accepting any new requests.  Signal handler safe.
 627  *
 628  * ----------------------------------------------------------------------
 629  */
 630 DLLAPI void FCGX_ShutdownPending(void);
 631
 632 #if defined (__cplusplus) || defined (c_plusplus)
 633 } /* terminate extern "C" { */
 634 #endif
 635
 636 #endif  /* _FCGIAPP_H */