HomeSYNOPSIS
pid = os.spawn(spec)
DESCRIPTION
Starts a child process from an executable file. The argument spec is a table that specifies the process and its parameters.
Fields in spec are:
| Name | Description |
|---|---|
| filename | Full path to the executable file. |
| arg | A list of commandline arguments that are passed to the executable. This must be a lua table of strings in list form. The argument is optional. The executable always gets its filename passed as the first commandline parameter (in argv[0]). All further parameters are taken from this arg list. |
| env | A list of environment variables that are passed to the executable. This argument is optional. When not specified, the child process receives a copy of its parent's environment. To start the child with an empty environment, set env to false. When used to specify a list of variables, this parameter must be a lua table of strings in list form. Each entry must be of the form NAME=VALUE. |
| stdin
stdout stderr |
When none of these fields are specified, the child process' stdio channels are the same as those of the parent process. When at least one of these fields is specified as a file handle, the child process' stdio channel of that name is routed to that handle. Any other stdio channel not specified is disabled on the child. Note that the child gets copies of these file handles. Therefore the parent is free to close it's file handles after spawning the child, if it does not need them on the parent side. |
| fds | An optional list of file handles to pass to the child process. By default, all open files of the parent process are closed when seen from the child process. To keep certain handles open on the child side, pass a lua table with a list of file handles as fds. Note that the child gets copies of these file handles. Therefore the parent is free to close it's file handles after spawning the child, if it does not need them on the parent side. This feature is useful to pass one half of a pipe or socketpair to a child process. Note that the child process does not automatically know which file handles it got passed. You will need to pass the file numbers either via a commandline parameter (through arg) or via a environment variable (through env). |
With this function there is no way for the parent process to know when the child exits. If you need that information, use event:spawn() instead, which supports a callback on process exit.
A process can be forcefully terminated by using the command os.kill().
RETURN VALUE
On success, returns the process id of the child process. On error, three values are returned:
nil, a string describing the error (The result of the C library call strerror() on the
errno code) and the errno number from the standard C library.
EXAMPLE
This runs a directory listing
os.spawn{
filename = "/bin/ls",
arg = { "-l", "/media" },
env = false,
}