The callscgi handler uses SCGI to call an external handler for requests. callscgi is a persistent handler, as defined in ashd(7).
Depending on which arguments are given, callscgi will run in one of four operating modes.
If an address option is given (see OPTIONS below), but the PROGRAM argument is not given, callscgi will run in client mode. In client mode, callscgi will try to connect to a SCGI server listening to the given address. If it cannot connect, it will exit, except when failing only once, in which case it will retry according to the -N option, described below.
If no address option is given, but the PROGRAM argument is given, callscgi will run in anonymous mode. In anonymous mode, callscgi will create a Unix socket listening on some more-or-less random address, and start the given PROGRAM, passing the listening socket on its standard input, expecting the program to start accepting connections on that socket. callscgi will then connect to that socket for each request. If such a connection is refused, the child program will be assumed to have crashed, and callscgi will restart it. Also in anonymous mode, callscgi will try and kill the child program whenever callscgi itself exits for whatever reason (commonly because its own control socket is closed by its parent handler).
If both an address option and the PROGRAM argument are given, but the -N option is not given, callscgi will run in launching mode. In launching mode, callscgi will try to connect to a SCGI server at the given address, but if (and only if) that fails, it will create a socket listening to the given address, and start the given PROGRAM, passing the listening socket on its standard input, expecting the program to start accepting connections on that socket. Unlike in anonymous mode, callscgi will leave any child process it has started running even when callscgi itself exits.
If both an address option, the PROGRAM argument and the -N option are given, callscgi will run in mixed mode. In mixed mode, callscgi will try to connect to a SCGI server at the given address, but if that fails, it will start the given PROGRAM. Unlike in launching mode, however, callscgi will not create the listening socket itself, but will assume that the PROGRAM will create it independently (probably based on any ARGS passed to it). When PROGRAM is launched, callscgi will try to connect to the given address once per second, up to RETRIES times. If the connection cannot succeed even after RETRIES attempts, callscgi will exit.
localhost instead. TCPPORT may be
given symbolically.
Fredrik Tolf <fredrik@dolda2000.com>