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.5 2000/11/05 17:09:36 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 #ifdef _WIN32
  30
  31 #ifndef DLLAPI
  32 #define DLLAPI __declspec(dllimport)
  33 #endif
  34
  35 #else  /* !_WIN32 */
  36
  37 #define DLLAPI
  38
  39 #endif /* !_WIN32 */
  40
  41 /*
  42  * Error codes.  Assigned to avoid conflict with EOF and errno(2).
  43  */
  44 #define FCGX_UNSUPPORTED_VERSION -2
  45 #define FCGX_PROTOCOL_ERROR -3
  46 #define FCGX_PARAMS_ERROR -4
  47 #define FCGX_CALL_SEQ_ERROR -5
  48
  49 /*
  50  * This structure defines the state of a FastCGI stream.
  51  * Streams are modeled after the FILE type defined in stdio.h.
  52  * (We wouldn't need our own if platform vendors provided a
  53  * standard way to subclass theirs.)
  54  * The state of a stream is private and should only be accessed
  55  * by the procedures defined below.
  56  */
  57 typedef struct FCGX_Stream {
  58     unsigned char *rdNext;    /* reader: first valid byte
  59                                * writer: equals stop */
  60     unsigned char *wrNext;    /* writer: first free byte
  61                                * reader: equals stop */
  62     unsigned char *stop;      /* reader: last valid byte + 1
  63                                * writer: last free byte + 1 */
  64     unsigned char *stopUnget; /* reader: first byte of current buffer
  65                                * fragment, for ungetc
  66                                * writer: undefined */
  67     int isReader;
  68     int isClosed;
  69     int wasFCloseCalled;
  70     int FCGI_errno;                /* error status */
  71     void (*fillBuffProc) (struct FCGX_Stream *stream);
  72     void (*emptyBuffProc) (struct FCGX_Stream *stream, int doClose);
  73     void *data;
  74 } FCGX_Stream;
  75
  76 /*
  77  * An environment (as defined by environ(7)): A NULL-terminated array
  78  * of strings, each string having the form name=value.
  79  */
  80 typedef char **FCGX_ParamArray;
  81
  82 /*
  83  * FCGX_Request Flags
  84  *
  85  * Setting FCGI_FAIL_ACCEPT_ON_INTR prevents FCGX_Accept() from
  86  * restarting upon being interrupted.
  87  */
  88 #define FCGI_FAIL_ACCEPT_ON_INTR        1
  89
  90 /*
  91  * FCGX_Request -- State associated with a request.
  92  *
  93  * Its exposed for API simplicity, I expect parts of it to change!
  94  */
  95 typedef struct FCGX_Request {
  96     int requestId;            /* valid if isBeginProcessed */
  97     int role;
  98     FCGX_Stream *in;
  99     FCGX_Stream *out;
 100     FCGX_Stream *err;
 101         char **envp;
 102
 103         /* Don't use anything below here */
 104
 105     struct Params *paramsPtr;
 106     int ipcFd;               /* < 0 means no connection */
 107     int isBeginProcessed;     /* FCGI_BEGIN_REQUEST seen */
 108     int keepConnection;       /* don't close ipcFd at end of request */
 109     int appStatus;
 110     int nWriters;             /* number of open writers (0..2) */
 111         int flags;
 112         int listen_sock;
 113 } FCGX_Request;
 114
 115 \f
 116 /*
 117  *======================================================================
 118  * Control
 119  *======================================================================
 120  */
 121
 122 /*
 123  *----------------------------------------------------------------------
 124  *
 125  * FCGX_IsCGI --
 126  *
 127  *      Returns TRUE iff this process appears to be a CGI process
 128  *      rather than a FastCGI process.
 129  *
 130  *----------------------------------------------------------------------
 131  */
 132 DLLAPI int FCGX_IsCGI(void);
 133
 134 /*
 135  *----------------------------------------------------------------------
 136  *
 137  * FCGX_Init --
 138  *
 139  *      Initialize the FCGX library.  Call in multi-threaded apps
 140  *      before calling FCGX_Accept_r().
 141  *
 142  *      Returns 0 upon success.
 143  *
 144  *----------------------------------------------------------------------
 145  */
 146 DLLAPI int FCGX_Init(void);
 147
 148 /*
 149  *----------------------------------------------------------------------
 150  *
 151  * FCGX_OpenSocket --
 152  *
 153  *      Create a FastCGI listen socket.
 154  *
 155  *      path is the Unix domain socket (named pipe for WinNT), or a colon
 156  *      followed by a port number.  e.g. "/tmp/fastcgi/mysocket", ":5000"
 157  *
 158  *      backlog is the listen queue depth used in the listen() call.
 159  *
 160  *  Returns the socket's file descriptor or -1 on error.
 161  *
 162  *----------------------------------------------------------------------
 163  */
 164 DLLAPI int FCGX_OpenSocket(const char *path, int backlog);
 165
 166 /*
 167  *----------------------------------------------------------------------
 168  *
 169  * FCGX_InitRequest --
 170  *
 171  *      Initialize a FCGX_Request for use with FCGX_Accept_r().
 172  *
 173  *      sock is a file descriptor returned by FCGX_OpenSocket() or 0 (default).
 174  *      The only supported flag at this time is FCGI_FAIL_ON_INTR.
 175  *
 176  *      Returns 0 upon success.
 177  *----------------------------------------------------------------------
 178  */
 179 DLLAPI int FCGX_InitRequest(FCGX_Request *request, int sock, int flags);
 180
 181 /*
 182  *----------------------------------------------------------------------
 183  *
 184  * FCGX_Accept_r --
 185  *
 186  *      Accept a new request (multi-thread safe).  Be sure to call
 187  *      FCGX_Init() first.
 188  *
 189  * Results:
 190  *      0 for successful call, -1 for error.
 191  *
 192  * Side effects:
 193  *
 194  *      Finishes the request accepted by (and frees any
 195  *      storage allocated by) the previous call to FCGX_Accept.
 196  *      Creates input, output, and error streams and
 197  *      assigns them to *in, *out, and *err respectively.
 198  *      Creates a parameters data structure to be accessed
 199  *      via getenv(3) (if assigned to environ) or by FCGX_GetParam
 200  *      and assigns it to *envp.
 201  *
 202  *      DO NOT retain pointers to the envp array or any strings
 203  *      contained in it (e.g. to the result of calling FCGX_GetParam),
 204  *      since these will be freed by the next call to FCGX_Finish
 205  *      or FCGX_Accept.
 206  *
 207  *      DON'T use the FCGX_Request, its structure WILL change.
 208  *
 209  *----------------------------------------------------------------------
 210  */
 211 DLLAPI int FCGX_Accept_r(FCGX_Request *request);
 212
 213 /*
 214  *----------------------------------------------------------------------
 215  *
 216  * FCGX_Finish_r --
 217  *
 218  *      Finish the request (multi-thread safe).
 219  *
 220  * Side effects:
 221  *
 222  *      Finishes the request accepted by (and frees any
 223  *      storage allocated by) the previous call to FCGX_Accept.
 224  *
 225  *      DO NOT retain pointers to the envp array or any strings
 226  *      contained in it (e.g. to the result of calling FCGX_GetParam),
 227  *      since these will be freed by the next call to FCGX_Finish
 228  *      or FCGX_Accept.
 229  *
 230  *----------------------------------------------------------------------
 231  */
 232 DLLAPI void FCGX_Finish_r(FCGX_Request *request);
 233
 234 /*
 235  *----------------------------------------------------------------------
 236  *
 237  * FCGX_Free --
 238  *
 239  *      Free the memory and IPC FD associated with the request (multi-thread safe).
 240  *
 241  *----------------------------------------------------------------------
 242  */
 243 DLLAPI void FCGX_Free(FCGX_Request * request);
 244
 245 /*
 246  *----------------------------------------------------------------------
 247  *
 248  * FCGX_Accept --
 249  *
 250  *      Accept a new request (NOT multi-thread safe).
 251  *
 252  * Results:
 253  *      0 for successful call, -1 for error.
 254  *
 255  * Side effects:
 256  *
 257  *      Finishes the request accepted by (and frees any
 258  *      storage allocated by) the previous call to FCGX_Accept.
 259  *      Creates input, output, and error streams and
 260  *      assigns them to *in, *out, and *err respectively.
 261  *      Creates a parameters data structure to be accessed
 262  *      via getenv(3) (if assigned to environ) or by FCGX_GetParam
 263  *      and assigns it to *envp.
 264  *
 265  *      DO NOT retain pointers to the envp array or any strings
 266  *      contained in it (e.g. to the result of calling FCGX_GetParam),
 267  *      since these will be freed by the next call to FCGX_Finish
 268  *      or FCGX_Accept.
 269  *
 270  *----------------------------------------------------------------------
 271  */
 272 DLLAPI int FCGX_Accept(
 273         FCGX_Stream **in,
 274         FCGX_Stream **out,
 275         FCGX_Stream **err,
 276         FCGX_ParamArray *envp);
 277
 278 /*
 279  *----------------------------------------------------------------------
 280  *
 281  * FCGX_Finish --
 282  *
 283  *      Finish the current request (NOT multi-thread safe).
 284  *
 285  * Side effects:
 286  *
 287  *      Finishes the request accepted by (and frees any
 288  *      storage allocated by) the previous call to FCGX_Accept.
 289  *
 290  *      DO NOT retain pointers to the envp array or any strings
 291  *      contained in it (e.g. to the result of calling FCGX_GetParam),
 292  *      since these will be freed by the next call to FCGX_Finish
 293  *      or FCGX_Accept.
 294  *
 295  *----------------------------------------------------------------------
 296  */
 297 DLLAPI void FCGX_Finish(void);
 298
 299 /*
 300  *----------------------------------------------------------------------
 301  *
 302  * FCGX_StartFilterData --
 303  *
 304  *      stream is an input stream for a FCGI_FILTER request.
 305  *      stream is positioned at EOF on FCGI_STDIN.
 306  *      Repositions stream to the start of FCGI_DATA.
 307  *      If the preconditions are not met (e.g. FCGI_STDIN has not
 308  *      been read to EOF) sets the stream error code to
 309  *      FCGX_CALL_SEQ_ERROR.
 310  *
 311  * Results:
 312  *      0 for a normal return, < 0 for error
 313  *
 314  *----------------------------------------------------------------------
 315  */
 316 DLLAPI int FCGX_StartFilterData(FCGX_Stream *stream);
 317
 318 /*
 319  *----------------------------------------------------------------------
 320  *
 321  * FCGX_SetExitStatus --
 322  *
 323  *      Sets the exit status for stream's request. The exit status
 324  *      is the status code the request would have exited with, had
 325  *      the request been run as a CGI program.  You can call
 326  *      SetExitStatus several times during a request; the last call
 327  *      before the request ends determines the value.
 328  *
 329  *----------------------------------------------------------------------
 330  */
 331 DLLAPI void FCGX_SetExitStatus(int status, FCGX_Stream *stream);
 332 \f
 333 /*
 334  *======================================================================
 335  * Parameters
 336  *======================================================================
 337  */
 338
 339 /*
 340  *----------------------------------------------------------------------
 341  *
 342  * FCGX_GetParam -- obtain value of FCGI parameter in environment
 343  *
 344  *
 345  * Results:
 346  *      Value bound to name, NULL if name not present in the
 347  *      environment envp.  Caller must not mutate the result
 348  *      or retain it past the end of this request.
 349  *
 350  *----------------------------------------------------------------------
 351  */
 352 DLLAPI char *FCGX_GetParam(const char *name, FCGX_ParamArray envp);
 353 \f
 354 /*
 355  *======================================================================
 356  * Readers
 357  *======================================================================
 358  */
 359
 360 /*
 361  *----------------------------------------------------------------------
 362  *
 363  * FCGX_GetChar --
 364  *
 365  *      Reads a byte from the input stream and returns it.
 366  *
 367  * Results:
 368  *      The byte, or EOF (-1) if the end of input has been reached.
 369  *
 370  *----------------------------------------------------------------------
 371  */
 372 DLLAPI int FCGX_GetChar(FCGX_Stream *stream);
 373
 374 /*
 375  *----------------------------------------------------------------------
 376  *
 377  * FCGX_UnGetChar --
 378  *
 379  *      Pushes back the character c onto the input stream.  One
 380  *      character of pushback is guaranteed once a character
 381  *      has been read.  No pushback is possible for EOF.
 382  *
 383  * Results:
 384  *      Returns c if the pushback succeeded, EOF if not.
 385  *
 386  *----------------------------------------------------------------------
 387  */
 388 DLLAPI int FCGX_UnGetChar(int c, FCGX_Stream *stream);
 389
 390 /*
 391  *----------------------------------------------------------------------
 392  *
 393  * FCGX_GetStr --
 394  *
 395  *      Reads up to n consecutive bytes from the input stream
 396  *      into the character array str.  Performs no interpretation
 397  *      of the input bytes.
 398  *
 399  * Results:
 400  *      Number of bytes read.  If result is smaller than n,
 401  *      the end of input has been reached.
 402  *
 403  *----------------------------------------------------------------------
 404  */
 405 DLLAPI int FCGX_GetStr(char *str, int n, FCGX_Stream *stream);
 406
 407 /*
 408  *----------------------------------------------------------------------
 409  *
 410  * FCGX_GetLine --
 411  *
 412  *      Reads up to n-1 consecutive bytes from the input stream
 413  *      into the character array str.  Stops before n-1 bytes
 414  *      have been read if '\n' or EOF is read.  The terminating '\n'
 415  *      is copied to str.  After copying the last byte into str,
 416  *      stores a '\0' terminator.
 417  *
 418  * Results:
 419  *      NULL if EOF is the first thing read from the input stream,
 420  *      str otherwise.
 421  *
 422  *----------------------------------------------------------------------
 423  */
 424 DLLAPI char *FCGX_GetLine(char *str, int n, FCGX_Stream *stream);
 425
 426 /*
 427  *----------------------------------------------------------------------
 428  *
 429  * FCGX_HasSeenEOF --
 430  *
 431  *      Returns EOF if end-of-file has been detected while reading
 432  *      from stream; otherwise returns 0.
 433  *
 434  *      Note that FCGX_HasSeenEOF(s) may return 0, yet an immediately
 435  *      following FCGX_GetChar(s) may return EOF.  This function, like
 436  *      the standard C stdio function feof, does not provide the
 437  *      ability to peek ahead.
 438  *
 439  * Results:
 440  *      EOF if end-of-file has been detected, 0 if not.
 441  *
 442  *----------------------------------------------------------------------
 443  */
 444
 445 DLLAPI  int FCGX_HasSeenEOF(FCGX_Stream *stream);
 446 \f
 447 /*
 448  *======================================================================
 449  * Writers
 450  *======================================================================
 451  */
 452
 453 /*
 454  *----------------------------------------------------------------------
 455  *
 456  * FCGX_PutChar --
 457  *
 458  *      Writes a byte to the output stream.
 459  *
 460  * Results:
 461  *      The byte, or EOF (-1) if an error occurred.
 462  *
 463  *----------------------------------------------------------------------
 464  */
 465 DLLAPI int FCGX_PutChar(int c, FCGX_Stream *stream);
 466
 467 /*
 468  *----------------------------------------------------------------------
 469  *
 470  * FCGX_PutStr --
 471  *
 472  *      Writes n consecutive bytes from the character array str
 473  *      into the output stream.  Performs no interpretation
 474  *      of the output bytes.
 475  *
 476  * Results:
 477  *      Number of bytes written (n) for normal return,
 478  *      EOF (-1) if an error occurred.
 479  *
 480  *----------------------------------------------------------------------
 481  */
 482 DLLAPI int FCGX_PutStr(const char *str, int n, FCGX_Stream *stream);
 483
 484 /*
 485  *----------------------------------------------------------------------
 486  *
 487  * FCGX_PutS --
 488  *
 489  *      Writes a null-terminated character string to the output stream.
 490  *
 491  * Results:
 492  *      number of bytes written for normal return,
 493  *      EOF (-1) if an error occurred.
 494  *
 495  *----------------------------------------------------------------------
 496  */
 497 DLLAPI int FCGX_PutS(const char *str, FCGX_Stream *stream);
 498
 499 /*
 500  *----------------------------------------------------------------------
 501  *
 502  * FCGX_FPrintF, FCGX_VFPrintF --
 503  *
 504  *      Performs printf-style output formatting and writes the results
 505  *      to the output stream.
 506  *
 507  * Results:
 508  *      number of bytes written for normal return,
 509  *      EOF (-1) if an error occurred.
 510  *
 511  *----------------------------------------------------------------------
 512  */
 513 DLLAPI int FCGX_FPrintF(FCGX_Stream *stream, const char *format, ...);
 514
 515 DLLAPI int FCGX_VFPrintF(FCGX_Stream *stream, const char *format, va_list arg);
 516
 517 /*
 518  *----------------------------------------------------------------------
 519  *
 520  * FCGX_FFlush --
 521  *
 522  *      Flushes any buffered output.
 523  *
 524  *      Server-push is a legitimate application of FCGX_FFlush.
 525  *      Otherwise, FCGX_FFlush is not very useful, since FCGX_Accept
 526  *      does it implicitly.  Calling FCGX_FFlush in non-push applications
 527  *      results in extra writes and therefore reduces performance.
 528  *
 529  * Results:
 530  *      EOF (-1) if an error occurred.
 531  *
 532  *----------------------------------------------------------------------
 533  */
 534 DLLAPI int FCGX_FFlush(FCGX_Stream *stream);
 535 \f
 536 /*
 537  *======================================================================
 538  * Both Readers and Writers
 539  *======================================================================
 540  */
 541
 542 /*
 543  *----------------------------------------------------------------------
 544  *
 545  * FCGX_FClose --
 546  *
 547  *      Closes the stream.  For writers, flushes any buffered
 548  *      output.
 549  *
 550  *      Close is not a very useful operation since FCGX_Accept
 551  *      does it implicitly.  Closing the out stream before the
 552  *      err stream results in an extra write if there's nothing
 553  *      in the err stream, and therefore reduces performance.
 554  *
 555  * Results:
 556  *      EOF (-1) if an error occurred.
 557  *
 558  *----------------------------------------------------------------------
 559  */
 560 DLLAPI int FCGX_FClose(FCGX_Stream *stream);
 561
 562 /*
 563  *----------------------------------------------------------------------
 564  *
 565  * FCGX_GetError --
 566  *
 567  *      Return the stream error code.  0 means no error, > 0
 568  *      is an errno(2) error, < 0 is an FastCGI error.
 569  *
 570  *----------------------------------------------------------------------
 571  */
 572 DLLAPI int FCGX_GetError(FCGX_Stream *stream);
 573
 574 /*
 575  *----------------------------------------------------------------------
 576  *
 577  * FCGX_ClearError --
 578  *
 579  *      Clear the stream error code and end-of-file indication.
 580  *
 581  *----------------------------------------------------------------------
 582  */
 583 DLLAPI void FCGX_ClearError(FCGX_Stream *stream);
 584
 585
 586 #if defined (__cplusplus) || defined (c_plusplus)
 587 } /* terminate extern "C" { */
 588 #endif
 589
 590 #endif  /* _FCGIAPP_H */