---

5.2.7.6 Passthrough connections

The functions described in this section allow you to pass through client connections to the standard input (stdin) and standard output (stdout) of external programs. Some of the routines deal with the management of program environments. Basically, there are two methods for passing through a duplex connection: the Unix’ish fork and exec method and the shuffle method where the main process keeps control over the communication on the original duplex connection and passes this data through two pairs of pipes, or yet another socket connection, to the child process. All of the three method are implemented calling them SVZ_PROCESS_FORK, SVZ_PROCESS_SHUFFLE_PIPE and SVZ_PROCESS_SHUFFLE_SOCK.

Function: int svz_sock_process (svz_socket_t *sock, char *bin, char *dir, char **argv, svz_envblock_t *envp, int forkp, char *user) ¶

Start a new program bin, a fully qualified executable filename, passing the socket or pipe descriptor(s) in the socket structure sock to its stdin and stdout.

If dir is non-NULL, it specifies the working directory of the new process.

The program arguments and the environment of the new process are taken from argv and envp. Normally argv[0] should be set to the program’s name. If NULL, it defaults to bin.

The forkp argument is a flag that controls the passthrough method. If non-zero, pipe descriptors or the socket descriptor are passed to the child process directly through fork and exec. Otherwise, socket transactions are passed via a pair or pipes or sockets (depending on whether or not the system provides socketpair).

You can pass the user and group identifications in the format ‘user[.group]’ (group is optional), as SVZ_PROCESS_NONE or SVZ_PROCESS_OWNER in the user argument. This specifies the permissions of the new child process. If SVZ_PROCESS_OWNER is passed the permissions are set to the executable file bin owner; SVZ_PROCESS_NONE does not change user or group.

Return the new process id on success, -1 on failure.

Please note: On M$-Windows platforms it is not possible to pass a socket connection to stdin/stdout of a child process. That is why this function creates an inheritable version of the socket and puts the socket handle number into the environment variables SEND_HANDLE and RECV_HANDLE. A spawned child process can use these handles as if they were self-created. After calling WSAStartup the child process can send and recv as usual.

Relatedly, Windoze does not use SIGCHLD to inform the parent when a child dies, so for that platform, you should use the next function (which is not otherwise available):

Function: int svz_mingw_child_dead_p (char *prefix, svz_t_handle *pid) ¶

Check child pointed at by pid by waiting a bit. If it is dead, close and invalidate its handle, and return 1. Otherwise, return 0. prefix is for error messages; it should be either the empty string, or a string ending in colon and space.

On non-Windoze, this is the function you want to use:

Function: int svz_most_recent_dead_child_p (svz_t_handle pid) ¶

Return 1 if a child process pid died recently, updating other internal state by side effect. Otherwise, return 0.

Function: void svz_envblock_setup (void) ¶

Set up internal tables for environment block wrangling.

This function must be called once after svz_boot so that subsequent functions (like svz_envblock_default) can work correctly.

Function: svz_envblock_t * svz_envblock_create (void) ¶

Create and return a fresh environment block, useful for passing to svz_envblock_default and svz_envblock_add. Its size is initially set to zero.

Function: int svz_envblock_default (svz_envblock_t *env) ¶

Fill environment block env with the environment variables from the current process, replacing its current contents (if any).

Function: int svz_envblock_add (svz_envblock_t *env, char *format, …) ¶

Insert a new environment variable into environment block env. The format argument is a printf-style format string describing how to format the optional arguments. You specify environment variables in the ‘VAR=VALUE’ format.

Function: void svz_envblock_destroy (svz_envblock_t *env) ¶

Destroy environment block env completely. Afterwards, env is invalid and should therefore not be further referenced.

Function: void * svz_envblock_get (svz_envblock_t *env) ¶

Convert environment block env into something which can be passed to execve (Unix) or CreateProcess (Windows). Additionally, under Windows, sort the environment block.

(Unfortunately the layout of environment blocks in Unices and Windows differ. On Unices you have a NULL terminated array of character strings (i.e., char **) and on Windows systems you have a simple character string containing the environment variables in the format ‘VAR=VALUE’ each separated by a zero byte (i.e., char *). The end of the list is indicated by a further zero byte.)