From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sun, 27 Jul 2025 17:29:42 +0000 (-0700)
Subject: doc: update cd info
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=b1eb59a78a0d5f1bdb10bc8869d5e48f73dcbc7a;p=thirdparty%2Fautoconf.git

doc: update cd info

* doc/autoconf.texi: Modernize and update description
of cd gotchas.  Prompted by email from Farblos in:
https://lists.gnu.org/r/autoconf/2025-07/msg00004.html
---

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 78bbec032..c6b23c78e 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -17145,6 +17145,12 @@ output via terminal escape sequences, and the result can cause spurious
 failures when the output is not directed to a terminal.  Configure
 scripts use M4sh, which automatically unsets this variable.
 
+@item HOME
+@evindex HOME
+Strange things can happen if @env{HOME} is unset or empty.
+For example, plain @command{cd} (with no arguments) has unspecified behavior.
+Also, @env{HOME} should be absolute, not relative.
+
 @item IFS
 @evindex IFS
 Long ago, shell scripts inherited @env{IFS} from the environment,
@@ -17380,6 +17386,12 @@ than 3.1.6-dev-18.  If you are using an older @command{zsh}
 and forget to set @env{NULLCMD},
 your script might be suspended waiting for data on its standard input.
 
+@item OLDPWD
+@evindex OLDPWD
+POSIX requires that @command{cd} must update the @env{OLDPWD}
+environment variable, if set, to point to the name of the previous
+directory, but Solaris 10 @command{/bin/sh} does not support this.
+
 @item options
 @evindex options
 For @command{zsh} 4.3.10, @env{options} is treated as an associative
@@ -17860,8 +17872,26 @@ Also, Autoconf-generated scripts check for this problem when computing
 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
 so it is safe to @command{cd} to these variables.
 
-POSIX states that behavior is undefined if @command{cd} is given an
-explicit empty argument.  Some shells do nothing, some change to the
+POSIX specifies an @option{-e} option that affects the exit status
+when the @option{-P} option is in effect.  Portable scripts should
+avoid it for the same reason they avoid @option{-P}.
+
+@evindex OLDPWD
+@evindex PWD
+POSIX says that a successful @command{cd} updates the values of the
+@env{OLDPWD} and @env{PWD} variables, and that @command{cd -} acts like
+@command{cd $OLDPWD}.  Older shells, such as Solaris 10
+@command{/bin/sh}, do not support this and portable scripts should not
+rely on it.
+
+@evindex HOME
+If @env{HOME} is unset or empty, the behavior of @command{cd} with no
+arguments is implementation-defined, so portable scripts should avoid it
+in that case.
+
+POSIX 1003.1-2024 states that @command{cd} must fail if given an
+explicit empty argument.  However, earlier POSIX editions did not
+specify the behavior and some shells do nothing, some change to the
 first entry in @env{CDPATH}, some change to @env{HOME}, and some exit
 the shell rather than returning an error.  Unfortunately, this means
 that if @samp{$var} is empty, then @samp{cd "$var"} is less predictable
@@ -17870,6 +17900,11 @@ at changing to @env{HOME}, although this is probably not what you wanted
 in a script).  You should check that a directory name was supplied
 before trying to change locations.
 
+If @command{cd} fails, POSIX requires the invoking shell to behave as if
+@command{cd} exited with status 1, which means the invoking shell can continue.
+However, Solaris 10 @command{/bin/sh} aborts the containing command if
+interactive, and exits otherwise.
+
 @xref{Special Shell Variables}, for portability problems involving
 @command{cd} and the @env{CDPATH} environment variable.
 Also please see the discussion of the @command{pwd} command.