execline
Software
www.skarnet.org
The execline library interface
The execline library has been designed to help
programmers write applications suitable for use in execline
scripts.
Compiling
- Add /package/admin/execline/include to your header directory list
- Use #include "execline.h"
Linking
- Define a global variable PROG of type const char *
that contains the name of your executable.
- Add /package/admin/execline/library and
/package/prog/skalibs/library to your library directory list
- Link with libexecline.a and libstddjb.a
Programming
Check the /package/admin/execline/include/execline.h header
for the exact prototypes of the described functions.
int argc1 ;
const char **argv ;
argc1 = el_semicolon(argv) ;
- el_semicolon() scans argv until it finds a
single, unquoted semicolon (;) or NULL (the end of
argv).
- el_semicolon() returns the position of the semicolon it
finds, starting at zero, or the length of argv if it doesn't
find any.
- If the scanned argument is quoted, i.e. it begins by a
tilda (~), el_semicolon() unquotes it, i.e. removes
the tilda.
- If the scanned argument is not quoted:
- If the EXECLINE_STRICT environment variable is set to
1, el_semicolon() prints a warning message to stderr.
- Else if the EXECLINE_STRICT environment variable is set to
2 or more, el_semicolon() prints an error message to stderr,
and the process exits 100.
- Else nothing happens: the unquoted argument is accepted.
If a scanned argument is not quoted, the argv is not
well-formed. In particular, it is vulnerable to the security
hole that plagued execline-0.x: if a substitution occurs in a block
that is not well-formed, it could affect the execution flow by creating
an unexpected unquoted semicolon. Well-formed argvs are immune
to this problem.
The execlineb launcher always produces
well-formed argvs (by automatically quoting every argument in
a block) if braces have been placed properly. The
execline launcher has no block support -
which is why you should use it only if you know exactly what you are doing.
Sequencing
const char *const *argv1 ;
const char *const *argv2 ;
el_execsequence(argv1, argv2) ;
- el_execsequence() forks and
pathexecs
argv1.
- It waits for it to exit, stores the return code in the
LASTEXITCODE environment variable, then pathexecs argv2.
- If an error occurs, el_execsequence
exits with an error message. It does not return in any case.
- argv1 and argv2 may be empty. In that case,
el_execsequence will just exec the remaining program, or
exit with a 0 value if both are empty.
int nc ;
elsubst *substs ;
unsigned int ns ;
stralloc to = GEN_ALLOC_ZERO ;
stralloc from ;
nc = el_substitute(&to, &from, substs, ns) ;
int n0 ;
stralloc sa ;
unsigned int offset ;
elsplitinfo si ;
n0 = (int)el_splitc (&sa, offset, delim) ;
n0 = (int)el_splitnc (&sa, offset, delim) ;
n0 = el_splitnetstring(&sa, offset) ;
n0 = el_split (&sa, offset, &si) ;
n0 = el_split0 (&sa, offset, &si) ;
- el_splitnc() replaces in sa, starting at position
offset, every occurrence of any
character in delim by a null character.
- el_splitc() replaces in sa, starting at position
offset, every bunch of consecutive
characters appearing in delim by a single null character.
Those functions return the number of null characters they have written.
- el_splitnetstring() expects to find a sequence of
netstrings in
sa, starting at position offset.
It decodes the netstrings and writes the result,
null-separated, into sa starting at offset (this piece
of the string is overwritten). It returns
the number of netstrings it has found, or -1 (setting errno appropriately)
if a temporary error occurs, or -2 if it cannot find a valid sequence
of netstrings.
- el_split0() calls el_split(). If it succeeds, it
adds a null character to sa and returns the total number of words
(normally the return code from el_split() plus 1), which is
suitable as the n field of an elsubst. If it fails, it
returns el_split()'s return code, setting errno to EINVAL
if that code was -2.
int r ;
stralloc sa = GEN_ALLOC_ZERO ;
char const *const *envp ;
unsigned int envlen ;
char const *const *list ;
unsigned int listlen ;
r = el_pushenv(&sa, envp, envlen, list, listlen) ;
r = el_popenv(&sa, envp, envlen, list, listlen) ;
- envp is the environment to scan, of length
envlen (not counting the possible final NULL)
- list is a list of null-terminated strings, of length
listlen. Every variable in envp whose name
starts with a prefix in list will be affected.
- el_pushenv() pushes the environment: for every
affected variable FOOBAR,
- ...
- FOOBAR:2 becomes FOOBAR:3
- FOOBAR:1 becomes FOOBAR:2
- FOOBAR becomes FOOBAR:1
el_pushenv() returns the total number of affected variables,
or -1 on error.
- el_popenv() pops the environment: for every
affected variable FOOBAR,
- FOOBAR is unset
- FOOBAR:1 becomes FOOBAR
- FOOBAR:2 becomes FOOBAR:1
- FOOBAR:3 becomes FOOBAR:2
- ...
el_popenv() returns the number of unset variables, or -1 on
error.
- The resulting environment is stored in sa, as the
concatenation of null-terminated strings. You can use
skalibs's
envalloc_make() to get a char ** from this stralloc.