Re: env: mention variables the shell wouldn't allow one to set

[Paul Eggert]

Dan Jacobson <address@hidden> writes:

> $ env k-o=4 ...

OK, thanks, I installed this patch to address this and a somewhat-related
issue (special built-in utilities).

2004-10-11  Paul Eggert  <address@hidden>

        * coreutils.texi (Special built-in utilities): New node.
        (printf invocation): builtin -> built-in, for consistency
        with POSIX terminology.
        (test invocation, pwd invocation):
        Use specific rather than generic language to warn about
        built-in commands.
        (chroot invocation, env invocation, nice invocation, nohup invocation):
        Warn that command must not be a special built-in.
        (env invocation): Warn about environment variables with unusual
        spellings, or duplicates.

Index: coreutils.texi
===================================================================
RCS file: /fetish/cu/doc/coreutils.texi,v
retrieving revision 1.216
retrieving revision 1.218
diff -p -u -r1.216 -r1.218
--- coreutils.texi      26 Sep 2004 22:56:04 -0000      1.216
+++ coreutils.texi      11 Oct 2004 23:47:20 -0000      1.218
@@ -649,6 +649,7 @@ name.
 * Trailing slashes::            --strip-trailing-slashes, in some programs.
 * Traversing symlinks::         -H, -L, or -P, in some programs.
 * Treating / specially::        --preserve-root and --no-preserve-root.
+* Special built-in utilities::  @command{break}, @command{:}, @command{eval}, 
@dots{}
 * Standards conformance::       Conformance to the @acronym{POSIX} standard.
 @end menu
 
@@ -1126,6 +1127,34 @@ when operating recursively on @file{/}, 
 more quickly, and hence damage more files before an alert user can
 interrupt them.
 
address@hidden Special built-in utilities
address@hidden Special built-in utilities
+
+Some programs like @command{nice} can invoke other programs; for
+example, the command @samp{nice cat file} invokes the program
address@hidden by executing the command @samp{cat file}.  However,
address@hidden built-in utilities} like @command{exit} cannot be invoked
+this way.  For example, the command @samp{nice exit} does not have a
+well-defined behavior: it may generate an error message instead of
+exiting.
+
+Here is a list of the special built-in utilities that are standardized
+by @acronym{POSIX} 1003.1-2004.
+
address@hidden
address@hidden@: : break continue eval exec exit export readonly
+return set shift times trap unset}
address@hidden quotation
+
+For example, because @samp{.}, @samp{:}, and @samp{exec} are special,
+the commands @samp{nice . foo.sh}, @samp{nice :}, and @samp{nice exec
+pwd} do not work as you might expect.
+
+Many shells extend this list.  For example, Bash has several extra
+special built-in utilities like @command{history}, and
address@hidden, and with Bash the command @samp{nice suspend}
+generates an error message instead of suspending.
+
 @node Standards conformance
 @section Standards conformance
 
@@ -9277,7 +9306,7 @@ $ /usr/local/bin/printf '\u4e2d\u6587'
 will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8, etc).
 
 Note that in these examples, the full name of @command{printf} has been
-given, to distinguish it from the GNU @code{bash} builtin function
+given, to distinguish it from the GNU @code{bash} built-in function
 @command{printf}.
 
 For larger strings, you don't need to look up the hexadecimal code
@@ -9430,8 +9459,8 @@ test
 
 @cindex conflicts with shell built-ins
 @cindex built-in shell commands, conflicts with
-Because most shells have a built-in command by the same name, using the
-unadorned command name in a script or interactively may get you
+Because most shells have a built-in @command{test} command, using an
+unadorned @command{test} in a script or interactively may get you
 different functionality than that described here.
 
 If @var{expression} is omitted, @command{test} returns false.
@@ -10200,8 +10229,8 @@ names---none will be symbolic links.
 
 @cindex conflicts with shell built-ins
 @cindex built-in shell commands, conflicts with
-Because most shells have a built-in command by the same name, using the
-unadorned command name in a script or interactively may get you
+Because most shells have a built-in @command{pwd} command, using an
+unadorned @command{pwd} in a script or interactively may get you
 different functionality than that described here.
 
 The only options are a lone @option{--help} or
@@ -12016,6 +12045,8 @@ the directory @var{newroot} (which must 
 @var{command} with optional @var{args}.  If @var{command} is not
 specified, the default is the value of the @env{SHELL} environment
 variable or @command{/bin/sh} if not set, invoked with the @option{-i} option.
address@hidden must not be a special built-in utility
+(@pxref{Special built-in utilities}).
 
 The only options are @option{--help} and @option{--version}.  @xref{Common
 options}.  Options must precede operands.
@@ -12075,21 +12106,33 @@ env address@hidden@dots{} address@hidden@v
 env
 @end example
 
-Arguments of the form @address@hidden@var{value}} set
+Operands of the form @address@hidden@var{value}} set
 the environment variable @var{variable} to value @var{value}.
 @var{value} may be empty (@address@hidden).  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 @samp{=} and the null character (@acronym{ASCII}
address@hidden).  However, it is wise to limit yourself to names that
+consist solely of underscores, digits, and @acronym{ASCII} letters,
+and that begin with a non-digit, as applications like the shell do not
+work well with other names.
 
 @vindex PATH
-The first remaining argument specifies the program name to invoke; it is
+The first operand that does not contain the character @samp{=}
+specifies the program to invoke; it is
 searched for according to the @env{PATH} environment variable.  Any
 remaining arguments are passed as arguments to that program.
+The program should not be a special built-in utility
+(@pxref{Special built-in utilities}).
 
 @cindex environment, printing
 
 If no command name is specified following the environment
 specifications, the resulting environment is printed.  This is like
-specifying a command name of @command{printenv}.
+specifying the @command{printenv} program.
 
 The program accepts the following options.  Also see @ref{Common options}.
 Options must precede operands.
@@ -12155,10 +12198,13 @@ enforce more restrictive limits.  An att
 outside the supported range is treated as an attempt to use the
 minimum or maximum supported value.
 
address@hidden must not be a special built-in utility (@pxref{Special
+built-in utilities}).
+
 @cindex conflicts with shell built-ins
 @cindex built-in shell commands, conflicts with
-Because many shells have a built-in command by the same name, using the
-unadorned command name in a script or interactively may get you
+Because many shells have a built-in @command{nice} command, using an
+unadorned @command{nice} in a script or interactively may get you
 different functionality than that described here.
 
 The program accepts the following option.  Also see @ref{Common options}.
@@ -12280,6 +12326,9 @@ with an @samp{&}.  Also, @command{nohup}
 scheduling priority of @var{command}; use @command{nice} for that,
 e.g., @samp{nohup nice @var{command}}.
 
address@hidden must not be a special built-in utility (@pxref{Special
+built-in utilities}).
+
 The only options are @option{--help} and @option{--version}.  @xref{Common
 options}.  Options must precede operands.