system

Command: system


Description
"system" creates a child process of the current SLI process
and executes the given command in that child process.
Depending on the value of "Flag" the parent process will
wait for the child to terminate or continue execution in
parallel.
The command may be given either as a string containing
the command name and all options or as an array of
strings specifying the command name and every single
option.
If you are interested in communicating to the child process
via pipes see "spawn" or "shpawn".

Alternatives: Functions system_as_i_p with array or
string and integer(flag) and precode system_as_di_i_p
with array or string and dictionary followed by
integer(flag) and precode (both undocumented) -> behaviour and
synopsis are the same.

Parameters
In : CommandString(string)/CommandArray(array of string):
The UNIX command to execute.
Either a string containing the command and all
parameters or an array of strings containing the
command and the parameters in separate (see "sysexec").

Flag: 0: Wait for termination of child process.
A flag indicating if the child process exited
normally or abnormally and the exit status is
left on the stack.
1: Return immediately. This is the "no-care-mode".
An orphaned grandchild process is created.
I.e. a child is forked which again forks
a child and then exits. The orphaned grandchild
is inherited by the init-process immediately
which will perform any waiting.
This is a legal way of producing a child you don't
have to wait for. (However see remarks below.)
- All ressources occupied by the child process will
be automatically released with its termination. -
No result is left on the stack.
2: Return immediately.
Create a normal child process and return immediately
leaving it's PID on the stack.
! The parent has to call "wait" or "waitPID" in order
to free the ressources occupied by the child process
after it's termination !

The "Flag" parameter may be omitted in which case
it defaults to zero.

Precode(executable procedure):
-This parameter is for internal use with the "spawn"
command. However it is documented here for there may be
unexpected applications.-
In "Precode" there can be supplied a sequence of SLI
commands that will be executed by the child process
prior to calling "sysexec". The main application
is to instruct the child process to redirect it's
standard input/output to a pipe as does the "spawn"
command (for a example see the code of "spawn").


Out: NormalExitFlag(boolean):
True if the child terminated normally i.e. by a call to
exit() or by returning from main(). In that case the exit
code is reported in the Status argument (see below).
False if the child terminated due to a signal that was
not caught. In that case the number of that signal is
reported in the Status argument (see below).

Status(integer):
If NormalExitFlag is true this reports the child's exit
code i.e. the low-order eight bits of the status argument
that the child passed to exit() or the value the child
process returned from main().
If NormalExitFlag is false this reports the number of the
signal that caused the termination of the child process.
Look up this number in signaldict to know what it means.

ChildPID(integer): The process ID of the newly created child.

Author
R Kupper

Bugs
Be aware of citation-mark-bug in breakup (see "breakup")

Synopsis
CommandString system } { Flag=0 or omitted:
CommandArray system } { Status NormalExitFlag
} -> {
CommandString Flag system } { Flag=1: -
CommandArray Flag system } {
} { Flag=2: ChildPID
CommandString Flag Precode system }
CommandArray Flag Precode system }

Examples
1. (ls) system % This is the same as: (ls) 0 system
2. (xterm) 1 system
3. %The follwing asks SLI to make itself do something else in parallel
%and report make's exit code:
(make --silent) 2 system /MyChild Set

MyChild false waitPID %wait for child to terminate
pop pop (make returned exit code: ) =only =

File
lib/sli/processes.sli
Remarks
The no-care-mode (Flag=2) gives no way to know about the
child`s exit code. If you need to care about the exit code
use Flag=0 which will leave it on the stack or use Flag=1
and get the exit code by calling "wait" or "waitPID".

If you are interested in communicating to the child process
via pipes see "spawn" or "shpawn".

To Do: It should be possible to spawn a parallel SLI Process. This
should be supported by a future version. Actually as this is
the more general case the spoon/system/spawn chain of commands
could be restructured.