diff --git a/doc/execl-envfile.md b/doc/execl-envfile.md new file mode 100644 index 0000000000000000000000000000000000000000..df0903617d5648d3803a8efd8d9a0557e6611aea --- /dev/null +++ b/doc/execl-envfile.md @@ -0,0 +1,82 @@ +title: The 66-tools Suite: execl-envfile +author: Eric Vidal <eric@obarun.org> + +[66-tools](index.html) + +[Software](https://web.obarun.org/software) + +[obarun.org](https://web.obarun.org) + +# execl-envfile + +A mix of [s6-envdir](https://skarnet.org/software/s6/s6-envdir.html) and [importas](https://skarnet.org/software/execline/importas.html). Reads files containing variable assignments in the given *file/directory*, adds the variables to the environment and then executes a program. + +## Interface + +``` + execl-envfile [ -h ] [ -l ] src prog +``` +This tool expects to find a regular file or a directory in *src* containing one or multiple `key=value` pair(s). It will parse that file, import the `key=value` and then exec the given *prog* with the modified environment. In case of directory for each file found it apply the same process. *src* can be an absolute or a relative path. + +- It opens and reads a file. + +- It parses that file. + +- It imports the found `key=value` pair(s). + +- It substitutes each corresponding *key* with value from that file. + +- It unexports the variable(s) if requested. + +- It execs *prog* with the modified environment. + + +## Exit codes + +- *0* success +- *100* wrong usage +- *111* system call failed + +## Options + +- **-h** : prints this help. + +- **-l** : loose; do nothing and execute *prog* directly if *src* does not contain any regular file(s) or *src* does not exist. + +## File syntax + +*src* is a text file or a directory containing lines of pairs with the syntax being: `key = value` +Whitespace is permitted before and after *key*, and before or after *value*. Quoting is also possible. + +Empty lines or lines containing only whitespace are ignored. Lines beginning with `#` (also after whitespace) are ignored and typically used for comments. Comments are not possible at the end of lines: `key = value # comment` is not a valid comment. + +If val begin by a `!` character: `key=!value` the key will be removed from the environment after the substitution. + +## Usage example + +``` + #!/usr/bin/execlineb -P + fdmove -c 2 1 + execl-envfile %%service_admconf%%/ntpd + foreground { mkdir -p -m 0755 ${RUNDIR} } + execl-cmdline -s { ntpd ${CMD_ARGS} } + +``` + +The equivalent with s6-envdir and importas would be: + +``` + #!/usr/bin/execlineb -P + fdmove -c 2 1 + s6-envdir %%service_admconf%% + importas -u RUNDIR RUNDIR + importas -u CMD_ARGS CMD_ARGS + foreground { mkdir -p -m 0755 ${RUNDIR} } + execl-cmdline -s { ntpd ${CMD_ARGS} } +``` + +where `%%service_admconf%%` contains two named files `RUNDIR` and `CMD_ARGS` written with `/run/openntpd` and `-d -s` respectively. + +## Limits + +*src* can not exceed more than `100` files. Each file can not contain more than `4095` bytes or more than `50` `key=value` pairs. diff --git a/doc/index.md b/doc/index.md index 267a94027ec1f6e01d54d5ba26989b72669a1a4a..c316fc045138abc6ab41fc0c20e05941064495ec 100644 --- a/doc/index.md +++ b/doc/index.md @@ -80,6 +80,7 @@ Please refer to the [INSTALL.md](https://framagit.org/Obarun/66) file for detail - [66-echo](66-echo.html) - [66-umountall](66-umountall.html) +- [execl-envfile](execl-envfile.html) ## Why is 66 necessary? diff --git a/doc/make-html.sh b/doc/make-html.sh index 6cd223b0055caeb5af26ca762822cecbe9596307..22b88c22d030c320588d9ccf89b7bd255fb8bd22 100755 --- a/doc/make-html.sh +++ b/doc/make-html.sh @@ -1,6 +1,6 @@ #!/bin/sh -html='66-all 66-dbctl 66-disable 66-echo 66-enable 66-env 66-init 66-inresolve 66-inservice 66-instate 66-intree 66-parser 66-scanctl 66-scandir 66-start 66-stop 66-svctl 66-tree 66-update 66-boot 66-hpr 66-shutdown 66-shutdownd 66-umountall 66-update frontend instantiated-service module-service index' +html='66-all 66-dbctl 66-disable 66-echo 66-enable 66-env 66-init 66-inresolve 66-inservice 66-instate 66-intree 66-parser 66-scanctl 66-scandir 66-start 66-stop 66-svctl 66-tree 66-update 66-boot 66-hpr 66-shutdown 66-shutdownd 66-umountall 66-update frontend instantiated-service module-service index execl-envfile' if [ ! -d doc/html ]; then mkdir -p -m 0755 doc/html || exit 1 diff --git a/doc/make-man.sh b/doc/make-man.sh index d682574de48268aade9626da2d5443a6fce7e082..8d51a8e3953a8a4f63f723af036c1607105bd201 100755 --- a/doc/make-man.sh +++ b/doc/make-man.sh @@ -1,6 +1,6 @@ #!/bin/sh -man1='66-all 66-dbctl 66-disable 66-echo 66-enable 66-env 66-init 66-inresolve 66-inservice 66-instate 66-intree 66-parser 66-scanctl 66-scandir 66-start 66-stop 66-svctl 66-tree 66-update' +man1='66-all 66-dbctl 66-disable 66-echo 66-enable 66-env 66-init 66-inresolve 66-inservice 66-instate 66-intree 66-parser 66-scanctl 66-scandir 66-start 66-stop 66-svctl 66-tree 66-update execl-envfile' man8='66-boot 66-hpr 66-shutdown 66-shutdownd 66-umountall'