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