From: Philipp Stephani <phst@google.com>
Date: Sun, 17 Jan 2021 10:52:40 +0000 (+0100)
Subject: Add a bit more clarification around standard error processes.
X-Git-Tag: emacs-28.0.90~4244
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=152964362f905ba4f6d60d8c082330b739b8bc8e;p=emacs.git

Add a bit more clarification around standard error processes.

* doc/lispref/processes.texi (Asynchronous Processes): Document
how to obtain the standard error process that Emacs creates.
(Accepting Output): Add an example how to wait for standard error in
case Emacs has created a standard error process.
---

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 535cebed7a8..6dedaa31f2e 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -729,7 +729,9 @@ coding systems (@pxref{Default Coding Systems}).  On the other hand,
 it will use @var{query-flag} as its query-on-exit flag (@pxref{Query
 Before Exit}).  It will be associated with the @var{stderr} buffer
 (@pxref{Process Buffers}) and send its output (which is the standard
-error of the main process) there.
+error of the main process) there.  To get the process object for the
+standard error process, pass the @var{stderr} buffer to
+@code{get-buffer-process}.
 
 If @var{stderr} is a pipe process, Emacs will use it as standard error
 process for the new process.
@@ -1942,6 +1944,29 @@ code:
 (while (accept-process-output stderr-process))
 @end example
 
+If you passed a buffer to the @var{stderr} argument of
+@code{make-process}, you still have to wait for the standard error
+process, like so:
+
+@example
+(let* ((stdout (generate-new-buffer "stdout"))
+       (stderr (generate-new-buffer "stderr"))
+       (process (make-process :name "test"
+                              :command '("my-program")
+                              :buffer stdout
+                              :stderr stderr))
+       (stderr-process (get-buffer-process stderr)))
+  (unless (and process stderr-process)
+    (error "Process unexpectedly nil"))
+  (while (accept-process-output process))
+  (while (accept-process-output stderr-process)))
+@end example
+
+@noindent
+Only when both @code{accept-process-output} forms return @code{nil},
+you can be sure that the process has exited and Emacs has read all its
+output.
+
 Reading pending standard error from a process running on a remote host
 is not possible this way.