initial commit
[fcgi] / 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.1.1 1997/09/16 15:36:26 stanleyg Exp $