]rootPopenSocket

Control-struct: ]rootPopenSocket

file: job.t
package: muf
status: tentative

{  [ :socket socket
     :commandline "| pgp -feast pat |"
   | ]rootPopenSocket
}

The ]rootPopenSocket spawns a host process connected to the Muq server via pipes. The @$S.actingUser must be root to do this.)

The :socket parameter must be a socket; It should be either freshly created See section makeSocket, or else one which has been closed by See section ]closeSocket. Before making this call, you should set the socket's $s.standardInput and $s.standardOutput keys to the message streams which you wish the socket connection to use.

The :commandline parameter may take one of three forms:

:commandline "| srv args"

Subprocess reads from socket, output to /dev/null.

:commandline "srv args |"

Subprocess reads from /dev/null, output to socket.

:commandline "| srv args |"

Subprocess both reads and writes from socket.

Note that in the third case, it is often necessary that the subprocess disable output buffering in order to avoid a deadlock in which it blocks waiting for input while its output sits unsent in its stdio output buffer. Subprocesses written in Perl may disable output buffering by doing

select( (select(STDOUT), $| = 1)[0]);

while subprocesses written in C may disable output buffering by doing

setvbuf( stdout, NULL, _IONBF, 0 );

or simply by using raw write() calls in place of the stdio printf, fprintf ... family of buffered output calls.

In all events, Muq will look for the server in the host directory given by db property .muq$S.srvdir, which is usually muq/srv but may be set to other values by editing the value of srvdir in muq/bin/Muq-config.sh or by using the --srvdir=/var/people/pat/muq/srv commandline switch when invoking Muq.

Security precautions include:

• There is no way to modify the .muq$S.srvdir property from within a running server.
• Server names specified may not begin with a period, and must consist only of letters, digits, periods and dashes. (In particular, slashes are not allowed.)
• This facility may be disabled completely by specifying --srvdir (no server directory) on the commandline.
• Servers are started up by a direct fork() and exec(), without the security problems of an intervening shell. (Hence also without most of the conveniences of an intervening shell, such as wildcard or environment variable expansion.)

Gory Details

• Subprocess streams which you do not specify are set to /dev/null. In particular, stdout is currently always /dev/null.
• Doing [ :socket s | ]closeSocket on a socket opened with ]rootPopenSocket will return immediately, but the socket will not be ready for re-use until the subprocess actually exits (as determined by recieving a SIGCHLD signal and querying waitpid()). When you call ]closeSocket Muq sends a HUP, and if that doesn't do the trick within skt_milliseconds_of_grace (normally 30000) milliseconds, sends a SIGKILL. If that has no effect within another skt_milliseconds_of_grace milliseconds, is closes the pipes and frees the socket anyhow.
• You may examine socket$S.closedBy to determine what terminated a subprocess: It will be :exit if the subprocess called exit() (in which case socket$S.exitStatus will have the integer exit status), :close if the subprocess was killed by a Muq ]closeSocket, and :signal if it was killed by any other signal (in which case socket$S.lastSignal will have the integer signal number).

See section ]openSocket.

Examples

• write-only-1|
• write-only-2|
• |read-only-1
• |unix-string-upcase-1|
• |unix-string-upcase-2|

Go to the first, previous, next, last section, table of contents.