examples: setsid is now built into htparser.
[ashd.git] / doc / callscgi.doc
... / ...
CommitLineData
1callscgi(1)
2===========
3
4NAME
5----
6callscgi - SCGI request handler for ashd(7)
7
8SYNOPSIS
9--------
10*callscgi* [*-h*] [*-N* 'RETRIES'] [*-i* 'ID'] [*-u* 'UNIXPATH'] [*-t* \[HOST:]'TCPPORT'] ['PROGRAM' ['ARGS'...]]
11
12DESCRIPTION
13-----------
14
15The *callscgi* handler uses SCGI to call an external handler for
16requests. *callscgi* is a persistent handler, as defined in *ashd*(7).
17
18Depending on which arguments are given, *callscgi* will run in one of
19four operating modes.
20
21If an address option is given (see OPTIONS below), but the 'PROGRAM'
22argument is not given, *callscgi* will run in client mode. In client
23mode, *callscgi* will try to connect to a SCGI server listening to the
24given address. If it cannot connect, it will exit, except when failing
25only once, in which case it will retry according to the *-N* option,
26described below.
27
28If no address option is given, but the 'PROGRAM' argument is given,
29*callscgi* will run in anonymous mode. In anonymous mode, *callscgi*
30will create a Unix socket listening on some more-or-less random
31address, and start the given 'PROGRAM', passing the listening socket
32on its standard input, expecting the program to start accepting
33connections on that socket. *callscgi* will then connect to that
34socket for each request. If such a connection is refused, the child
35program will be assumed to have crashed, and *callscgi* will restart
36it. Also in anonymous mode, *callscgi*, will try and kill the child
37program whenever *callscgi* itself exits for whatever reason (commonly
38because its own control socket is closed by its parent handler).
39
40If both an address option and the 'PROGRAM' argument are given, but
41the *-N* option is not given, *callscgi* will run in launching
42mode. In launching mode, *callscgi* will try to connect to a SCGI
43server at the given address, but if (and only if) that fails, it will
44create a socket listening to the given address, and start the given
45'PROGRAM', passing the listening socket on its standard input,
46expecting the program to start accepting connections on that
47socket. Unlike in anonymous mode, *callscgi* will leave any child
48process it has started running even when *callscgi* itself exits.
49
50If both an address option, the 'PROGRAM' argument and the *-N* option
51are given, *callscgi* will run in mixed mode. In mixed mode,
52*callscgi* will try to connect to a SCGI server at the given address,
53but if that fails, it will start the given 'PROGRAM'. Unlike in
54launching mode, however, *callscgi* will not create the listening
55socket itself, but will assume that the 'PROGRAM' will create it
56independently (probably based on any 'ARGS' passed to it). When
57'PROGRAM' is launched, *callscgi* will try to connect to the given
58address once per second, up to 'RETRIES' times. If the connection
59cannot succeed even after 'RETRIES' attempts, *callscgi* will exit.
60
61OPTIONS
62-------
63
64*-h*::
65
66 Print a brief help message to standard output and exit.
67
68*-u* 'UNIXPATH'::
69
70 Use 'UNIXPATH' as the Unix socket address of the SCGI server.
71
72*-t* \[HOST:]'TCPPORT'::
73
74 Use the given TCP/IP address as the SCGI server address. If
75 'HOST' is not given, use `localhost` instead. 'TCPPORT' may be
76 given symbolically.
77
78*-i* 'ID'::
79
80 Use 'ID' to create a reasonably unique pathname to use as the
81 Unix socket address of the SCGI server. This option is mainly
82 intended for use as a convenience in launching mode, where the
83 SCGI server does not need to know the actual address it is
84 listening to (since it gets passed the listening socket on
85 standard input) to start SCGI servers that can persist even if
86 *callscgi* exits for some reason.
87
88*-N* 'RETRIES'::
89
90 In client mode and mixed mode, try to connect 'RETRIES' times,
91 once per second, to the SCGI server before giving up. If both
92 an address option and the 'PROGRAM' argument are given, the
93 presence of the *-N* option determines whether to run in
94 launching mode or mixed mode, as described above.
95
96SIGNALS
97-------
98
99SIGINT, SIGTERM::
100
101 Exit cleanly, sending SIGTERM to any child process started if
102 running in anonymous mode, as described above.
103
104AUTHOR
105------
106Fredrik Tolf <fredrik@dolda2000.com>
107
108SEE ALSO
109--------
110*ashd*(7)