; Improve documentation of 'suspend-emacs'

* doc/lispref/os.texi (Suspending Emacs):
* src/keyboard.c (Fsuspend_emacs): Document possible failures
in sending STUFFSTRING to the shell.  (Bug#73100).

(cherry picked from commit 4f044d0d3df019e9a7717b443fe4b4c172854c7c)

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 3ab4b66ba30b48b82af320444d907265201828e3..fe84c2c340351006e3b3af3bcc3061e6ba7f05de 100644 (file)
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -811,9 +811,6 @@ before suspending Emacs, or this function signals an error.
 
 If @var{string} is non-@code{nil}, its characters are sent to Emacs's
 superior shell, to be read as terminal input.
-@c FIXME?  It seems to me that shell does echo STRING.
-The characters in @var{string} are not echoed by the superior shell;
-only the results appear.
 
 Before suspending, @code{suspend-emacs} runs the normal hook
 @code{suspend-hook}.  After the user resumes Emacs,
@@ -859,9 +856,13 @@ Resumed!
 @end group
 @end smallexample
 
-@c FIXME?  AFAICS, it is echoed.
-Note that @samp{pwd} is not echoed after Emacs is suspended.  But it
-is read and executed by the shell.
+Note that on some operating systems, sending @var{string} to the Emacs
+parent shell might require special privileges, in which case it might
+silently fail to send @var{string} to the shell for execution.  On other
+systems this is not supported, and Emacs will signal an error if you
+try.  Also, @var{string} might not be echoed, even if it is executed by
+the shell.  So we don't recommend relying on this feature in portable
+Lisp programs.
 @end deffn
 
 @defvar suspend-hook

diff --git a/src/keyboard.c b/src/keyboard.c
index a6bd113f19eb6d115f5358e5585f13c4020c10aa..64c9fe8b2dc84ac95fdb270dd5b6bde979248213 100644 (file)
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -11917,7 +11917,12 @@ Before suspending, run the normal hook `suspend-hook'.
 After resumption run the normal hook `suspend-resume-hook'.
 
 Some operating systems cannot stop the Emacs process and resume it later.
-On such systems, Emacs starts a subshell instead of suspending.  */)
+On such systems, Emacs starts a subshell instead of suspending.
+
+On some operating systems, stuffing characters into terminal input
+buffer requires special privileges or is not supported at all.
+On such systems, calling this function with non-nil STUFFSTRING might
+either signal an error or silently fail to stuff the characters.  */)
   (Lisp_Object stuffstring)
 {
   specpdl_ref count = SPECPDL_INDEX ();