execline
Software
skarnet.org

# The `envfile` program

`envfile` reads a file containing variable assignments, adds the variables to the environment, then executes a program.

## Interface

         envfile [ -i | -I ] file prog...

`envfile` reads file and adds the key-value pairs defined in file to the environment. Then it execs into prog..., i.e. the rest of its command line, with the modified environment.

## Exit codes

- 1: syntax error in file
- 100: wrong usage
- 111: system call failed
- 126: execve() on prog failed (unknown reason)
- 127: execve() on prog failed (prog could not be found)

0 is not listed because on success, `envfile` does not exit: it execs into prog.

## Options

- `-i` : strict. If file does not exist, exit 111 with an error message. This is the default.
- `-I` : loose. If file does not exist, exec into prog without modifying the environment.

## File syntax

file is a text file containing lines of the form `key = value`. Whitespace is permitted before and after key, and before or after value.

Empty lines, or lines containing only whitespace, are ignored. Lines beginning with `#` (possibly after some whitespace) are ignored (and typically used for comments). Leading and trailing whitespace is stripped from values; but a value can be double-quoted, which allows for inclusion of leading and trailing whitespace.

A non-commented line that ends with a backslash ("`\`") is concatenated with the following one, and the newline character is ignored. If a backslashed newline happens before the start of a value, then the whitespace at the beginning of the new line will be part of the value (i.e. leading whitespace on a new line is not stripped).

C escapes, including hexadecimal and octal sequences, are supported in quoted values. Unicode codepoint sequences are not supported. It is possible to include a newline in a quoted value by using `\n`; but including newlines in environment variables is not recommended.

If value is empty, key is still added to the environment, with an empty value. If you do not want key to be added to the environment at all, comment out the line. `envfile` does not offer a way to remove variables from the environment.

The envfile format is largely compatible with systemd's EnvironmentFile format, which allows for the reuse of such files outside of systemd.

## Notes

- If file is `-` then `envfile` reads and parses its standard input instead. To read a file literally named `-`, you can use `./-` for instance.
- The variables that can be defined with `envfile` are purposefully restricted. If you need more expressive power for your variable names, or for your values, you should use an envdir instead: see s6-envdir.