Introduce process-file-return-signal-string

* doc/lispref/processes.texi (Synchronous Processes):
Describe `process-file-return-signal-string'.

* doc/misc/tramp.texi: Adapt Tramp and Emacs version numbers.
(Remote processes): Describe `process-file-return-signal-string'
and $INSIDE_EMACS.

* etc/NEWS: Describe `process-file-return-signal-string'.  Fix typos.

* lisp/simple.el (process-file-return-signal-string): New user option.

* lisp/net/tramp-adb.el (tramp-adb-handle-process-file):
* lisp/net/tramp-sh.el (tramp-sh-handle-process-file): Use it.

* lisp/net/tramp.el (tramp-get-signal-strings): New defun.

* test/lisp/net/tramp-tests.el (tramp-test28-process-file): Adapt test.

8 files changed, 164 insertions, 73 deletions

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index c6e735a9b1e..22c50936185 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -477,6 +477,22 @@ You should only ever change this variable with a let-binding; never
 with @code{setq}.
 @end defvar
 
+@defopt process-file-return-signal-string
+This user option indicates whether a call of @code{process-file}
+returns a string describing the signal interrupting a remote process.
+
+When a process returns an exit code greater than 128, it is
+interpreted as a signal.  @code{process-file} requires to return a
+string describing this signal.
+
+Since there are processes violating this rule, returning exit codes
+greater than 128 which are not bound to a signal, @code{process-file}
+returns always the exit code as natural number for remote processes.
+Setting this user option to non-nil forces @code{process-file} to
+interpret such exit codes as signals, and to return a corresponding
+string.
+@end defopt
+
 @defun call-process-region start end program &optional delete destination display &rest args
 This function sends the text from @var{start} to @var{end} as
 standard input to a process running @var{program}.  It deletes the text
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 0b13c17dbcf..d1688deb1b7 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -318,14 +318,14 @@ behind the scenes when you open a file with @value{tramp}.
 @uref{https://ftp.gnu.org/gnu/tramp/}.  The version number of
 @value{tramp} can be obtained by the variable @code{tramp-version}.
 For released @value{tramp} versions, this is a three-number string
-like ``2.4.2''.
+like ``2.4.3''.
 
 A @value{tramp} release, which is packaged with Emacs, could differ
 slightly from the corresponding standalone release.  This is because
 it isn't always possible to synchronize release dates between Emacs
 and @value{tramp}.  Such version numbers have the Emacs version number
-as suffix, like ``2.3.5.26.3''.  This means @w{@value{tramp} 2.3.5} as
-integrated in @w{Emacs 26.3}.  A complete list of @value{tramp}
+as suffix, like ``2.4.3.27.1''.  This means @w{@value{tramp} 2.4.3} as
+integrated in @w{Emacs 27.1}.  A complete list of @value{tramp}
 versions packaged with Emacs can be retrieved by
 
 @vindex customize-package-emacs-version-alist
@@ -337,12 +337,12 @@ versions packaged with Emacs can be retrieved by
 ELPA} package.  Besides the standalone releases, further minor version
 of @value{tramp} will appear on GNU ELPA, until the next @value{tramp}
 release appears.  These minor versions have a four-number string, like
-``2.4.2.1''.
+``2.4.3.1''.
 
 @value{tramp} development versions are available on Git servers.
 Development versions contain new and incomplete features.  The
 development version of @value{tramp} is always the version number of
-the next release, plus the suffix ``-pre'', like ``2.4.3-pre''.
+the next release, plus the suffix ``-pre'', like ``2.4.4-pre''.
 
 One way to obtain @value{tramp} from Git server is to visit the
 Savannah project page at the following URL and then clicking on the
@@ -2315,7 +2315,7 @@ string of that environment variable looks always like
 @example
 @group
 echo $INSIDE_EMACS
-@result{} 26.2,tramp:2.3.4
+@result{} 27.1,tramp:2.4.3
 @end group
 @end example
 
@@ -3050,6 +3050,17 @@ host when the variable @code{default-directory} is remote:
 @end group
 @end lisp
 
+@vindex process-file-return-signal-string
+@code{process-file} shall return either the exit code of the process,
+or a string describing the signal, when the process has been
+interrupted.  Since it cannot be determined reliably whether a remote
+process has been interrupted, @code{process-file} returns always the
+exit code.  When the user option
+@code{process-file-return-signal-string} is non-nil,
+@code{process-file} regards all exit codes greater than 128 as an
+indication that the process has been interrupted, and returns a
+respective string.
+
 Remote processes do not apply to @acronym{GVFS} (see @ref{GVFS-based
 methods}) because the remote file system is mounted on the local host
 and @value{tramp} just accesses by changing the
@@ -3057,9 +3068,17 @@ and @value{tramp} just accesses by changing the
 
 @value{tramp} starts a remote process when a command is executed in a
 remote file or directory buffer.  As of now, these packages have been
-integrated to work with @value{tramp}: @file{compile.el} (commands
-like @code{compile} and @code{grep}) and @file{gud.el} (@code{gdb} or
-@code{perldb}).
+integrated to work with @value{tramp}: @file{shell.el},
+@file{eshell.el}, @file{compile.el} (commands like @code{compile} and
+@code{grep}) and @file{gud.el} (@code{gdb} or @code{perldb}).
+
+@vindex INSIDE_EMACS@r{, environment variable}
+@value{tramp} always modifies the @env{INSIDE_EMACS} environment
+variable for remote processes.  Per default, this environment variable
+shows the Emacs version.  @value{tramp} adds its own version string,
+so it looks like @samp{27.1,tramp:2.4.3.1}.  However, other packages
+might also add their name to this environment variable, like
+@samp{27.1,comint,tramp:2.4.3.1}.
 
 For @value{tramp} to find the command on the remote, it must be
 accessible through the default search path as setup by @value{tramp}
@@ -3254,7 +3273,7 @@ variables.
 @vindex async-shell-command-width
 @vindex COLUMNS@r{, environment variable}
 If Emacs supports the variable @code{async-shell-command-width} (since
-@w{Emacs 27.1}), @value{tramp} cares about its value for asynchronous
+@w{Emacs 27}), @value{tramp} cares about its value for asynchronous
 shell commands.  It specifies the number of display columns for
 command output.  For synchronous shell commands, a similar effect can
 be achieved by adding the environment variable @env{COLUMNS} to
@@ -3741,7 +3760,7 @@ row are possible, like @file{/path/to/dir/file.tar.gz.uu/dir/file}.
 
 @vindex tramp-archive-all-gvfs-methods
 An archive file name could be a remote file name, as in
-@file{/ftp:anonymous@@ftp.gnu.org:/gnu/tramp/tramp-2.3.2.tar.gz/INSTALL}.
+@file{/ftp:anonymous@@ftp.gnu.org:/gnu/tramp/tramp-2.4.3.tar.gz/INSTALL}.
 Since all file operations are mapped internally to @acronym{GVFS}
 operations, remote file names supported by @code{tramp-gvfs} perform
 better, because no local copy of the file archive must be downloaded
@@ -3752,7 +3771,7 @@ the similar @samp{/scp:user@@host:...}.  See the constant
 
 If @code{url-handler-mode} is enabled, archives could be visited via
 URLs, like
-@file{https://ftp.gnu.org/gnu/tramp/tramp-2.3.2.tar.gz/INSTALL}.  This
+@file{https://ftp.gnu.org/gnu/tramp/tramp-2.4.3.tar.gz/INSTALL}.  This
 allows complex file operations like
 
 @lisp
@@ -3760,8 +3779,8 @@ allows complex file operations like
 (progn
   (url-handler-mode 1)
   (ediff-directories
-   "https://ftp.gnu.org/gnu/tramp/tramp-2.3.1.tar.gz/tramp-2.3.1"
-   "https://ftp.gnu.org/gnu/tramp/tramp-2.3.2.tar.gz/tramp-2.3.2" ""))
+   "https://ftp.gnu.org/gnu/tramp/tramp-2.4.2.tar.gz/tramp-2.4.2"
+   "https://ftp.gnu.org/gnu/tramp/tramp-2.4.3.tar.gz/tramp-2.4.3" ""))
 @end group
 @end lisp
 
diff --git a/etc/NEWS b/etc/NEWS
index b93199f362f..303036ece34 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -101,19 +101,23 @@ horizontal movements now stop at the edge of the board.
 
 * Changes in Specialized Modes and Packages in Emacs 28.1
 
-** EIEIO: 'oset' and 'oset-default' are declared obsolete
+** EIEIO: 'oset' and 'oset-default' are declared obsolete.
 
-** New minor mode 'cl-font-lock-built-in-mode' for `lisp-mode'
+** New minor mode 'cl-font-lock-built-in-mode' for `lisp-mode'.
 The mode provides refined highlighting of built-in functions, types,
 and variables.
 
-** archive-mode
+** Archive mode
+
 *** Can now modify members of 'ar' archives.
-*** Display of summaries unified between backends
-*** New var 'archive-hidden-columns' and cmd 'archive-hideshow-column'
-These let you control which columns are displayed and which are kept hidden
 
-** Emacs-Lisp mode
+*** Display of summaries unified between backends.
+
+*** New user option 'archive-hidden-columns' and command
+'archive-hideshow-column'.  These let you control which columns are
+displayed and which are kept hidden.
+
+** Emacs Lisp mode
 
 *** The mode-line now indicates whether we're using lexical or dynamic scoping.
 
@@ -158,7 +162,7 @@ this user option.
 This file was a compatibility kludge which is no longer needed.
 
 ---
-** 'lisp-mode' now uses 'common-lisp-indent-function'.
+** Lisp mode now uses 'common-lisp-indent-function'.
 To revert to the previous behaviour,
 '(setq lisp-indent-function 'lisp-indent-function)' from 'lisp-mode-hook'.
 
@@ -184,7 +188,7 @@ their backends.
 ** Eshell
 
 ---
-*** Environment variable INSIDE_EMACS is now copied to subprocesses.
+*** Environment variable 'INSIDE_EMACS' is now copied to subprocesses.
 Its value equals the result of evaluating '(format "%s,eshell" emacs-version)'.
 
 ** Tramp
@@ -240,7 +244,7 @@ it after GDB quits.  A toggle button is also provided under 'Gud --
 GDB-Windows'.
 
 +++
-*** gdb-mi now has a better logic for displaying source buffers
+*** gdb-mi now has a better logic for displaying source buffers.
 Now GDB only uses one source window to display source file by default.
 Customize 'gdb-max-source-window-count' to use more than one window.
 Control source file display by 'gdb-display-source-buffer-action'.
@@ -259,11 +263,11 @@ case-insensitive matching of messages when the old behaviour is
 required, but the recommended solution is to use a correctly matching
 regexp instead.
 
-** Hi-Lock
+** Hi Lock mode
 
 ---
 *** Matching in 'hi-lock-mode' is case-sensitive when regexp contains
-upper case characters and `search-upper-case' is non-nil.
+upper case characters and 'search-upper-case' is non-nil.
 'highlight-phrase' also uses 'search-whitespace-regexp'
 to substitute spaces in regexp search.
 
@@ -274,13 +278,13 @@ The new default value is 2000000 (2 megabytes).
 ** Texinfo
 
 ---
-*** New customizable option 'texinfo-texi2dvi-options'.
+*** New user option 'texinfo-texi2dvi-options'.
 This is used when invoking 'texi2dvi' from 'texinfo-tex-buffer'.
 
 ** Rmail
 
 ---
-*** New customizable option 'rmail-re-abbrevs'.
+*** New user option 'rmail-re-abbrevs'.
 Its default value matches localized abbreviations of the "reply"
 prefix on the Subject line in various languages.
 
@@ -290,13 +294,13 @@ prefix on the Subject line in various languages.
 These new navigation commands are bound to 'n' and 'p' in
 'apropos-mode'.
 
-** cc-mode
+** CC mode
 
 *** Added support for Doxygen documentation style.
-‘doxygen’ is now valid ‘c-doc-comment-style’ which recognises all
-comment styles supported by Doxygen (namely ‘///’, ‘//!’, ‘/** … */’
-and ‘/*! … */’.  ‘gtkdoc’ remains the default for C and C++ modes; to
-use ‘doxygen’ by default one might evaluate:
+'doxygen' is now a valid 'c-doc-comment-style' which recognises all
+comment styles supported by Doxygen (namely '///', '//!', '/** … */'
+and '/*! … */'.  'gtkdoc' remains the default for C and C++ modes; to
+use 'doxygen' by default one might evaluate:
 
     (setq-default c-doc-comment-style
                   '((java-mode . javadoc)
@@ -304,17 +308,17 @@ use ‘doxygen’ by default one might evaluate:
                     (c-mode    . doxygen)
                     (c++-mode  . doxygen)))
 
-or use it in a custom ‘c-style’.
+or use it in a custom 'c-style'.
 
-*** Added support to line up ‘?’ and ‘:’ of a ternary operator.
-The new ‘c-lineup-ternary-bodies’ function can be used as a lineup
+*** Added support to line up '?' and ':' of a ternary operator.
+The new 'c-lineup-ternary-bodies' function can be used as a lineup
 function to align question mark and colon which are part of a ternary
-operator (‘?:’).  For example:
+operator ('?:').  For example:
 
     return arg % 2 == 0 ? arg / 2
                         : (3 * arg + 1);
 
-To enable, add it to appropriate entries in ‘c-offsets-alist’, e.g.:
+To enable, add it to appropriate entries in 'c-offsets-alist', e.g.:
 
     (c-set-offset 'arglist-cont '(c-lineup-ternary-bodies
                                   c-lineup-gcc-asm-reg))
@@ -325,20 +329,21 @@ To enable, add it to appropriate entries in ‘c-offsets-alist’, e.g.:
 
 ** browse-url
 
-*** Added support for custom URL handlers
+*** Added support for custom URL handlers.
 
-There is a new defvar 'browse-url-default-handlers' and a defcustom
-'browse-url-handlers' being alists with (REGEXP-OR-PREDICATE
-. FUNCTION) entries allowing to define different browsing FUNCTIONs
-depending on the URL to be browsed.  The defvar is for default
-handlers provided by Emacs itself or external packages, the defcustom
-is for the user (and allows for overriding the default handlers).
+There is a new variable 'browse-url-default-handlers' and a user
+option 'browse-url-handlers' being alists with '(REGEXP-OR-PREDICATE
+. FUNCTION)' entries allowing to define different browsing FUNCTIONs
+depending on the URL to be browsed.  The variable is for default
+handlers provided by Emacs itself or external packages, the user
+option is for the user (and allows for overriding the default
+handlers).
 
 Formerly, one could do the same by setting
 'browse-url-browser-function' to such an alist.  This usage is still
 supported but deprecated.
 
-*** Categorization of browsing functions in internal vs. external
+*** Categorization of browsing functions in internal vs. external.
 
 All standard browsing functions such as 'browse-url-firefox',
 'browse-url-mail', or 'eww' have been categorized into internal (URL
@@ -351,10 +356,11 @@ either an internal or external browser.
 
 * New Modes and Packages in Emacs 28.1
 
-*** Lisp Data mode
+** Lisp Data mode
+
 The new command 'lisp-data-mode' enables a major mode for buffers
 composed of Lisp symbolic expressions that do not form a computer
-program.  The '.dir-locals.el' file is automatically set to use this
+program.  The ".dir-locals.el" file is automatically set to use this
 mode, as are other data files produced by Emacs.
 
 
@@ -436,23 +442,28 @@ such as "2020-01-15T16:12:21-08:00".
 ** The new function 'dom-remove-attribute' has been added.
 
 ---
-** 'make-network-process', 'make-serial-process' :coding behavior change.
-Previously, passing ":coding nil" to either of these functions would
+** 'make-network-process', 'make-serial-process' ':coding' behavior change.
+Previously, passing ':coding nil' to either of these functions would
 override any non-nil binding for 'coding-system-for-read' and
 'coding-system-for-write'.  For consistency with 'make-process' and
-'make-pipe-process', passing ":coding nil" is now ignored.  No code in
+'make-pipe-process', passing ':coding nil' is now ignored.  No code in
 Emacs depended on the previous behavior; if you really want the
 process' coding-system to be nil, use 'set-process-coding-system'
-after the process has been created, or pass in ":coding '(nil nil)".
+after the process has been created, or pass in ':coding '(nil nil)'.
 
 +++
-** 'open-network-stream' now accepts a :coding argument.
+** 'open-network-stream' now accepts a ':coding' argument.
 This allows specifying the coding systems used by a network process
 for encoding and decoding without having to bind
-coding-system-for-{read,write} or call 'set-process-coding-system'.
+'coding-system-for-{read,write}' or call 'set-process-coding-system'.
+
++++
+** 'open-gnutls-stream' now also accepts a ':coding' argument.
 
 +++
-** 'open-gnutls-stream' now also accepts a :coding argument.
+** New user option 'process-file-return-signal-string'.
+It controls, whether 'process-file' returns a string when a remote
+process is interrupted by a signal.
 
 
 * Changes in Emacs 28.1 on Non-Free Operating Systems
@@ -473,12 +484,12 @@ current IME activation status.
 ** On MS-Windows, Emacs can now use the native image API to display images.
 Emacs can now use the MS-Windows GDI+ library to load and display
 images in JPEG, PNG, GIF and TIFF formats.  This support is enabled
-unless Emacs was configured --without-native-image-api.
+unless Emacs was configured '--without-native-image-api'.
 
 This feature is experimental, and needs to be turned on to be used.
 To turn this on, set the variable 'w32-use-native-image-API' to a
 non-nil value.  Please report any bugs you find while using the native
-image API via "M-x report-emacs-bug".
+image API via 'M-x report-emacs-bug'.
 
 
 ----------------------------------------------------------------------
diff --git a/lisp/net/tramp-adb.el b/lisp/net/tramp-adb.el
index 7ef07afb8ef..b4a080ee0f6 100644
--- a/lisp/net/tramp-adb.el
+++ b/lisp/net/tramp-adb.el
@@ -918,9 +918,11 @@ PRESERVE-UID-GID and PRESERVE-EXTENDED-ATTRIBUTES are completely ignored."
          (kill-buffer (tramp-get-connection-buffer v))
          (setq ret 1)))
 
-      ;; Handle signals.
-      (when (and (natnump ret) (> ret 128))
-        (setq ret (format "Signal %d" (- ret 128))))
+      ;; Handle signals.  `process-file-return-signal-string' exists
+      ;; since Emacs 28.1.
+      (when (and (bound-and-true-p process-file-return-signal-string)
+                 (natnump ret) (> ret 128))
+        (setq ret (nth (- ret 128) (tramp-get-signal-strings))))
 
       ;; Provide error file.
       (when tmpstderr (rename-file tmpstderr (cadr destination) t))
diff --git a/lisp/net/tramp-sh.el b/lisp/net/tramp-sh.el
index c609f58cdd8..523663cafbd 100644
--- a/lisp/net/tramp-sh.el
+++ b/lisp/net/tramp-sh.el
@@ -3159,9 +3159,11 @@ STDERR can also be a file name."
          (kill-buffer (tramp-get-connection-buffer v))
          (setq ret 1)))
 
-      ;; Handle signals.
-      (when (and (natnump ret) (> ret 128))
-        (setq ret (format "Signal %d" (- ret 128))))
+      ;; Handle signals.  `process-file-return-signal-string' exists
+      ;; since Emacs 28.1.
+      (when (and (bound-and-true-p process-file-return-signal-string)
+                 (natnump ret) (>= ret 128))
+        (setq ret (nth (- ret 128) (tramp-get-signal-strings))))
 
       ;; Provide error file.
       (when tmpstderr (rename-file tmpstderr (cadr destination) t))
diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index 70fb46bb4cb..ee263ebe933 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -5047,6 +5047,23 @@ name of a process or buffer, or nil to default to the current buffer."
    (lambda ()
      (remove-hook 'interrupt-process-functions #'tramp-interrupt-process))))
 
+(defun tramp-get-signal-strings ()
+  "Strings to return by `process-file' in case of signals."
+  ;; We use key nil for local connection properties.
+  (with-tramp-connection-property nil "signal-strings"
+    (let (result)
+      (if (and (stringp shell-file-name) (executable-find shell-file-name))
+          (dotimes (i 128)
+            (push
+             (if (= i 19) 1 ;; SIGSTOP
+               (call-process
+                shell-file-name nil nil nil "-c" (format "kill -%d $$" i)))
+             result))
+        (dotimes (i 128)
+          (push (format "Signal %d" i) result)))
+      ;; Due to Bug#41287, we cannot add this to the `dotimes' clause.
+      (reverse result))))
+
 ;; Checklist for `tramp-unload-hook'
 ;; - Unload all `tramp-*' packages
 ;; - Reset `file-name-handler-alist'
diff --git a/lisp/simple.el b/lisp/simple.el
index b5ba05426f5..d151d6c9aeb 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -4141,6 +4141,20 @@ its behavior with respect to remote file attribute caching.
 You should only ever change this variable with a let-binding;
 never with `setq'.")
 
+(defcustom process-file-return-signal-string nil
+  "Whether to return a string describing the signal interrupting a process.
+When a process returns an exit code greater than 128, it is
+interpreted as a signal.  `process-file' requires to return a
+string describing this signal.
+Since there are processes violating this rule, returning exit
+codes greater than 128 which are not bound to a signal,
+`process-file' returns the exit code as natural number also in
+this case.  Setting this user option to non-nil forces
+`process-file' to interpret such exit codes as signals, and to
+return a corresponding string."
+  :version "28.1"
+  :type 'boolean)
+
 (defun start-file-process (name buffer program &rest program-args)
   "Start a program in a subprocess.  Return the process object for it.
 
diff --git a/test/lisp/net/tramp-tests.el b/test/lisp/net/tramp-tests.el
index de85f83982c..1f56baad7ce 100644
--- a/test/lisp/net/tramp-tests.el
+++ b/test/lisp/net/tramp-tests.el
@@ -75,6 +75,7 @@
 ;; Needed for Emacs 26.
 (defvar async-shell-command-width)
 ;; Needed for Emacs 27.
+(defvar process-file-return-signal-string)
 (defvar shell-command-dont-erase-buffer)
 
 ;; Beautify batch mode.
@@ -4208,18 +4209,27 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
             (should (zerop (process-file "true")))
             (should-not (zerop (process-file "false")))
             (should-not (zerop (process-file "binary-does-not-exist")))
-            (should
-             (= 42
+            ;; Return exit code.
+            (should (= 42 (process-file
+                           (if (tramp--test-adb-p) "/system/bin/sh" "/bin/sh")
+                           nil nil nil "-c" "exit 42")))
+            ;; Return exit code in case the process is interrupted,
+            ;; and there's no indication for a signal describing string.
+            (let (process-file-return-signal-string)
+              (should
+               (= (+ 128 2)
+                  (process-file
+                   (if (tramp--test-adb-p) "/system/bin/sh" "/bin/sh")
+                   nil nil nil "-c" "kill -2 $$"))))
+            ;; Return string in case the process is interrupted and
+            ;; there's an indication for a signal describing string.
+            (let ((process-file-return-signal-string t))
+              (should
+               (string-equal
+                "Interrupt"
                 (process-file
                  (if (tramp--test-adb-p) "/system/bin/sh" "/bin/sh")
-                 nil nil nil "-c" "exit 42")))
-            ;; Return string in case the process is interrupted.
-            (should
-             (string-equal
-              "Signal 2"
-              (process-file
-               (if (tramp--test-adb-p) "/system/bin/sh" "/bin/sh")
-               nil nil nil "-c" "kill -2 $$")))
+                 nil nil nil "-c" "kill -2 $$"))))
 
             (with-temp-buffer
               (write-region "foo" nil tmp-name)