For the latest stable version, please use Emilua API 0.10! |
system.spawn
Description
Creates a new process.
Named parameters
program: string|filesystem.path|file_descriptor
-
string
-
A simple filename. The system searches for this file in the list of directories specified by PATH (in the same way as for execvp(3)).
filesystem.path
-
The path (which can be absolute or relative) of the executable.
file_descriptor
-
A file descriptor to the executable. See fexecve(3).
arguments: string[]|nil
-
A table of strings that will be used as the created process'
argv
. Onnil
, an emptyargv
will be used.Don’t forget to include the name of the program as the first argument. environment: { [string]: string }|nil
-
A table of strings that will be used as the created process'
envp
. Onnil
, an emptyenvp
will be used. stdin,stdout,stderr: "share"|file_descriptor|nil
-
"share"
-
The spawned process will share the specified standard handle (
stdin
,stdout
, orstderr
) with the caller process. file_descriptor
-
Use the file descriptor as the specified standard handle (
stdin
,stdout
, orstderr
) for the spawned process. nil
-
Create and use a closed pipe end as the specified standard handle (
stdin
,stdout
, orstderr
) for the spawned process.
extra_fds: { [integer]: file_descriptor }|nil
-
Extra file descriptors for the child to inherit. Parent and child processes don’t need to share the same numeric value reference for a given file description. The file descriptor number used in the child process will be the one specified in the key portion of the dictionary argument. Only file descriptors numbered from
3
to9
are acceptable (i.e. the same limitations of low fds that you’re likely to face on older UNIX shells). If you need to pass more than 10 file descriptors — stdin, stdout, stderr, plus these extra 7 file descriptors — use another interface (e.g.SCM_RIGHTS
).Not available on Windows. signal_on_gcreaper: integer = system.signal.SIGTERM
-
Each process is responsible for reaping its own children. A process that fails to reap its children will soon exhaust its OS-provided resources. For short-lived programs that’s hardly a problem given the process quits and its children are re-parented to the next subreaper in the chain (usually the init process). However for a concurrency runtime such as Emilua we expect other concurrent tasks to remain unaffected by the one failing task (be it a single fiber or the whole VM). Emilua will then transparently reap any child process for which its handle has been GC’ed.
signal_on_gcreaper
allows the user to specify a signal to be sent to the child that’s about to be reaped at this occasion.By default, the signal
system.signal.SIGTERM
will be sent to the child and then the main Emilua process will — indefinitely, non-blockingly, and non-pollingly — await for all of its children to finish even if there’s no longer any Lua program being executed. Use the more dangeroussystem.signal.SIGKILL
if you don’t want the main Emilua process to wait long for the child. Use0
if you don’t want the Emilua reaper to send any signal before awaiting for the child.Ideally the system kernel would expose some re-parent syscall, but until then (if ever), signal_on_gcreaper
will be necessary.Only available on Linux. pd_daemon: boolean = see-below
-
Instead of the default terminate-on-close behaviour, allow the process to live until it is explicitly killed with kill(2).
By default, it’s
true
unless the parent process is in capability mode (see cap_enter(2)).Only available on FreeBSD. scheduler.policy: string|nil
-
Values acceptable on Linux for non-real-time policies are:
"other"
-
See
SCHED_OTHER
. "batch"
-
See
SCHED_BATCH
. "idle"
-
See
SCHED_IDLE
.
Values acceptable on Linux for real-time policies are:
"fifo"
-
See
SCHED_FIFO
. Must also setscheduler.priority
. "rr"
-
See
SCHED_RR
. Must also setscheduler.priority
.
Not available on Windows. scheduler.priority: integer|nil
-
The interpretation of this parameter is dependant on
scheduler.policy
.Not available on Windows. scheduler.reset_on_fork: boolean = false
-
If
true
, grandchildren created as a result of a call to fork(2) from the direct child will not inherit privileged scheduling policies. If set, must also setscheduler.policy
.Not available on Windows. start_new_session: boolean = false
-
Whether to create a new session and become the session leader. On
true
, callssetsid()
on the child.Not available on Windows. set_ctty: file_descriptor|nil
-
Set the controlling terminal for the child. It is an error to specify
set_ctty
, but omitstart_new_session
.It’s an error to specify both set_ctty
andforeground
.Not available on Windows. process_group: integer|nil
-
Set the process group (it calls
setpgid()
on the child). On 0, the child’s process group ID is made the same as its process ID.Not available on Windows. foreground: "stdin"|"stdout"|"stderr"|file_descriptor|nil
-
Make the child be the foreground job for the specified controlling terminal by calling
tcsetpgrp()
(SIGTTOU
will be blocked for the duration of the call). It is an error to specifyforeground
, but omitprocess_group
."stdin"
,"stdout"
, and"stderr"
can only be specified if parent and child share the same file for the specified standard handle.It’s an error to specify both foreground
andset_ctty
.Not available on Windows. ruid: integer|nil
-
Set the real user ID.
Not available on Windows. euid: integer|nil
-
Set the effective user ID. If the set-user-ID permission bit is enabled on the executable file, its effect will override this setting (see execve(2)).
Not available on Windows. rgid: integer|nil
-
Set the real group ID.
Not available on Windows. egid: integer|nil
-
Set the effective group ID. If the set-group-ID permission bit is enabled on the executable file, its effect will override this setting (see execve(2)).
Not available on Windows. extra_groups: integer[]|nil
-
Set the supplementary group IDs.
Not available on Windows. umask: integer|nil
-
See umask(3p).
Not available on Windows. working_directory: filesystem.path|file_descriptor|nil
-
Sets the working directory for the spawned program.
pdeathsig: integer|nil
-
Signal that the process will get when its parent dies. If the executable file contains set-user-ID, set-group-ID, or contains associated capabilities,
pdeathsig
will be cleared.“Parent” is a difficult term to define here. For Linux, that’s not the process, but the thread. For Emilua, the thread will exist for at least as long as the calling Lua VM exists (even if the Lua VM might jump between threads). The thread will also exist for even longer, for as long as other Lua VMs are using it. Not available on Windows. nsenter_user: file_descriptor|nil
-
Enter in this Linux user namespace. When
nsenter_user
is specified, Emilua always enter in the user namespace before any other namespace.Only available on Linux. nsenter_mount: file_descriptor|nil
-
Enter in this Linux mount namespace.
Only available on Linux. nsenter_uts: file_descriptor|nil
-
Enter in this Linux UTS namespace.
Only available on Linux. nsenter_ipc: file_descriptor|nil
-
Enter in this Linux IPC namespace.
Only available on Linux. nsenter_net: file_descriptor|nil
-
Enter in this Linux net namespace.
Only available on Linux.
subprocess
functions
wait(self)
Wait for the process to finish, and then reap it. Information regarding
termination status is stored in exit_code
and exit_signal
.
If your code fails to call wait() , the Emilua runtime will reap the
process in your stead as soon as the GC collects self and the underlying
subprocess finishes. It’s important to reap children processes to free
OS-associated resources.
|
subprocess
properties
exit_code: integer
The process return code as passed to exit(3). If the process was terminated by a
signal, this will be 128 + exit_signal
(as done in BASH).
You can only access this field for wait() 'ed processes.
|