execline
Software
www.skarnet.org
The execline program
execline reads and executes a script.
Interface
execline [ -q | -w | -W ] [ -p | -P | -S nmin ] -c script [ args... ]
or
execline [ -q | -w | -W ] [ -p | -P | -S nmin ] scriptfile [ args... ]
or in an executable file:
#!/command/execline [ -qwWpPSnmin ]
script
Parsing phase.
- execline reads and parses the script it is given.
It exits 100 on a syntax error and 111 on a temporary error.
It makes an argv, i.e. a system command line, with the
parsed script. If the argv is empty, execline
exits 0.
Environment management phase.
- Pushing the current stack frame. If neither the
-p nor the -P nor the -S option is set:
execline pushes
the current positional parameters, i.e. environment variables that
start with #, 0, 1, ..., 9.
To get the previous values back, use
emptyenv -P.
- Setting the new stack frame. If neither the -P
nor the -S option is not set:
- execline sets the # environment variable to
the number n of args it is given.
- It sets the 0 environment variable to the name
of the script - or to the execline invocation name
if the -c option is used.
- It sets the 1, 2, ... n
environment variables to the different args.
Execution phase.
- execline executes into the argv it
has built from the script, according to the
pathexec rules -
except that the default path will be /command instead of
/usr/bin:/bin. There is only one command line for the
whole script: the execline binary is a launcher,
whose sole purpose is to execute into that command line. It does
not stay in memory.
Options
- -c script : execute script, do not
look for a file.
See below for the other options.
Syntax of scripts
An execline script is a string that must not contain the null character.
execline parses it and divides it into words.
The parser recognizes the following components:
- whitespace is defined as spaces, tabs, newlines and
carriage returns. Words are always separated by whitespace.
- A quoted string begins with a doublequote (")
and ends with another doublequote. Quoted doublequotes must be prefixed
by a backslash (\). Quoted strings always evaluate to exactly
one word. For instance, "" evaluates to the empty word.
- The \a, \b, \t, \n, \v,
\f, and \r sequences are recognized in quoted
strings, and are converted to the ASCII numbers 7, 8, 9, 10, 11, 12 and
13 respectively.
- Starting with execline-1.05: inside a quoted string, backslashed
newlines disappear completely.
- \0xab sequences are recognized in quoted strings
and evaluate to ASCII hexadecimal number ab.
- \0abc sequences are recognized in quoted strings
and evaluate to ASCII octal number abc.
- \abc sequences are recognized in quoted strings
and evaluate to ASCII decimal number abc. a must not
be zero.
- A comment starts with a # and ends with the line. Comments
are not recognized inside quoted strings.
- Anything else is an unquoted string, that can evaluate to
zero or more words.
- Any character can be escaped in unquoted strings by prepending
it with a backslash. It works the same way in quoted strings, except
for the special sequences described above.
You can see an example of distinct execline components
here.
For proper execution of the script, the sequence of words must follow
the execline grammar. WARNING:
execline performs direct argv construction, without
transformation to the script. In particular, it has no support
for blocks, so if you need
blocks in your script, you will have to quote them by hand and make
sure your script is well-formed (every word inside n blocks,
including semicolons (block terminators), must be preceded by n
tildas). An ill-formed script is a security risk.
Use of the execline launcher is discouraged; you are advised
to use execlineb instead.
Options for block syntax checking
External execline commands that read blocks, like
foreground, use the EXECLINE_STRICT
environment variable: if it is set to 1, they will print a warning message
on stderr if they find their blocks not to be properly quoted. If it is set
to 2, they will also die. If it is set to 0, or unset, they won't complain
at all.
Normally the EXECLINE_STRICT environment variable is
inherited from the caller. You can
force it unset, set to 1, or set to 2 by giving respectively the
-q, -w or -W option to execline.
Options for environment management
Normally, execline scripts are reentrant: environment variables
potentially overwritten by execline, such as # or
0, are
pushed. This is the standard, safe
behaviour. Nevertheless, it is rather costly, and may be unneeded for
small scripts: for those cases, execline-1.05 comes with two options
that bypass the environment management. Be warned that the sole purpose
of these options is optimization, and you should not
use them if you're not familiar with the way execline uses the
environment to store positional parameters. Alternatively, execline-1.06
comes with an integrated substitution mechanism that doesn't make use
of the environment at all.
- The -p option will bypass the
push phase: the current frame of positional
parameters will be overwritten. The script will not be
reentrant, just as with pre-1.05.
- The -P option will bypass positional parameter handling
completely: the environment will not be pushed, and positional
parameters will be ignored. execline -P -c "script" is
equivalent to, but more efficient than, execline -c
"emptyenv -P script". You should use the -P option
only in standalone scripts that take no arguments, such as
daemontools' or
runit's run scripts.
- The -S n option will substitute the
positional parameters - up to at least nmin - but will not
push nor set environment
variables. execline -S3 -c "script" is equivalent to,
but more efficient than, execline -c "elgetpositionals -P3 emptyenv
-P script". See
the details.
Current limitations
execline builds and executes a unique
argv with the script: hence scripts are subject to OS-dependent
limitations such as the kernel buffer size for argv and envp
- at least 64 kB on most systems. This means that execline cannot
execute arbitrarily large scripts. Be careful with deeply nested scripts too:
without the -p/-P/-S option, each execline
invocation uses up some space in the environment.