Add 'file-user-uid' to get the connection-local effective UID

In particular, this lets Eshell show a "#" root prompt sigil when the
user has sudo'ed via "cd /sudo::" (bug#60722).

* lisp/simple.el (file-user-uid): New function.

* lisp/net/tramp.el (tramp-file-name-for-operation): Add
'file-user-uid'.
(tramp-handle-file-user-uid): New function.

* lisp/net/tramp-adb.el (tramp-adb-file-name-handler-alist):
* lisp/net/tramp-crypt.el (tramp-crypt-file-name-handler-alist):
* lisp/net/tramp-gvfs.el (tramp-gvfs-file-name-handler-alist):
* lisp/net/tramp-rclone.el (tramp-rclone-file-name-handler-alist):
* lisp/net/tramp-sh.el (tramp-sh-file-name-handler-alist):
* lisp/net/tramp-smb.el (tramp-smb-file-name-handler-alist):
* lisp/net/tramp-sshfs.el (tramp-sshfs-file-name-handler-alist):
* lisp/net/tramp-sudoedit.el (tramp-sudoedit-file-name-handler-alist):
Add 'file-user-uid'.

* lisp/net/tramp-archive.el (tramp-archive-handle-file-user-uid): New
function...
(tramp-archive-file-name-handler-alist): ... use it.

* lisp/eshell/em-prompt.el (eshell-prompt-function): Use
'file-user-uid'.

* lisp/eshell/esh-var.el (eshell-variable-aliases-list): Add '$UID'.

* test/lisp/eshell/esh-var-tests.el (esh-var-test/uid-var): New test.

* doc/lispref/os.texi (User Identification): Document 'file-user-uid'.

* doc/lispref/files.texi (Magic File Names): Mention 'file-user-uid'.

* doc/misc/eshell.texi (Variables): Document '$UID'.  Add a missing
index entry for '$INSIDE_EMACS'.

* etc/NEWS: Announce 'file-user-uid'.

3 files changed, 22 insertions, 2 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 5cc4c1e7ddf..ad01e0f2886 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -3390,7 +3390,8 @@ first, before handlers for jobs such as remote file access.
 @code{file-readable-p}, @code{file-regular-p},
 @code{file-remote-p}, @code{file-selinux-context},
 @code{file-symlink-p}, @code{file-system-info},
-@code{file-truename}, @code{file-writable-p},
+@code{file-truename}, @code{file-user-uid},
+@code{file-writable-p},
 @code{find-backup-file-name},@*
 @code{get-file-buffer},
 @code{insert-directory},
@@ -3451,7 +3452,8 @@ first, before handlers for jobs such as remote file access.
 @code{file-readable-p}, @code{file-regular-p},
 @code{file-remote-p}, @code{file-selinux-context},
 @code{file-symlink-p}, @code{file-system-info},
-@code{file-truename}, @code{file-writable-p},
+@code{file-truename}, @code{file-user-uid},
+@code{file-writable-p},
 @code{find-backup-file-name},
 @code{get-file-buffer},
 @code{insert-directory},
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 3be7036f637..bca62a7a8de 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1277,6 +1277,16 @@ This function returns the real @acronym{UID} of the user.
 This function returns the effective @acronym{UID} of the user.
 @end defun
 
+@defun file-user-uid
+This function returns the connection-local value for the user's
+effective @acronym{UID}.  If @code{default-directory} is local, this
+is equivalent to @code{user-uid}, but for remote files (@pxref{Remote
+Files, , , emacs, The GNU Emacs Manual}), it will return the
+@acronym{UID} for the user associated with that remote connection; if
+the remote connection has no associated user, it will instead return
+-1.
+@end defun
+
 @cindex GID
 @defun group-gid
 This function returns the effective @acronym{GID} of the Emacs process.
diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index fc7d52eb711..c40ff58f42c 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -983,6 +983,13 @@ whenever you change the current directory to a different host
 the value will automatically update to reflect the search path on that
 host.
 
+@vindex $UID
+@item $UID
+This returns the effective @acronym{UID} for the current user.  This
+variable is connection-aware, so when the current directory is remote,
+its value will be @acronym{UID} for the user associated with that
+remote connection.
+
 @vindex $_
 @item $_
 This refers to the last argument of the last command.  With a
@@ -1014,6 +1021,7 @@ that are currently visible in the Eshell window.  They are both
 copied to the environment, so external commands invoked from
 Eshell can consult them to do the right thing.
 
+@vindex $INSIDE_EMACS
 @item $INSIDE_EMACS
 This variable indicates to external commands that they are being
 invoked from within Emacs so they can adjust their behavior if