From 9193db08dea945eb18790f9f9381b9e6317f13fd Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 27 Oct 2018 13:18:33 +0300 Subject: [PATCH] Improve documentation of 'process-connection-type' * doc/lispref/processes.texi (Asynchronous Processes): Clarify better when it is advisable to use pipes for communicating with subprocesses. (Bug#33050) --- doc/lispref/processes.texi | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 34426f339c6..0868912b145 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -590,8 +590,8 @@ communication is only partially asynchronous: Emacs sends data to the process only when certain functions are called, and Emacs accepts data from the process only while waiting for input or for a time delay. -@cindex pty -@cindex pipe +@cindex pty, when to use for subprocess communications +@cindex pipe, when to use for subprocess communications An asynchronous process is controlled either via a @dfn{pty} (pseudo-terminal) or a @dfn{pipe}. The choice of pty or pipe is made when creating the process, by default based on the value of the @@ -601,11 +601,13 @@ Shell mode, because they allow for job control (@kbd{C-c}, @kbd{C-z}, etc.)@: between the process and its children, and because interactive programs treat ptys as terminal devices, whereas pipes don't support these features. However, for subprocesses used by Lisp programs for -internal purposes, it is often better to use a pipe, because pipes are +internal purposes (i.e., with no user interaction), where significant +amounts of data need to be exchanged between the subprocess and the +Lisp program, it is often better to use a pipe, because pipes are more efficient, and because they are immune to stray character injections that ptys introduce for large (around 500 byte) messages. -Also, the total number of ptys is limited on many systems and it is -good not to waste them. +Also, the total number of ptys is limited on many systems, and it is +good not to waste them unnecessarily. @defun make-process &rest args This function is the basic low-level primitive for starting @@ -658,7 +660,9 @@ pipe, or @code{nil} to use the default derived from the value of the @code{process-connection-type} variable. This parameter and the value of @code{process-connection-type} are ignored if a non-@code{nil} value is specified for the @code{:stderr} parameter; in that case, the -type will always be @code{pipe}. +type will always be @code{pipe}. On systems where ptys are not +available (MS-Windows), this parameter is likewise ignored, and pipes +are used unconditionally. @item :noquery @var{query-flag} Initialize the process query flag to @var{query-flag}. @@ -863,7 +867,8 @@ around the call to these functions. Note that the value of this variable is ignored when @code{make-process} is called with a non-@code{nil} value of the @code{:stderr} parameter; in that case, Emacs will communicate with -the process using pipes. +the process using pipes. It is also ignored if ptys are unavailable +(MS-Windows). @smallexample @group -- 2.39.2