From 37147e18b6cb697e3f52de8d561afe6bca8ecd08 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bastien=20Roucari=C3=A8s?= <rouca@debian.org>
Date: Fri, 29 Jan 2021 23:29:40 +0000
Subject: [PATCH] environ.7: Document that HOME, LOGNAME, SHELL, USER are set
 at login time
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clearly document that HOME, LOGNAME, SHELL and USER are set at
login time by a program like such as login(1).

Document also that using su could result in a mixed environment,
and point to the su(1) manual page.

[mtk: edited commit message]

Signed-off-by: Bastien Roucariès <rouca@debian.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man7/environ.7 | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/man7/environ.7 b/man7/environ.7
index 39959f1f7..2a8a045c0 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 at login time, see section NOTES below.
 .TP
 .B LOGNAME
 The name of the logged-in user (used by some System-V derived programs).
+Set at 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 at login time, see section NOTES below.
 .TP
 .B LANG
 The name of a locale to use for locale categories when not overridden
@@ -131,6 +131,7 @@ Set by some shells.
 .TP
 .B SHELL
 The absolute pathname of the user's login shell.
+Set at login time, see section NOTES below.
 .TP
 .B TERM
 The terminal type for which output is to be prepared.
@@ -277,6 +278,30 @@ 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,
+.BR setuid (2)
+family of function
+does not set theses variables. Notes that as documented,
+going to root by
+.BR su (8)
+may result in a mixed environment where
+.B LOGNAME
+and
+.B USER
+are retained from old user.
 .SH BUGS
 Clearly there is a security risk here.
 Many a system command has been
@@ -322,6 +347,7 @@ should consider renaming their option to
 .BR login (1),
 .BR printenv (1),
 .BR sh (1),
+.BR su (1),
 .BR tcsh (1),
 .BR execve (2),
 .BR clearenv (3),