Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XENV(1)			    General Commands Manual		       XENV(1)

       xenv - expand shell variables in	input files

       xenv [-hnrsuv] [-D NAME[=VALUE]]	[-S [$@%&#]] [-U NAME] [FILE...]

       Reads  input  from  FILEs (or the standard input, if none are supplied)
       and prints it on	the standard output, expanding references to  environ-
       ment variables with their actual	values.

   Variable expansion
       A reference is one of the following constructs:

       $NAME  Expands  to  the	value  of  the	variable  NAME,	or to an empty
	      string, if it is unset.

	      Same as above.

       The following forms cause xenv to test for a variable that is unset  or
       null.  Omitting the colon results in a test only	for a variable that is

	      Use Default Values.  If variable is unset	or null, the expansion
	      of  word	is  substituted.   Otherwise, the value	of variable is

	      Assign Default Values.  If variable is unset or null, the	expan-
	      sion  of word is assigned	to variable.  The value	of variable is
	      then substituted.

	      Display Error if Null or Unset.  If variable is null  or	unset,
	      the  expansion  of  word (or a message to	that effect if word is
	      not present) is output to	standard error.	 Otherwise, the	 value
	      of variable is substituted.

	      Use  Alternate  Value.  If variable is null or unset, nothing is
	      substituted, otherwise the expansion of word is substituted.

	      Unless variable is null or unset,	substitutes the	 expansion  of
	      word1, otherwise the expansion of	word2.

       The  above  notation is consistent with the POSIX shell,	except for the
       ${variable:|word1|word2}	form, which is an extension of xenv.

       Comments	are multiline.	They are introduced with  the  characters  ${*
       and  extend  up to the nearest pair of characters *}.  Comments are re-
       moved from the input.

   Preprocessor	statements.
       The two sigil characters	appearing at the beginning of line  (with  op-
       tion preceding whitespace) introduce special preprocessor statements.

       Changing	sigil
	      The  sigil character can be changed using	the $$sigil statement.
	      Its argument is the desired sigil, e.g.:

	      my user name is $USER
	      $$sigil %
	      my home dir is %HOME
	      %%sigil #
	      using shell #SHELL

	      Not all characters can be	used as	a sigil.  See the  description
	      of the -S	option (OPTIONS	below),	for a list of eligible charac-
	      ters.  If	invalid	sigil value is requested, the  $$sigil	state-
	      ment will	be reproduced on output	as any regular text.

       Verbatim	block
	      The following construct introduces verbatim text block:


	      It  expands  to  TEXT  unchanged.	  To insert verbatim text in a
	      line, use	the $( ... ) construct (see Quoting and	escaping,  be-

       The following conditional statements expand to a	given fragment of text
       depending on whether an environment variable is defined.

       Expand if defined
	      The construct

	      $$ifdef NAME

	      is replaced with the expansion of	TEXT1 if the environment vari-
	      able  NAME  is defined (including	if it has a null value)	and to
	      TEXT2 otherwise.

	      If the construct begins with $$ifndef, the sense is inverted.

       Expand if set
	      The construct

	      $$ifset NAME

	      is replaced with the expansion of	TEXT1 if the environment vari-
	      able  NAME  is  set and has a non-null value and to TEXT2	other-

	      If the construct begins with $$ifnset, the sense is inverted.

       In the conditional constructs above, the	$$else part is optional.

       Optional	whitespace is allowed between the beginning of	the  line  and
       the  $$ marker, as well as between it and the keyword.  This allows for
       indenting the nested constructs in a more natural way, e.g.:

       $$ifdef LOG_HOST
       $$ ifdef	LOG_PORT
	 logger	$LOG_HOST:$LOG_PORT;
       $$ else
	 logger	$LOG_HOST
       $$ endif

   Setting and unsetting variables
       $$set NAME
	      Sets the variable	NAME to	empty string.

       $$set NAME "STRING"
	      Sets the variable	NAME STRING.  Within STRING,  each  occurrence
	      of a backslash followed by another character is replaced by that
	      character	alone.

       $$unset NAME
	      Unsets the variable NAME.

   Quoting and escaping
       To deprive the selected sigil of	its special meaning, precede it	with a
       backslash.  For example:


       Backslash  followed  by	another	 backslash is replaced by single back-
       slash.  Backslash followed by any other character is reproduced	verba-

       To  reproduce a portion of text verbatim, enclose it in $( and ).  This
       has the same effect as the $$verbatim block, except that	it allows  the
       verbatim	portion	to appear within a line.  Newlines and balanced	paren-
       theses are allowed within the $(	...  ) construct.

   Changing the	sigil
       If the use of $ character to indicate variable  substitution  and  pre-
       processor  instructions	is  for	 some  reason not desirable, it	can be
       changed using the -S command line option.  The argument to that	option
       is  the character to use	instead	of $.  Only four characters are	eligi-
       ble for such use: @, %, &, and #.  For example, the command xenv	 -S  @
       will treat $ as a regular character, but	will expand the	constructs:


       Additionally, comments will be denoted by @{* ... *}, and @( ...	) will
       introduce inline	verbatim text.

       The same	holds true for preprocessor  statements,  i.e.	$$set  becomes
       @@set, and so on.

       Another way to change sigil is by using the $$sigil statement (see Pre-
       processor statements above).

       -h     Print a short command line summary and exit.

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

       -r     Retain references	to undefined variables in output.  By default,
	      an  undefined  variable expands to an empty string.  This	option
	      instructs	xenv to	reproduce the variable reference  verbatim  in
	      the  output.   Naturally,	 this  affects only $X and ${X}	refer-

       -S CHAR
	      Changes sigil (a character that starts variable substitution) to
	      CHAR.  Allowed characters	are: $ (the default), @, %, _, and #.

       -s     Generate	synchronization	 directives,  i.e.  lines  of the form
	      #line NUM	"FILE",	which mean that	the following line  originated
	      at line NUM in file FILE.
	      Synchronization  directives  are	emitted	 when variable or pre-
	      processor	directive expansion causes removal or insertion	of one
	      or more lines to the output.  Each synchronization directive oc-
	      cupies a single line by itself.  If a  synchronization  discrep-
	      ancy  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	understood).

       -u     Treat unset variables as an error.

       -D NAME[=VALUE]
	      Define environment variable NAME	to  the	 VALUE,	 or  an	 empty
	      string, if it is not given.

       -U NAME
	      Undefine the environment variable	NAME.

       -v     Print program version and	exit.

       dbe(1), m4env(1).

       Copyright (C) 2021 Sergey Poznyakoff <>
       License GPLv3+: GNU GPL version 3 or later <
       This is free software: you are free  to	change	and  redistribute  it.
       There is	NO WARRANTY, to	the extent permitted by	law.

XENV				 June 5, 2021			       XENV(1)


Want to link to this manual page? Use this URL:

home | help