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 */