23. Modified command invocation

This section describes commands that run other commands in some context different than the current one: a modified environment, as a different user, etc.

23.1 chroot: Run a command with a different root directory

chroot runs a command with a specified root directory. On many systems, only the super-user can do this.(4) Synopses:

chroot option newroot [command [args]…]
chroot option

Ordinarily, file names are looked up starting at the root of the directory structure, i.e., `/'. chroot changes the root to the directory newroot (which must exist) and then runs command with optional args. If command is not specified, the default is the value of the SHELL environment variable or /bin/sh if not set, invoked with the `-i' option. command must not be a special built-in utility (see section Special built-in utilities).

The program accepts the following options. Also see Common options. Options must precede operands.

`--userspec=user[:group]'

By default, command is run with the same credentials as the invoking process. Use this option to run it as a different user and/or with a different primary group.

`--groups=groups'

Use this option to specify the supplementary groups to be used by the new process. The items in the list (names or numeric IDs) must be separated by commas.

Here are a few tips to help avoid common problems in using chroot. To start with a simple example, make command refer to a statically linked binary. If you were to use a dynamically linked executable, then you'd have to arrange to have the shared libraries in the right place under your new root directory.

For example, if you create a statically linked ls executable, and put it in `/tmp/empty', you can run this command as root:

$ chroot /tmp/empty /ls -Rl /

Then you'll see output like this:

/:
total 1023
-rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls

If you want to use a dynamically linked executable, say bash, then first run `ldd bash' to see what shared objects it needs. Then, in addition to copying the actual binary, also copy the listed files to the required positions under your intended new root directory. Finally, if the executable requires any other files (e.g., data, state, device files), copy them into place, too.

Exit status:

125 if chroot itself fails
126 if command is found but cannot be invoked
127 if command cannot be found
the exit status of command otherwise

23.2 env: Run a command in a modified environment

env runs a command with a modified environment. Synopses:

env [option]… [name=value]… [command [args]…]
env

Operands of the form `variable=value' set the environment variable variable to value value. value may be empty (`variable='). Setting a variable to an empty value is different from unsetting it. These operands are evaluated left-to-right, so if two operands mention the same variable the earlier is ignored.

Environment variable names can be empty, and can contain any characters other than `=' and ASCII NUL. However, it is wise to limit yourself to names that consist solely of underscores, digits, and ASCII letters, and that begin with a non-digit, as applications like the shell do not work well with other names.

The first operand that does not contain the character `=' specifies the program to invoke; it is searched for according to the PATH environment variable. Any remaining arguments are passed as arguments to that program. The program should not be a special built-in utility (see section Special built-in utilities).

Modifications to PATH take effect prior to searching for command. Use caution when reducing PATH; behavior is not portable when PATH is undefined or omits key directories such as `/bin'.

In the rare case that a utility contains a `=' in the name, the only way to disambiguate it from a variable assignment is to use an intermediate command for command, and pass the problematic program name via args. For example, if `./prog=' is an executable in the current PATH:

env prog= true # runs 'true', with prog= in environment
env ./prog= true # runs 'true', with ./prog= in environment
env -- prog= true # runs 'true', with prog= in environment
env sh -c '\prog= true' # runs 'prog=' with argument 'true'
env sh -c 'exec "$@"' sh prog= true # also runs 'prog='

If no command name is specified following the environment specifications, the resulting environment is printed. This is like specifying the printenv program.

For some examples, suppose the environment passed to env contains `LOGNAME=rms', `EDITOR=emacs', and `PATH=.:/gnubin:/hacks':

• Output the current environment.

  $ env | LC_ALL=C sort EDITOR=emacs LOGNAME=rms PATH=.:/gnubin:/hacks

• Run foo with a reduced environment, preserving only the original PATH to avoid problems in locating foo.

  env - PATH="$PATH" foo

• Run foo with the environment containing `LOGNAME=rms', `EDITOR=emacs', and `PATH=.:/gnubin:/hacks', and guarantees that foo was found in the file system rather than as a shell built-in.

  env foo

• Run nemacs with the environment containing `LOGNAME=foo', `EDITOR=emacs', `PATH=.:/gnubin:/hacks', and `DISPLAY=gnu:0'.

  env DISPLAY=gnu:0 LOGNAME=foo nemacs

• Attempt to run the program /energy/-- (as that is the only possible path search result); if the command exists, the environment will contain `LOGNAME=rms' and `PATH=/energy', and the arguments will be `e=mc2', `bar', and `baz'.

  env -u EDITOR PATH=/energy -- e=mc2 bar baz

The program accepts the following options. Also see Common options. Options must precede operands.

`-0'

`--null'

Output a zero byte (ASCII NUL) at the end of each line, rather than a newline. This option enables other programs to parse the output of env even when that output would contain data with embedded newlines.

`-u name'

`--unset=name'

Remove variable name from the environment, if it was in the environment.

`-'

`-i'

`--ignore-environment'

Start with an empty environment, ignoring the inherited environment.

Exit status:

0   if no command is specified and the environment is output
125 if env itself fails
126 if command is found but cannot be invoked
127 if command cannot be found
the exit status of command otherwise

23.3 nice: Run a command with modified niceness

nice prints or modifies a process's niceness, a parameter that affects whether the process is scheduled favorably. Synopsis:

nice [option]… [command [arg]…]

If no arguments are given, nice prints the current niceness. Otherwise, nice runs the given command with its niceness adjusted. By default, its niceness is incremented by 10.

Niceness values range at least from -20 (process has high priority and gets more resources, thus slowing down other processes) through 19 (process has lower priority and runs slowly itself, but has less impact on the speed of other running processes). Some systems may have a wider range of nicenesses; conversely, other systems may enforce more restrictive limits. An attempt to set the niceness outside the supported range is treated as an attempt to use the minimum or maximum supported value.

A niceness should not be confused with a scheduling priority, which lets applications determine the order in which threads are scheduled to run. Unlike a priority, a niceness is merely advice to the scheduler, which the scheduler is free to ignore. Also, as a point of terminology, POSIX defines the behavior of nice in terms of a nice value, which is the nonnegative difference between a niceness and the minimum niceness. Though nice conforms to POSIX, its documentation and diagnostics use the term "niceness" for compatibility with historical practice.

command must not be a special built-in utility (see section Special built-in utilities).

Due to shell aliases and built-in nice command, using an unadorned nice interactively or in a script may get you different functionality than that described here. Invoke it via env (i.e., env nice …) to avoid interference from the shell.

The program accepts the following option. Also see Common options. Options must precede operands.

`-n adjustment'

`--adjustment=adjustment'

Add adjustment instead of 10 to the command's niceness. If adjustment is negative and you lack appropriate privileges, nice issues a warning but otherwise acts as if you specified a zero adjustment.

For compatibility nice also supports an obsolete option syntax `-adjustment'. New scripts should use `-n adjustment' instead.

Exit status:

0   if no command is specified and the niceness is output
125 if nice itself fails
126 if command is found but cannot be invoked
127 if command cannot be found
the exit status of command otherwise

It is sometimes useful to run a non-interactive program with reduced niceness.

$ nice factor 4611686018427387903

Since nice prints the current niceness, you can invoke it through itself to demonstrate how it works.

The default behavior is to increase the niceness by `10':

$ nice
0
$ nice nice
10
$ nice -n 10 nice
10

The adjustment is relative to the current niceness. In the next example, the first nice invocation runs the second one with niceness 10, and it in turn runs the final one with a niceness that is 3 more:

$ nice nice -n 3 nice
13

Specifying a niceness larger than the supported range is the same as specifying the maximum supported value:

$ nice -n 10000000000 nice
19

Only a privileged user may run a process with lower niceness:

$ nice -n -1 nice
nice: cannot set niceness: Permission denied
0
$ sudo nice -n -1 nice
-1

23.4 nohup: Run a command immune to hangups

nohup runs the given command with hangup signals ignored, so that the command can continue running in the background after you log out. Synopsis:

nohup command [arg]…

If standard input is a terminal, it is redirected from `/dev/null' so that terminal sessions do not mistakenly consider the terminal to be used by the command. This is a GNU extension; programs intended to be portable to non-GNU hosts should use `nohup command [arg]… </dev/null' instead.

If standard output is a terminal, the command's standard output is appended to the file `nohup.out'; if that cannot be written to, it is appended to the file `$HOME/nohup.out'; and if that cannot be written to, the command is not run. Any `nohup.out' or `$HOME/nohup.out' file created by nohup is made readable and writable only to the user, regardless of the current umask settings.

If standard error is a terminal, it is normally redirected to the same file descriptor as the (possibly-redirected) standard output. However, if standard output is closed, standard error terminal output is instead appended to the file `nohup.out' or `$HOME/nohup.out' as above.

To capture the command's output to a file other than `nohup.out' you can redirect it. For example, to capture the output of make:

nohup make > make.log

nohup does not automatically put the command it runs in the background; you must do that explicitly, by ending the command line with an `&'. Also, nohup does not alter the niceness of command; use nice for that, e.g., `nohup nice command'.

command must not be a special built-in utility (see section Special built-in utilities).

The only options are `--help' and `--version'. See section Common options. Options must precede operands.

Exit status:

125 if nohup itself fails, and POSIXLY_CORRECT is not set
126 if command is found but cannot be invoked
127 if command cannot be found
the exit status of command otherwise

If POSIXLY_CORRECT is set, internal failures give status 127 instead of 125.

23.5 stdbuf: Run a command with modified I/O stream buffering

stdbuf allows one to modify the buffering operations of the three standard I/O streams associated with a program. Synopsis:

stdbuf option… command

Any additional args are passed as additional arguments to the command.

The program accepts the following options. Also see Common options.

`-i mode'

`--input=mode'

Adjust the standard input stream buffering.

`-o mode'

`--output=mode'

Adjust the standard output stream buffering.

`-e mode'

`--error=mode'

Adjust the standard error stream buffering.

The mode can be specified as follows:

`L'

Set the stream to line buffered mode. In this mode data is coalesced until a newline is output or input is read from any stream attached to a terminal device. This option is invalid with standard input.

`0'

Disable buffering of the selected stream. In this mode data is output immediately and only the amount of data requested is read from input.

`size'

Specify the size of the buffer to use in fully buffered mode. size may be, or may be an integer optionally followed by, one of the following multiplicative suffixes:

`KB' => 1000 (KiloBytes) `K' => 1024 (KibiBytes) `MB' => 1000*1000 (MegaBytes) `M' => 1024*1024 (MebiBytes) `GB' => 1000*1000*1000 (GigaBytes) `G' => 1024*1024*1024 (GibiBytes)

and so on for `T', `P', `E', `Z', and `Y'.

NOTE: If command adjusts the buffering of its standard streams (tee does for e.g.) then that will override corresponding settings changed by stdbuf. Also some filters (like dd and cat etc.) don't use streams for I/O, and are thus unaffected by stdbuf settings.

Exit status:

125 if stdbuf itself fails
126 if command is found but cannot be invoked
127 if command cannot be found
the exit status of command otherwise

23.6 su: Run a command with substitute user and group ID

su allows one user to temporarily become another user. It runs a command (often an interactive shell) with the real and effective user ID, group ID, and supplemental groups of a given user. Synopsis:

su [option]… [user [arg]…]

If no user is given, the default is root, the super-user. The shell to use is taken from user's passwd entry, or `/bin/sh' if none is specified there. If user has a password, su prompts for the password unless run by a user with effective user ID of zero (the super-user).

By default, su does not change the current directory. It sets the environment variables HOME and SHELL from the password entry for user, and if user is not the super-user, sets USER and LOGNAME to user. By default, the shell is not a login shell.

Any additional args are passed as additional arguments to the shell.

GNU su does not treat `/bin/sh' or any other shells specially (e.g., by setting argv[0] to `-su', passing `-c' only to certain shells, etc.).

su can optionally be compiled to use syslog to report failed, and optionally successful, su attempts. (If the system supports syslog.) However, GNU su does not check if the user is a member of the wheel group; see below.

The program accepts the following options. Also see Common options.

`-c command'

`--command=command'

Pass command, a single command line to run, to the shell with a `-c' option instead of starting an interactive shell.

`-f'

`--fast'

Pass the `-f' option to the shell. This probably only makes sense if the shell run is csh or tcsh, for which the `-f' option prevents reading the startup file (`.cshrc'). With Bourne-like shells, the `-f' option disables file name pattern expansion (globbing), which is not likely to be useful.

`-'

`-l'

`--login'

Make the shell a login shell. This means the following. Unset all environment variables except TERM, HOME, and SHELL (which are set as described above), and USER and LOGNAME (which are set, even for the super-user, as described above), and set PATH to a compiled-in default value. Change to user's home directory. Prepend `-' to the shell's name, intended to make it read its login startup file(s).

`-m'

`-p'

`--preserve-environment'

Do not change the environment variables HOME, USER, LOGNAME, or SHELL. Run the shell given in the environment variable SHELL instead of the shell from user's passwd entry, unless the user running su is not the super-user and user's shell is restricted. A restricted shell is one that is not listed in the file `/etc/shells', or in a compiled-in list if that file does not exist. Parts of what this option does can be overridden by `--login' and `--shell'.

`-s shell'

`--shell=shell'

Run shell instead of the shell from user's passwd entry, unless the user running su is not the super-user and user's shell is restricted (see `-m' just above).

Exit status:

125 if su itself fails
126 if subshell is found but cannot be invoked
127 if subshell cannot be found
the exit status of the subshell otherwise

23.6.1 Why GNU su does not support the `wheel' group

(This section is by Richard Stallman.)

Sometimes a few of the users try to hold total power over all the rest. For example, in 1984, a few users at the MIT AI lab decided to seize power by changing the operator password on the Twenex system and keeping it secret from everyone else. (I was able to thwart this coup and give power back to the users by patching the kernel, but I wouldn't know how to do that in Unix.)

However, occasionally the rulers do tell someone. Under the usual su mechanism, once someone learns the root password who sympathizes with the ordinary users, he or she can tell the rest. The "wheel group" feature would make this impossible, and thus cement the power of the rulers.

I'm on the side of the masses, not that of the rulers. If you are used to supporting the bosses and sysadmins in whatever they do, you might find this idea strange at first.

23.7 timeout: Run a command with a time limit

timeout runs the given command and kills it if it is still running after the specified time interval. Synopsis:

timeout [option] number[smhd] command [arg]…

number is an integer followed by an optional unit; the default is seconds. The units are:

`s'

seconds

`m'

minutes

`h'

hours

`d'

days

command must not be a special built-in utility (see section Special built-in utilities).

The program accepts the following option. Also see Common options. Options must precede operands.

`-s signal'

`--signal=signal'

Send this signal to command on timeout, rather than the default `TERM' signal. signal may be a name like `HUP' or a number. Also see See section Signal specifications.

Exit status:

124 if command times out
125 if timeout itself fails
126 if command is found but cannot be invoked
127 if command cannot be found
the exit status of command otherwise

This document was generated on January, 20 2010 using texi2html 1.76.