[PATCH 1/2] docs: avoid use of $tmp outside of config.status use

[Eric Blake]

* doc/autoconf.texi (Polymorphic Variables, Shell Substitutions):
Use $var or $t instead.
(Limitations of Usual Tools): Use $dir instead.
(Initialization Macros) <AS_TMPDIR>: Make good on the NEWS
regarding AS_TMPDIR being documented as consuming $tmp.
Suggested by Ralf Wildenhues.

Signed-off-by: Eric Blake <address@hidden>
---

I noticed that the only mention of $tmp being public was in NEWS;
this adds it to the docs as well as fixing all unrelated uses to
pick a different name.

 ChangeLog         |   10 +++++++++
 doc/autoconf.texi |   55 +++++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 51 insertions(+), 14 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 6accc2f..3128ac8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2010-08-27  Eric Blake  <address@hidden>
+
+       docs: avoid use of $tmp outside of config.status use
+       * doc/autoconf.texi (Polymorphic Variables, Shell Substitutions):
+       Use $var or $t instead.
+       (Limitations of Usual Tools): Use $dir instead.
+       (Initialization Macros) <AS_TMPDIR>: Make good on the NEWS
+       regarding AS_TMPDIR being documented as consuming $tmp.
+       Suggested by Ralf Wildenhues.
+
 2010-08-27  Ralf Wildenhues  <address@hidden>

        Avoid long lines in testsuite script.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 19f00bd..840b4fe 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -13442,8 +13442,8 @@ Polymorphic Variables
 AC_DEFUN([MY_ACTION],
 [AS_LITERAL_IF([$1],
   [echo "$$1"],
-  [AS_VAR_COPY([tmp], [$1])
-   echo "$tmp"],
+  [AS_VAR_COPY([var], [$1])
+   echo "$var"],
   [eval 'echo "$'"$1"\"])])
 foo=bar bar=hello
 MY_ACTION([bar])
@@ -13462,8 +13462,8 @@ Polymorphic Variables
 For situations where the final contents of @var{var} are relatively
 short (less than 256 bytes), it is more efficient to use the simpler
 code sequence of @address@hidden@address@hidden@address@hidden (or its
-polymorphic equivalent of @code{AS_VAR_COPY([tmp], address@hidden)} and
address@hidden(address@hidden, ["$tmp"@var{text}])}).  But in the case
+polymorphic equivalent of @code{AS_VAR_COPY([t], address@hidden)} and
address@hidden(address@hidden, ["$t"@var{text}])}).  But in the case
 when the script will be repeatedly appending text into @code{var},
 issues of scaling start to become apparent.  A naive implementation
 requires execution time linear to the length of the current contents of
@@ -13702,6 +13702,33 @@ Initialization Macros
 configure scripts.
 @end defmac

address@hidden AS_TMPDIR (@var{prefix}, @dvar{dir, 
address@hidden:=/address@hidden)
address@hidden
address@hidden TMPDIR
address@hidden tmp
+Create, as safely as possible, a temporary sub-directory within
address@hidden with a name starting with @var{prefix}.  @var{prefix} should
+be 2-4 characters, to make it slightly easier to identify the owner of
+the directory.  If @var{dir} is omitted, then the value of @env{TMPDIR}
+will be used (defaulting to @samp{/tmp}).  On success, the name of the
+newly created directory is stored in the shell variable @code{tmp}.  On
+error, the script is aborted.
+
+Typically, this macro is coupled with some exit traps to delete the created
+directory and its contents on exit or interrupt.  However, there is a
+slight window between when the directory is created and when the name is
+actually known to the shell, so an interrupt at the right moment might
+leave the temporary directory behind.  Hence it is important to use a
address@hidden that makes it easier to determine if a leftover temporary
+directory from an interrupted script is safe to delete.
+
+The use of the output variable @samp{$tmp} rather than something in the
address@hidden namespace is historical; it has the unfortunate consequence
+that reusing this otherwise common name for any other purpose inside
+your script has the potential to break any cleanup traps designed to
+remove the temporary directory.
address@hidden defmac
+
 @defmac AS_SHELL_SANITIZE
 @asindex{SHELL_SANITIZE}
 Initialize the shell suitably for @command{configure} scripts.  This has
@@ -15475,15 +15502,15 @@ Shell Substitutions

 Perhaps the easiest way to work around quoting issues in a manner
 portable to all shells is to place the results in a temporary variable,
-then use @samp{$tmp} as the @var{value}, rather than trying to inline
+then use @samp{$t} as the @var{value}, rather than trying to inline
 the expression needing quoting.

 @example
-$ @kbd{/bin/sh -c 'tmp="a  b\"'\''@}\\"; echo "address@hidden@}"'}
+$ @kbd{/bin/sh -c 't="a  b\"'\''@}\\"; echo "address@hidden@}"'}
 b  c"'@}\
-$ @kbd{ksh -c 'tmp="a  b\"'\''@}\\"; echo "address@hidden@}"'}
+$ @kbd{ksh -c 't="a  b\"'\''@}\\"; echo "address@hidden@}"'}
 b  c"'@}\
-$ @kbd{bash -c 'tmp="a  b\"'\''@}\\"; echo "address@hidden@}"'}
+$ @kbd{bash -c 't="a  b\"'\''@}\\"; echo "address@hidden@}"'}
 b  c"'@}\
 @end example

@@ -18428,22 +18455,22 @@ Limitations of Usual Tools
 gaining control, though @command{mktemp} is far less likely to fail
 gratuitously under attack.

-Here is sample code to create a new temporary directory safely:
+Here is sample code to create a new temporary directory @samp{$dir} safely:

 @example
-# Create a temporary directory $tmp in $TMPDIR (default /tmp).
+# Create a temporary directory $dir in $TMPDIR (default /tmp).
 # Use mktemp if possible; otherwise fall back on mkdir,
 # with $RANDOM to make collisions less likely.
 : "address@hidden:=/address@hidden"
 @{
-  tmp=`
+  dir=`
     (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
   ` &&
-  test -n "$tmp" && test -d "$tmp"
+  test -d "$dir"
 @} || @{
-  tmp=$TMPDIR/foo$$-$RANDOM
+  dir=$TMPDIR/foo$$-$RANDOM
 @c $$ restore font-lock
-  (umask 077 && mkdir "$tmp")
+  (umask 077 && mkdir "$dir")
 @} || exit $?
 @end example

-- 
1.7.2.2