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.8 2001/06/22 14:19:23 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 #if defined (c_plusplus) || defined (__cplusplus)
  26 extern "C" {
  27 #endif
  28
  29 #ifndef DLLAPI
  30 #ifdef _WIN32
  31 #define DLLAPI __declspec(dllimport)
  32 #else
  33 #define DLLAPI
  34 #endif
  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_GetChar --
 361  *
 362  *      Reads a byte from the input stream and returns it.
 363  *
 364  * Results:
 365  *      The byte, or EOF (-1) if the end of input has been reached.
 366  *
 367  *----------------------------------------------------------------------
 368  */
 369 DLLAPI int FCGX_GetChar(FCGX_Stream *stream);
 370
 371 /*
 372  *----------------------------------------------------------------------
 373  *
 374  * FCGX_UnGetChar --
 375  *
 376  *      Pushes back the character c onto the input stream.  One
 377  *      character of pushback is guaranteed once a character
 378  *      has been read.  No pushback is possible for EOF.
 379  *
 380  * Results:
 381  *      Returns c if the pushback succeeded, EOF if not.
 382  *
 383  *----------------------------------------------------------------------
 384  */
 385 DLLAPI int FCGX_UnGetChar(int c, FCGX_Stream *stream);
 386
 387 /*
 388  *----------------------------------------------------------------------
 389  *
 390  * FCGX_GetStr --
 391  *
 392  *      Reads up to n consecutive bytes from the input stream
 393  *      into the character array str.  Performs no interpretation
 394  *      of the input bytes.
 395  *
 396  * Results:
 397  *      Number of bytes read.  If result is smaller than n,
 398  *      the end of input has been reached.
 399  *
 400  *----------------------------------------------------------------------
 401  */
 402 DLLAPI int FCGX_GetStr(char *str, int n, FCGX_Stream *stream);
 403
 404 /*
 405  *----------------------------------------------------------------------
 406  *
 407  * FCGX_GetLine --
 408  *
 409  *      Reads up to n-1 consecutive bytes from the input stream
 410  *      into the character array str.  Stops before n-1 bytes
 411  *      have been read if '\n' or EOF is read.  The terminating '\n'
 412  *      is copied to str.  After copying the last byte into str,
 413  *      stores a '\0' terminator.
 414  *
 415  * Results:
 416  *      NULL if EOF is the first thing read from the input stream,
 417  *      str otherwise.
 418  *
 419  *----------------------------------------------------------------------
 420  */
 421 DLLAPI char *FCGX_GetLine(char *str, int n, FCGX_Stream *stream);
 422
 423 /*
 424  *----------------------------------------------------------------------
 425  *
 426  * FCGX_HasSeenEOF --
 427  *
 428  *      Returns EOF if end-of-file has been detected while reading
 429  *      from stream; otherwise returns 0.
 430  *
 431  *      Note that FCGX_HasSeenEOF(s) may return 0, yet an immediately
 432  *      following FCGX_GetChar(s) may return EOF.  This function, like
 433  *      the standard C stdio function feof, does not provide the
 434  *      ability to peek ahead.
 435  *
 436  * Results:
 437  *      EOF if end-of-file has been detected, 0 if not.
 438  *
 439  *----------------------------------------------------------------------
 440  */
 441
 442 DLLAPI  int FCGX_HasSeenEOF(FCGX_Stream *stream);
 443 \f
 444 /*
 445  *======================================================================
 446  * Writers
 447  *======================================================================
 448  */
 449
 450 /*
 451  *----------------------------------------------------------------------
 452  *
 453  * FCGX_PutChar --
 454  *
 455  *      Writes a byte to the output stream.
 456  *
 457  * Results:
 458  *      The byte, or EOF (-1) if an error occurred.
 459  *
 460  *----------------------------------------------------------------------
 461  */
 462 DLLAPI int FCGX_PutChar(int c, FCGX_Stream *stream);
 463
 464 /*
 465  *----------------------------------------------------------------------
 466  *
 467  * FCGX_PutStr --
 468  *
 469  *      Writes n consecutive bytes from the character array str
 470  *      into the output stream.  Performs no interpretation
 471  *      of the output bytes.
 472  *
 473  * Results:
 474  *      Number of bytes written (n) for normal return,
 475  *      EOF (-1) if an error occurred.
 476  *
 477  *----------------------------------------------------------------------
 478  */
 479 DLLAPI int FCGX_PutStr(const char *str, int n, FCGX_Stream *stream);
 480
 481 /*
 482  *----------------------------------------------------------------------
 483  *
 484  * FCGX_PutS --
 485  *
 486  *      Writes a null-terminated character string to the output stream.
 487  *
 488  * Results:
 489  *      number of bytes written for normal return,
 490  *      EOF (-1) if an error occurred.
 491  *
 492  *----------------------------------------------------------------------
 493  */
 494 DLLAPI int FCGX_PutS(const char *str, FCGX_Stream *stream);
 495
 496 /*
 497  *----------------------------------------------------------------------
 498  *
 499  * FCGX_FPrintF, FCGX_VFPrintF --
 500  *
 501  *      Performs printf-style output formatting and writes the results
 502  *      to the output stream.
 503  *
 504  * Results:
 505  *      number of bytes written for normal return,
 506  *      EOF (-1) if an error occurred.
 507  *
 508  *----------------------------------------------------------------------
 509  */
 510 DLLAPI int FCGX_FPrintF(FCGX_Stream *stream, const char *format, ...);
 511
 512 DLLAPI int FCGX_VFPrintF(FCGX_Stream *stream, const char *format, va_list arg);
 513
 514 /*
 515  *----------------------------------------------------------------------
 516  *
 517  * FCGX_FFlush --
 518  *
 519  *      Flushes any buffered output.
 520  *
 521  *      Server-push is a legitimate application of FCGX_FFlush.
 522  *      Otherwise, FCGX_FFlush is not very useful, since FCGX_Accept
 523  *      does it implicitly.  Calling FCGX_FFlush in non-push applications
 524  *      results in extra writes and therefore reduces performance.
 525  *
 526  * Results:
 527  *      EOF (-1) if an error occurred.
 528  *
 529  *----------------------------------------------------------------------
 530  */
 531 DLLAPI int FCGX_FFlush(FCGX_Stream *stream);
 532 \f
 533 /*
 534  *======================================================================
 535  * Both Readers and Writers
 536  *======================================================================
 537  */
 538
 539 /*
 540  *----------------------------------------------------------------------
 541  *
 542  * FCGX_FClose --
 543  *
 544  *      Closes the stream.  For writers, flushes any buffered
 545  *      output.
 546  *
 547  *      Close is not a very useful operation since FCGX_Accept
 548  *      does it implicitly.  Closing the out stream before the
 549  *      err stream results in an extra write if there's nothing
 550  *      in the err stream, and therefore reduces performance.
 551  *
 552  * Results:
 553  *      EOF (-1) if an error occurred.
 554  *
 555  *----------------------------------------------------------------------
 556  */
 557 DLLAPI int FCGX_FClose(FCGX_Stream *stream);
 558
 559 /*
 560  *----------------------------------------------------------------------
 561  *
 562  * FCGX_GetError --
 563  *
 564  *      Return the stream error code.  0 means no error, > 0
 565  *      is an errno(2) error, < 0 is an FastCGI error.
 566  *
 567  *----------------------------------------------------------------------
 568  */
 569 DLLAPI int FCGX_GetError(FCGX_Stream *stream);
 570
 571 /*
 572  *----------------------------------------------------------------------
 573  *
 574  * FCGX_ClearError --
 575  *
 576  *      Clear the stream error code and end-of-file indication.
 577  *
 578  *----------------------------------------------------------------------
 579  */
 580 DLLAPI void FCGX_ClearError(FCGX_Stream *stream);
 581
 582 /*
 583  *----------------------------------------------------------------------
 584  *
 585  * FCGX_CreateWriter --
 586  *
 587  *      Create a FCGX_Stream (used by cgi-fcgi).  This shouldn't
 588  *      be needed by a FastCGI applictaion.
 589  *
 590  *----------------------------------------------------------------------
 591  */
 592 DLLAPI FCGX_Stream *FCGX_CreateWriter(
 593         int socket,
 594         int requestId,
 595         int bufflen,
 596         int streamType);
 597
 598 /*
 599  *----------------------------------------------------------------------
 600  *
 601  * FCGX_FreeStream --
 602  *
 603  *      Free a FCGX_Stream (used by cgi-fcgi).  This shouldn't
 604  *      be needed by a FastCGI applictaion.
 605  *
 606  *----------------------------------------------------------------------
 607  */
 608 DLLAPI void FCGX_FreeStream(FCGX_Stream **stream);
 609
 610
 611 #if defined (__cplusplus) || defined (c_plusplus)
 612 } /* terminate extern "C" { */
 613 #endif
 614
 615 #endif  /* _FCGIAPP_H */