Home Contents | # event:spawn | Event | Core4 Lua Event System

## SYNOPSIS

#include <lua/wait.lh>
#include <lua/signal.lh>

1. pid = app:spawn(spec, callback)
2. function callback(pid, status) ...

## DESCRIPTION

Starts a child process from an executable file. The argument spec is a table that specifies the process and its parameters. The arguments in the table are the same as used by the generic command os.spawn(). See there for a documentation of the parameters.

The additional argument callback takes a function which is called when the child process terminates.

The callback parameter pid is the process id of the child process that has terminated. (The same process id that was previously returned by the app:spawn() command when the process was started.)

The callback parameter status indicates the reason of the process termination. For the normal successful exit, this value is zero.

The following macros may be used to test the manner of exit of the process. These macros are imported from the C language. To use them from Lua code, explicitly test for non-zero, as Lua considers the zero as true.

Example: if (WIFEXITED(status) ~= 0) then ... end

WIFEXITED(status)
  Non-zero if the process terminated normally.
WIFSIGNALED(status)
  Non-zero if the process terminated due to receipt of a signal.

Depending on the values of the macros above, the following macros produce the remaining status information about the child process:

WEXITSTATUS(status)
  If WIFEXITED(status) is non-zero, evaluates to the exit value of the child process. This value is truncated to 8 bits.
WTERMSIG(status)
  If WIFSIGNALED(status) is non-zero, evaluates to the number of the signal that caused the termination of the process.

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 and then prints DONE together with PID and status.

app:spawn( { filename = "/bin/ls", arg = { "-l", "/media" }, env = false, }, function(pid, status) print("DONE", pid, status) end )

## SEE ALSO

os.spawn(), os.kill(), rawio.pipe(), rawio.socketpair()