From 0f3f6bf6bf38f1ed9c85fe98d6ac7645bf10a6c3 Mon Sep 17 00:00:00 2001
From: Eric Blake <ebb9@byu.net>
Date: Mon, 26 Oct 2009 09:26:00 -0600
Subject: [PATCH] doc: document PATH interactions with env

* doc/coreutils.texi (env invocation): Mention that PATH is
modified prior to exec.
* tests/misc/env: Test this.
---
 doc/coreutils.texi |  5 +++++
 tests/misc/env     | 24 +++++++++++++++++++++---
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index c54ffb8..8a79ba7 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -14408,6 +14408,11 @@ remaining arguments are passed as arguments to that program.
 The program should not be a special built-in utility
 (@pxref{Special built-in utilities}).
 
+Modifications to @env{PATH} take effect prior to searching for
+@var{command}.  Use caution when reducing @env{PATH}; behavior is
+not portable when @env{PATH} is undefined or omits key directories
+such as @file{/bin}.
+
 @cindex environment, printing
 
 If no command name is specified following the environment
diff --git a/tests/misc/env b/tests/misc/env
index 07dd9e4..e1e51ed 100755
--- a/tests/misc/env
+++ b/tests/misc/env
@@ -51,9 +51,16 @@ test $? = 126 || fail=1
 env no_such # no such command
 test $? = 127 || fail=1
 
-# Cygwin requires a minimal environment to launch new processes, so a
-# subsequent env will show more than just what we set.  Hence, it is
-# more portable to grep that our desired changes took place.
+# POSIX is clear that environ may, but need not be, sorted.
+# Environment variable values may contain newlines, which cannot be
+# observed by merely inspecting output from env.
+# Cygwin requires a minimal environment to launch new processes: execve
+# adds missing variables SYSTEMROOT and WINDIR, which show up in a
+# subsequent env.  Cygwin also requires /bin to always be part of PATH,
+# and attempts to unset or reduce PATH may cause execve to fail.
+#
+# For these reasons, it is more portable to grep that our desired changes
+# took place, rather than comparing output of env over an entire environment.
 if env | grep '^ENV_TEST' >/dev/null ; then
   skip_test_ "environment has potential interference from ENV_TEST*"
 fi
@@ -85,6 +92,17 @@ ENV_TEST1=b
 EOF
 compare exp out || fail=1
 
+# PATH modifications affect exec.
+mkdir unlikely_name || framework_failure
+cat <<EOF > unlikely_name/also_unlikely || framework_failure
+#!/bin/sh
+echo pass
+EOF
+chmod +x unlikely_name/also_unlikely || framework_failure
+env also_unlikely && fail=1
+test x`PATH=$PATH:unlikely_name env also_unlikely` = xpass || fail=1
+test x`env PATH="$PATH":unlikely_name also_unlikely` = xpass || fail=1
+
 # Use -- to end arguments.
 ln -s "$abs_top_builddir/src/echo" ./-i || framework_failure
 case `PATH="$PATH:" env -i echo good` in
-- 
2.7.4