Previous: Raw sockets, Up: Client connections [Contents][Index]
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
.
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):
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:
Return 1 if a child process pid died recently, updating other internal state by side effect. Otherwise, return 0.
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.
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.
Fill environment block env with the environment variables from the current process, replacing its current contents (if any).
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.
Destroy environment block env completely. Afterwards, env is invalid and should therefore not be further referenced.
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.)
Previous: Raw sockets, Up: Client connections [Contents][Index]