doc/cgi-fcgi.1

   1 NAME
   2      cgi-fcgi   - bridge from CGI to FastCGI
   3
   4 SYNOPSIS
   5      cgi-fcgi -f cmdPath
   6      cgi-fcgi -bind  -connect connName
   7      cgi-fcgi -start -connect connName appPath [nServers]
   8      cgi-fcgi -connect connName appPath [nServers]
   9
  10 DESCRIPTION
  11      cgi-fcgi is a CGI/1.1 program that communicates with an
  12      already-running FastCGI application in order to respond to an
  13      HTTP request.  cgi-fcgi is also capable of starting a FastCGI
  14      application.
  15
  16      When you invoke cgi-fcgi as
  17
  18          cgi-fcgi -f cmdPath
  19
  20      then cgi-fcgi opens the file at cmdPath and reads its
  21      arguments from that file.  cgi-fcgi will skip lines
  22      that begin with the comment character #.  The first
  23      non-comment line should contain valid arguments in
  24      one of the other three forms.
  25
  26      The -f form of cgi-fcgi is designed for Unix systems
  27      whose exec(2) family of system calls supports the execution of
  28      command interpreter files.  For instance, if a file with
  29      execute permission contains the text
  30
  31          #! /bin/cgi-fcgi -f
  32          -connect /httpd/root/sock/app /httpd/root/bin/app
  33
  34      the effect is the same as executing
  35
  36          /bin/cgi-fcgi -connect /httpd/root/sock/app /httpd/root/bin/app
  37
  38      When you invoke cgi-fcgi as
  39
  40          cgi-fcgi -bind -connect connName
  41
  42      the connName argument is either the path name of a Unix domain
  43      listening socket or a host:port pair.  If connName contains
  44      a colon, it is assumed to be host:port.  cgi-fcgi performs
  45      a connect(2) using connName.  If the connect succeeds, cgi-fcgi
  46      forwards the CGI environment variables and stdin data to the
  47      FastCGI application, and forwards the stdout and stderr data from
  48      the application to cgi-fcgi's stdout (most likely connected to
  49      a Web server).  When the FastCGI application signals the end of
  50      its response, cgi-fcgi flushes its buffers and
  51      exits, and the Web server completes the http response.
  52
  53      When you invoke cgi-fcgi as
  54
  55          cgi-fcgi -start -connect connName appPath [nServers]
  56
  57      then cgi-fcgi performs the function of starting one or more
  58      FastCGI application processes.  The connName argument specifies
  59      either the path name of the Unix domain listening socket that
  60      cgi-fcgi will create, or is "localhost:NNN" where NNN is the port
  61      number of the TCP/IP listening socket that cgi-fcgi will create
  62      on the local machine.  (cgi-fcgi will not create processes
  63      on remote machines.)  After cgi-fcgi creates the listening socket,
  64      it forks nServers copies of a process running the executable file
  65      appPath.  If nServers is omitted, the effect is as if the value "1"
  66      had been specified.  The processes share the single listening socket.
  67
  68      When you invoke cgi-fcgi as
  69
  70          cgi-fcgi -connect connName appPath [nServers]
  71
  72      cgi-fcgi performs -bind and then, if necssary, performs -start
  73      and repeats the -bind.  That is, cgi-fcgi first operates as if
  74      the command had been
  75
  76          cgi-fcgi -bind -connect connName
  77
  78      If the connect fails, cgi-fcgi tries
  79
  80          cgi-fcgi -start -connect connName appPath [nServers]
  81
  82      and finally retries
  83
  84          cgi-fcgi -bind -connect connName
  85
  86      In this form, cgi-fcgi does not support TCP/IP connections.
  87
  88 ENVIRONMENT VARIABLES
  89      The usual CGI ones, but they are not interpreted by cgi-fcgi.
  90
  91 SEE ALSO
  92      FGCI_accept(3)
  93
  94 BUGS
  95      cgi-fcgi doesn't generate useful HTTP responses in case of error,
  96      and it generates no response at all when run as start-fcgi.
  97
  98      On Digital UNIX 3.0 systems the implementation of Unix Domain
  99      sockets does not work when such sockets are stored on NFS file
 100      systems.  Symptom: cgi-fcgi may core dump or may exit with
 101      status 38.  Work-around: store sockets in local file systems
 102      (/tmp often works) or use TCP/IP.
 103
 104      On AIX systems the implementation of listening sockets
 105      does not support socket sharing, and the standard FastCGI
 106      application libraries can't synchronize access to AIX listening
 107      sockets.  Work-around: Don't use the nServers argument on AIX.
 108
 109 HISTORY
 110      Copyright (c) 1996 Open Market, Inc.
 111      See the file "LICENSE.TERMS" for information on usage and redistribution
 112      of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 113      $Id: cgi-fcgi.1,v 1.1 1997/09/16 15:36:26 stanleyg Exp $