persistent process supervision
runenv(8)                          runtools                          runenv(8)



NAME
       runenv - run a program with a modified environment

SYNOPSIS
       runenv [-hV] [-i] [-U acct ] newenv program [ args ...  ]

DESCRIPTION
       runenv  starts  program  with a modified environment.  As distinct from
       common versions of env(1), modifications are applied  only  within  the
       environment  of  program;  the  environment  of  runenv  itself  is not
       affected.

       Modifications for the new environment are  specified  in  the  argument
       newenv,  which is either a file or a directory.  If newenv is a - (sin-
       gle dash), runenv  reads  the  modifications  from  standard  input  as
       described for a file.

       The  argument  program may be either a pathname or a filename.  If pro-
       gram contains a ``/'' (slash) character, it is  considered  a  pathname
       and  runenv will attempt to invoke it directly.  Otherwise, runenv will
       perform a shell-like search for program within the directories  defined
       in the PATH variable of the runtime environment of runenv.

       If the argument newenv is a file:

       The file newenv is opened and read line by line.  A line in the form of
       k=v is interpreted as an environmental  variable,  k,  defined  with  a
       value  of  v.  If the variable k does not exist in the current environ-
       ment, k=v will be added to the environment of program.  If the variable
       k  does exist in the current environment, its value will be replaced by
       v in the environment of program.

       A line in the form of k only, without =v, specifies that  any  existing
       variable k will be deleted (unset) from the environment of program.

       All names and values read from file are trimmed of leading and trailing
       whitespace.  Empty lines and lines beginning with ``#'' are ignored.

       If the argument newenv is a directory:

       Each file k in the directory newenv is interpreted as an  environmental
       variable  k=v,  where k is the name of the file, and v is read from the
       first line of the file.  As above, if the variable k does not exist  in
       the  current  environment, k=v will be added to the environment of pro-
       gram.  If the variable k does exist in  the  current  environment,  its
       value will be replaced by v in the environment of program.

       If  the  file  k is empty, then any existing variable k will be deleted
       (unset) from the environment of program.

       Filenames in the directory newenv that begin with  ``.''  are  ignored,
       and  filenames should not contain ``=''.  The values read from files in
       newenv are trimmed of leading and trailing whitespace.  No special pro-
       vision  is  made  for  commenting  files,  except to note that any text
       occuring after the first line is ignored.

       Escape sequences:

       Whether newenv is a file or directory, a limited number of  two-charac-
       ter escape sequences are supported within value definitions:

       ``\n'' is changed to newline

       ``\t'' is changed to tab

       ``\_'' (backslash + underscore) is changed to single space

       ``\\'' is changed to single backslash

       These  escape  sequences  make it possible to embed newlines in values,
       and provide a way to retain leading and trailing whitespace.  Any other
       ``\'' sequences found within a value are left verbatim.

OPTIONS
       -h     Help.  Display brief usage message and exit.

       -i     Ignore  existing  environment.   Normally  runenv  modifies  the
              existing environment.  If the -i option is specified, any exist-
              ing  environment is ignored and only new environment definitions
              are passed to program.

       -U acct
              UID/GID.  A few programs  look  specifically  for  environmental
              variables  named  UID  and  GID.  The -U option may be used as a
              convenient way to set these variables with  the  uid/gid  corre-
              sponding  to the user name acct.  Note that this option emphati-
              cally does nothing by itself to change  the  executable  permis-
              sions  of  program.   It  only sets up a couple of environmental
              variables that may (or may not) be used by the  subsequent  pro-
              gram  according  to  its  own design.  To affect the actual set-
              user-ID permissions of program, see runuid(8).

       -V     Version.  Report the version number and exit.

EXIT STATUS
       runenv exits with one of the following values:

       0      program was invoked and completed successfully.  In  this  case,
              the  exit code is returned by the program, rather than by runenv
              itself.

       100    runenv failed because of a usage error, such as an invalid  com-
              mand-line  option  or  argument.   In this case, runenv prints a
              brief error message and usage help to stderr on exit.

       111    runenv failed due to some system or  resource  error.   In  this
              case,  runenv  prints  a  brief  diagnostic message to stderr on
              exit.

       1-127  program was invoked and failed with its own non-zero  exit  sta-
              tus.

AUTHOR
       Wayne Marshall, http://b0llix.net/perp/

SEE ALSO
       runtools_intro(8),  runargs(8), runargv0(8), runchoom(8), rundetach(8),
       rundeux(8),   runfile(8),   runlimit(8),    runlock(8),    runpause(8),
       runsession(8), runtool(8), runtrap(8), runuid(8)



runtools-2.07                    January 2013                        runenv(8)