[PATCH 04/14] Document PATH resolution

From: Bastien Roucariès <[email protected]>

Document PATH resolution, particularly null sequence and empty PATH

Signed-off-by: Bastien Roucariès <[email protected]>
---
 man7/environ.7 | 39 +++++++++++++++++++++++++++++++++++----
 1 file changed, 35 insertions(+), 4 deletions(-)

diff --git a/man7/environ.7 b/man7/environ.7
index 568962bb3..16e122154 100644
--- a/man7/environ.7
+++ b/man7/environ.7
@@ -68,7 +68,8 @@ The name of the logged-in user (used by some BSD-derived programs).
 Set a login time, see section NOTES below.
 .TP
 .B LOGNAME
-The name of the logged-in user (used by some System-V derived programs).
+The name of the logged-in user (used by some System-V derived programs
+and POSIX.1-2017).
 Set a login time, see section NOTES below.
 .TP
 .B HOME
@@ -97,16 +98,28 @@ environment variables).
 The sequence of directory prefixes that
 .BR sh (1)
 and many other
-programs apply in searching for a file known by an incomplete pathname.
+programs using
+.BR execlp (3)
+apply in searching for a file known by an incomplete pathname.
 The prefixes are separated by \(aq\fB:\fP\(aq.
-(Similarly one has
+When a non-zero-length prefix is applied to this pathname, a \(aq\fB/\fP\(aq
+(slash) shall be inserted between the prefix and the filename if the prefix
+did not end in
+\(aq\fB\(sl\fP\(aq (slash).
+A zero length prefix is a legacy sequence that indicate the current directory or
+\(aq\fB.\fP\(aq (see section BUGS below).
+The list of prefixes shall be searched from beginning to end, applying the
+pathname to each prefix, until an executable file with the specified name
+and appropriate execution permissions is found.
+.IP
+Similarly one has
 .B CDPATH
 used by some shells to find the target
 of a change directory command,
 .B MANPATH
 used by
 .BR man (1)
-to find manual pages, and so on)
+to find manual pages, and so on.
 .TP
 .B PWD
 The current working directory.
@@ -253,6 +266,9 @@ The variables
 are specified by
 POSIX.1-1996
 and should be reasonably portable.
+.PP
+.B PATH
+behavior is specified by  POSIX.1-2017.
 .SH NOTES
 The
 .BR prctl (2)
@@ -291,6 +307,12 @@ are retained from old user. Therefore,
 using
 .I su -l
 is recommended.
+.PP
+The default search path (used when the environment
+does not contain the variable \fBPATH\fR)
+shows some variation across systems. See
+.B execlp (3)
+for documentation of the exact behavior.
 .SH BUGS
 Clearly there is a security risk here.
 Many a system command has been
@@ -329,6 +351,14 @@ The authors of
 .I gzip
 should consider renaming their option to
 .BR GZIP_OPT .
+.PP
+.B PATH
+zero lengh sequence,
+that appears as two adjacent colons \(aq\fB::\fP\(aq, as a initial colon
+\(aq\fB:\fP\(aq preceding the rest of the list,
+or as a trailing colon \(aq\fB:\fP\(aq following the rest of the list,
+shall be replaced by implicit \(aq\fB.\fP\(aq, in order to be portable
+and strictly conformant to POSIX.1-2017.
 .SH SEE ALSO
 .BR bash (1),
 .BR csh (1),
@@ -342,6 +372,7 @@ should consider renaming their option to
 .BR execve (2),
 .BR clearenv (3),
 .BR exec (3),
+.BR execlp (3)
 .BR getenv (3),
 .BR putenv (3),
 .BR setenv (3),