8 Invocation

The general usage is:

xenv [options] [file...]

The input is read from each file in turn, processed and the expansion is printed on the standard output. If no file arguments are given, the input is read from the standard input. Special file name ‘-’ (dash), stands for standard input as well.

Command line options are:

-e name

Define the environment meta-variable name. See Meta-variable.

-h

-?

Print a short command line summary and exit.

-m

Pipe output to m4. See GNU M4 manual in GNU M4 macro processor. If the -s option is also given, it will be passed to m4 as well. See also -p.

-n

Dry-run mode. Process input files without producing any output. Report any errors. This option is useful together with the -u to discover undefined variables.

-p command

Pipe output to command.

-r

Retain references to undefined variables in output. When this option is given any reference in the form ‘$name’ or ‘${name}’ that appears in the input text and refers to undefined variable name will be reproduced in output verbatim. By default, such references produce no expansion.

Notice the emphasized text above. This option does not apply to variable references appearing in command substitutions (see Command substitution) and external tests (see external tests).

See also -u below.

-s

Generate synchronization directives, i.e. lines of the form

#line num "file"

which mean that the line that follows originated at line num in file file.

Synchronization directives are emitted when variable or preprocessor directive expansion causes removal or insertion of one or more lines to the output. Each synchronization directive occupies a single line by itself. If a synchronization discrepancy occurs in the middle of an output line, emission of the synchronization directive is delayed until the next newline that does not occur in the middle of a quoted string (both single and double quotes are honored).

-t n

Sets maximum execution time for external commands to n seconds. The default is unlimited. This affects command substitution (see Command substitution) and $$ifcom ($$ifncom) conditionals (see external tests).

-u

Treat unset variables as an error. Any ‘$name’ or ‘${name}’ construct appearing in the input text will trigger an error message, if the variable name is not defined. The offending construct will either produce no expansion or will be retained in the output, if the -r option is given. The program will continue running. When the input text is exhausted, it will exit with code 65 (see Exit codes).

Notice the emphasized text above. This option does not apply to variable references appearing in command substitutions (see Command substitution) and external tests (see external tests).

-D name[=value]

Define environment variable name to value, or to an empty string, if value is omitted.

-U name

Undefine the environment variable name.

-v

Print program version and exit.

-W [no-]feature

-W feature=value

Controls the specific xenv feature. The first form enables or disable (if prefixed with ‘no-’) the feature. The second form sets the feature value. Valid feature names are:

feature: command

Controls command substitution (see Command substitution).

feature: comment

Controls comments (see Comments).

feature: booleans=value

This feature defines strings which are considered boolean values in $$iftrue and $$iffalse directives (see boolean evaluation). The argument value is a comma-delimited list of ‘t/f’ pairs. Each such pair defines t as true value and f as false value. Either part may be omitted. For example:

-Wbooleans=1/0,true/false

This instructs xenv to evaluate ‘1’ and ‘true’ as boolean true and ‘0’ or ‘false’ as boolean false.

feature: directive

Preprocessor directives (see Directives).

feature: escape

Use of ‘\’ as escape character (see Escapes).

feature: minimal

Disables most other features and enforces $ENV as environment meta-variable (see Meta-variable). In other words, -Wminimal is equivalent to:

-Wno-command -Wno-comment -Wno-directive -Wno-quote \
-Wno-escape -e ENV

feature: paranoid-memfree

Free all allocated memory before exit. It is needed mostly for debugging and chasing memory allocation errors.

feature: stashfiles=n

Sets allowed number of simultaneously open stash files. A stash is an internal structure used to store temporary data. Stashes are used, in particular, to implement diversions, loops and conditional constructs. A stash attempts to store as much data as possible in the RAM. The amount of memory allotted for each stash is defined by the stashsize feature (see below). When its memory gets filled, it opens a temporary file and stores the surplus data there. When a new stash file needs to be open and the number of already open files equals n, the program will close the least recently used stash file, thereby freeing a file descriptor for use of the new stash. The closed file will eventually be reopened when it is needed.

By default, the number of stashfiles is set to 2/3 of the system limit on the number of open file descriptors. You may wish to set this feature if xenv terminates with a ‘too many open files’ error.

feature: stashsize=n

Sets amount of memory allocated per stash. When this memory is filled, a temporary file is created and all surplus data are stored there. The n can be followed by the usual suffixes: ‘K’, ‘M’, and ‘G’. Lower-case letters are allowed too.

The default memory size is set to the system memory page size.

feature: quote

Controls inline verbatim quotations (see inline verbatim).

By default all features except minimal are enabled.

-x

Enable debugging output.