[PATCH 03/14] Document that means at login time for HOME, LOGNAME, SHELL, USER

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

Clearly document that su by default does not change this variables.

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

diff --git a/man7/environ.7 b/man7/environ.7
index fe220cc03..568962bb3 100644
--- a/man7/environ.7
+++ b/man7/environ.7
@@ -65,15 +65,15 @@ Common examples are:
 .TP
 .B USER
 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).
+Set a login time, see section NOTES below.
 .TP
 .B HOME
-A user's login directory, set by
-.BR login (1)
-from the password file
-.BR passwd (5).
+A user's login directory, set a login time.
+Set a login time, see section NOTES below.
 .TP
 .B LANG
 The name of a locale to use for locale categories when not overridden
@@ -114,6 +114,7 @@ Set by some shells.
 .TP
 .B SHELL
 The absolute pathname of the user's login shell.
+Set a login time, see section NOTES below.
 .TP
 .B TERM
 The terminal type for which output is to be prepared.
@@ -259,6 +260,37 @@ The
 and
 .B PR_SET_MM_ENV_END
 operations can be used to control the location of the process's environment.
+.PP
+The
+.B HOME,
+.B LOGNAME,
+.B SHELL
+and
+.B USER
+variables are only set when an user is changing using
+session management interface, typically by program
+.B login(1)
+from user database (for instance, but not limited, by using
+.B password (5)
+database).
+Particularly,
+.B setuid (2)
+family of function
+or even
+.I su -p
+command, as documented in
+.B su (1),
+does not set theses variables. Notes that as documented,
+going to root by
+.I su
+result in a mixed environment where
+.B LOGNAME
+and
+.B USER
+are retained from old user. Therefore,
+using
+.I su -l
+is recommended.
 .SH BUGS
 Clearly there is a security risk here.
 Many a system command has been
@@ -305,6 +337,7 @@ should consider renaming their option to
 .BR mktemp (1),
 .BR printenv (1),
 .BR sh (1),
+.BR su (1)
 .BR tcsh (1),
 .BR execve (2),
 .BR clearenv (3),