[Emacs-diffs] emacs-25 88a5052: Improve and clarify documentation of subprocesses

[Eli Zaretskii]

branch: emacs-25
commit 88a5052579069be93a0af556c9a43a8ed75d3efb
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve and clarify documentation of subprocesses
    
    * doc/lispref/processes.texi (Subprocess Creation, Shell Arguments):
    Mention 'make-process' rather than 'start-process'.  Update wrt
    standard destinations of standard output/error streams and due to
    different formats of arguments accepted by 'make-process'.
    (Processes): Mention process objects that represent connections.
    (Synchronous Processes): Minor clarifications.
    (Asynchronous Processes): Describe 'make-process' and
    'make-pipe-process' before 'start-process'.  Update and expand the
    documentation.
    (Deleting Processes, Process Information, Input to Processes)
    (Signals to Processes, Query Before Exit, Network): Update and
    expand the documentation, especially wrt process objects that
    represent connections.
    (Output from Processes): Mention the possibility of separating
    stderr via 'make-process'.
    (Filter Functions): Mention that stderr by default arrives at the
    filter function together with stdout.  (Bug#24287)
    
    * src/process.c (Fprocess_id, Fprocess_command)
    (Fprocess_contact, Fprocess_type, Fstop_process): Doc fixes for
    process objects that represent connections.
---
 doc/lispref/processes.texi |  649 +++++++++++++++++++++++++-------------------
 src/process.c              |   26 +-
 2 files changed, 389 insertions(+), 286 deletions(-)

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index b4542f6..9c4f8ca 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -27,9 +27,18 @@ with the subprocess or to control it.  For example, you can 
send
 signals, obtain status information, receive output from the process, or
 send input to it.
 
+  In addition to processes that run programs, Lisp programs can open
+connections of several types to devices or processes running on the
+same machine or on other machines.  The supported connection types
+are: TCP and UDP network connections, serial port connections, and
+pipe connections.  Each such connection is also represented by a
+process object.
+
 @defun processp object
 This function returns @code{t} if @var{object} represents an Emacs
-subprocess, @code{nil} otherwise.
+process object, @code{nil} otherwise.  The process object can
+represent a subprocess running a program or a connection of any
+supported type.
 @end defun
 
   In addition to subprocesses of the current Emacs session, you can
@@ -67,7 +76,7 @@ Processes}.
 @cindex process creation
 
   There are three primitives that create a new subprocess in which to run
-a program.  One of them, @code{start-process}, creates an asynchronous
+a program.  One of them, @code{make-process}, creates an asynchronous
 process and returns a process object (@pxref{Asynchronous Processes}).
 The other two, @code{call-process} and @code{call-process-region},
 create a synchronous process and do not return a process object
@@ -82,15 +91,14 @@ fashion, their common arguments are described here.
 @cindex execute program
 @cindex @env{PATH} environment variable
 @cindex @env{HOME} environment variable
-  In all cases, the function's @var{program} argument specifies the
-program to be run.  An error is signaled if the file is not found or
-cannot be executed.  If the file name is relative, the variable
address@hidden contains a list of directories to search.  Emacs
-initializes @code{exec-path} when it starts up, based on the value of
-the environment variable @env{PATH}.  The standard file name
-constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as
-usual in @code{exec-path}, but environment variable substitutions
-(@samp{$HOME}, etc.)@: are not recognized; use
+  In all cases, the functions specify the program to be run.  An error
+is signaled if the file is not found or cannot be executed.  If the
+file name is relative, the variable @code{exec-path} contains a list
+of directories to search.  Emacs initializes @code{exec-path} when it
+starts up, based on the value of the environment variable @env{PATH}.
+The standard file name constructs, @samp{~}, @samp{.}, and @samp{..},
+are interpreted as usual in @code{exec-path}, but environment variable
+substitutions (@samp{$HOME}, etc.)@: are not recognized; use
 @code{substitute-in-file-name} to perform them (@pxref{File Name
 Expansion}).  @code{nil} in this list refers to
 @code{default-directory}.
@@ -106,27 +114,36 @@ system-dependent.
 @end defopt
 
   @strong{Please note:} The argument @var{program} contains only the
-name of the program; it may not contain any command-line arguments.  You
-must use a separate argument, @var{args}, to provide those, as
-described below.
+name of the program file; it may not contain any command-line
+arguments.  You must use a separate argument, @var{args}, to provide
+those, as described below.
 
   Each of the subprocess-creating functions has a @var{buffer-or-name}
-argument that specifies where the standard output from the program will
-go.  It should be a buffer or a buffer name; if it is a buffer name,
-that will create the buffer if it does not already exist.  It can also
-be @code{nil}, which says to discard the output, unless a custom filter 
function
-handles it.  (@xref{Filter Functions}, and @ref{Read and Print}.)
-Normally, you should avoid having multiple processes send output to the
-same buffer because their output would be intermixed randomly.
-For synchronous processes, you can send the output to a file instead
-of a buffer.
+argument that specifies where the output from the program will go.  It
+should be a buffer or a buffer name; if it is a buffer name, that will
+create the buffer if it does not already exist.  It can also be
address@hidden, which says to discard the output, unless a custom filter
+function handles it.  (@xref{Filter Functions}, and @ref{Read and
+Print}.)  Normally, you should avoid having multiple processes send
+output to the same buffer because their output would be intermixed
+randomly.  For synchronous processes, you can send the output to a
+file instead of a buffer (and the corresponding argument is therefore
+more appropriately called @var{destination}).  By default, both
+standard output and standard error streams go to the same destination,
+but all the 3 primitives allow optionally to direct the standard error
+stream to a different destination.
 
 @cindex program arguments
-  All three of the subprocess-creating functions have a @code{&rest}
-argument, @var{args}.  The @var{args} must all be strings, and they are
-supplied to @var{program} as separate command line arguments.  Wildcard
-characters and other shell constructs have no special meanings in these
-strings, since the strings are passed directly to the specified program.
+  All three of the subprocess-creating functions allow to specify
+command-line arguments for the process to run. For @code{call-process}
+and @code{call-process-region}, these come in the form of a
address@hidden&rest} argument, @var{args}.  For @code{make-process}, both the
+program to run and its command-line arguments are specified as a list
+of strings.  The command-line arguments must all be strings, and they
+are supplied to the program as separate argument strings.  Wildcard
+characters and other shell constructs have no special meanings in
+these strings, since the strings are passed directly to the specified
+program.
 
 @cindex environment variables, subprocesses
   The subprocess inherits its environment from Emacs, but you can
@@ -147,6 +164,7 @@ The value of this variable is a list of directories to 
search for
 programs to run in subprocesses.  Each element is either the name of a
 directory (i.e., a string), or @code{nil}, which stands for the default
 directory (which is the value of @code{default-directory}).
address@hidden Files, executable-find}, for the details of this search.
 @cindex program directories
 
 The value of @code{exec-path} is used by @code{call-process} and
@@ -210,11 +228,11 @@ a shell command:
   The following two functions are useful for combining a list of
 individual command-line argument strings into a single string, and
 taking a string apart into a list of individual command-line
-arguments.  These functions are mainly intended for
-converting user input in the minibuffer, a Lisp string, into a list of
-string arguments to be passed to @code{call-process} or
address@hidden, or for converting such lists of arguments into
-a single Lisp string to be presented in the minibuffer or echo area.
+arguments.  These functions are mainly intended for converting user
+input in the minibuffer, a Lisp string, into a list of string
+arguments to be passed to @code{make-process}, @code{call-process} or
address@hidden, or for converting such lists of arguments into a
+single Lisp string to be presented in the minibuffer or echo area.
 Note that if a shell is involved (e.g., if using
 @code{call-process-shell-command}), arguments should still be
 protected by @code{shell-quote-argument};
@@ -331,7 +349,7 @@ string specifies a file name to redirect error output into.
 You can't directly specify a buffer to put the error output in; that is
 too difficult to implement.  But you can achieve this result by sending
 the error output to a temporary file and then inserting the file into a
-buffer.
+buffer when the subprocess finishes.
 @end table
 
 If @var{display} is address@hidden, then @code{call-process} redisplays
@@ -346,13 +364,15 @@ results become visible on the screen only when Emacs 
redisplays that
 buffer in the normal course of events.
 
 The remaining arguments, @var{args}, are strings that specify command
-line arguments for the program.
+line arguments for the program.  Each string is passed to
address@hidden as a separate argument.
 
 The value returned by @code{call-process} (unless you told it not to
 wait) indicates the reason for process termination.  A number gives the
 exit status of the subprocess; 0 means success, and any other value
 means failure.  If the process terminated with a signal,
address@hidden returns a string describing the signal.
address@hidden returns a string describing the signal.  If you
+told @code{call-process} not to wait, it returns @code{nil}.
 
 In the examples below, the buffer @samp{foo} is current.
 
@@ -510,10 +530,10 @@ address@hidden
 
 @defun call-process-shell-command command &optional infile destination display
 This function executes the shell command @var{command} synchronously.
-The arguments are handled as in @code{call-process}.  An old calling
-convention allowed passing any number of additional arguments after
address@hidden, which were concatenated to @var{command}; this is still
-supported, but strongly discouraged.
+The other arguments are handled as in @code{call-process}.  An old
+calling convention allowed passing any number of additional arguments
+after @var{display}, which were concatenated to @var{command}; this is
+still supported, but strongly discouraged.
 @end defun
 
 @defun process-file-shell-command command &optional infile destination display
@@ -565,33 +585,169 @@ from the process only while waiting for input or for a 
time delay.
 @cindex pipe
   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, based on the value of the variable
address@hidden (see below).  Ptys are usually
-preferable for processes visible to the user, as in Shell mode,
-because they allow for job control (@kbd{C-c}, @kbd{C-z}, etc.)@:
-between the process and its children, whereas pipes do not.  For
-subprocesses used for internal purposes by programs, it is often
-better to use a pipe, because they 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.
+when creating the process, by default based on the value of the
+variable @code{process-connection-type} (see below).  If available,
+ptys are usually preferable for processes visible to the user, as in
+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
+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.
+
address@hidden make-process &rest args
+This function is the basic low-level primitive for starting
+asynchronous subprocesses.  It returns a process object representing
+the subprocess.  Compared to the more high-level @code{start-process},
+described below, it takes keyword arguments, is more flexible, and
+allows to specify process filters and sentinels in a single call.
+
+The arguments @var{args} are a list of keyword/argument pairs.
+Omitting a keyword is always equivalent to specifying it with value
address@hidden  Here are the meaningful keywords:
+
address@hidden @asis
address@hidden :name @var{name}
+Use the string @var{name} as the process name; if a process with this
+name already exists, then @var{name} is modified (by appending
address@hidden<1>}, etc.)@: to be unique.
+
address@hidden :buffer @var{buffer}
+Use @var{buffer} as the process buffer.  If the value is @code{nil},
+the subprocess is not associated with any buffer.
+
address@hidden :command @var{command}
+Use @var{command} as the command line of the process.  The value
+should be a list starting with the program's executable file name,
+followed by strings to give to the program as its arguments.  If
+the first element of the list is @code{nil}, Emacs opens a new
+pseudoterminal (pty) and associates its input and output with
address@hidden, without actually running any program; the rest of the
+list elements are ignored in that case.
+
address@hidden :coding @var{coding}
+If @var{coding} is a symbol, it specifies the coding system to be
+used for both reading and writing of data from and to the
+connection.  If @var{coding} is a cons cell
address@hidden@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
+will be used for reading and @var{encoding} for writing.  The coding
+system used for encoding the data written to the program is also used
+for encoding the command-line arguments (but not the program itself,
+whose file name is encoded as any other file name; @pxref{Encoding and
+I/O, file-name-coding-system}).
+
+If @var{coding} is @code{nil}, the default rules for finding the
+coding system will apply.  @xref{Default Coding Systems}.
+
address@hidden :connection-type @var{TYPE}
+Initialize the type of device used to communicate with the subprocess.
+Possible values are @code{pty} to use a pty, @code{pipe} to use a
+pipe, or @code{nil} to use the default derived from the value of the
address@hidden variable.  This parameter and the value
+of @code{process-connection-type} are ignored if a address@hidden
+value is specified for the @code{:stderr} parameter; in that case, the
+type will always be @code{pipe}.
+
address@hidden :noquery @var{query-flag}
+Initialize the process query flag to @var{query-flag}.
address@hidden Before Exit}.
+
address@hidden :stop @var{stopped}
+If @var{stopped} is address@hidden, start the process in the
+stopped state.
+
address@hidden :filter @var{filter}
+Initialize the process filter to @var{filter}.  If not specified, a
+default filter will be provided, which can be overridden later.
address@hidden Functions}.
+
address@hidden :sentinel @var{sentinel}
+Initialize the process sentinel to @var{sentinel}.  If not specified,
+a default sentinel will be used, which can be overridden later.
address@hidden
+
address@hidden :stderr @var{stderr}
+Associate @var{stderr} with the standard error of the process.  A
address@hidden value should be either a buffer or a pipe process
+created with @code{make-pipe-process}, described below.
address@hidden table
+
+The original argument list, modified with the actual connection
+information, is available via the @code{process-contact} function.
address@hidden defun
+
address@hidden make-pipe-process &rest args
+This function creates a bidirectional pipe which can be attached to a
+child process.  This is useful with the @code{:stderr} keyword of
address@hidden  The function returns a process object.
+
+The arguments @var{args} are a list of keyword/argument pairs.
+Omitting a keyword is always equivalent to specifying it with value
address@hidden
+
+Here are the meaningful keywords:
+
address@hidden @asis
address@hidden :name @var{name}
+Use the string @var{name} as the process name.  As with
address@hidden, it is modified if necessary to make it unique.
+
address@hidden :buffer @var{buffer}
+Use @var{buffer} as the process buffer.
+
address@hidden :coding @var{coding}
+If @var{coding} is a symbol, it specifies the coding system to be
+used for both reading and writing of data from and to the
+connection.  If @var{coding} is a cons cell
address@hidden@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
+will be used for reading and @var{encoding} for writing.
+
+If @var{coding} is @code{nil}, the default rules for finding the
+coding system will apply.  @xref{Default Coding Systems}.
+
address@hidden :noquery @var{query-flag}
+Initialize the process query flag to @var{query-flag}.
address@hidden Before Exit}.
+
address@hidden :stop @var{stopped}
+If @var{stopped} is address@hidden, start the process in the
+stopped state.
+
address@hidden :filter @var{filter}
+Initialize the process filter to @var{filter}.  If not specified, a
+default filter will be provided, which can be changed later.
address@hidden Functions}.
+
address@hidden :sentinel @var{sentinel}
+Initialize the process sentinel to @var{sentinel}.  If not specified,
+a default sentinel will be used, which can be changed later.
address@hidden
address@hidden table
+
+The original argument list, modified with the actual connection
+information, is available via the @code{process-contact} function.
address@hidden defun
 
 @defun start-process name buffer-or-name program &rest args
-This function creates a new asynchronous subprocess and starts the
-program @var{program} running in it.  It returns a process object that
-stands for the new subprocess in Lisp.  The argument @var{name}
-specifies the name for the process object; if a process with this name
-already exists, then @var{name} is modified (by appending @samp{<1>},
-etc.)@: to be unique.  The buffer @var{buffer-or-name} is the buffer to
-associate with the process.
+This function is a higher-level wrapper around @code{make-process},
+exposing an interface that is similar to @code{call-process}.  It
+creates a new asynchronous subprocess and starts the specified
address@hidden running in it.  It returns a process object that stands
+for the new subprocess in Lisp.  The argument @var{name} specifies the
+name for the process object; as with @code{make-process}, it is
+modified if necessary to make it unique.  The buffer
address@hidden is the buffer to associate with the process.
 
 If @var{program} is @code{nil}, Emacs opens a new pseudoterminal (pty)
 and associates its input and output with @var{buffer-or-name}, without
 creating a subprocess.  In that case, the remaining arguments
 @var{args} are ignored.
 
-The remaining arguments, @var{args}, are strings that specify command
-line arguments for the subprocess.
+The rest of @var{args} are strings that specify command line arguments
+for the subprocess.
 
 In the example below, the first process is started and runs (rather,
 sleeps) for 100 seconds (the output buffer @samp{foo} is created
@@ -633,14 +789,14 @@ subprocess running @var{program} in it, and returns its 
process
 object.
 
 The difference from @code{start-process} is that this function may
-invoked a file handler based on the value of @code{default-directory}.
+invoke a file handler based on the value of @code{default-directory}.
 This handler ought to run @var{program}, perhaps on the local host,
 perhaps on a remote host that corresponds to @code{default-directory}.
 In the latter case, the local part of @code{default-directory} becomes
 the working directory of the process.
 
 This function does not try to invoke file name handlers for
address@hidden or for the @var{program-args}.
address@hidden or for the rest of @var{args}.
 
 Depending on the implementation of the file handler, it might not be
 possible to apply @code{process-filter} or @code{process-sentinel} to
@@ -654,19 +810,20 @@ this function does nothing and returns @code{nil}.
 @end defun
 
 @defun start-process-shell-command name buffer-or-name command
-This function is like @code{start-process}, except that it uses a shell
-to execute the specified command.  The argument @var{command} is a shell
-command name.  The variable @code{shell-file-name} specifies which shell to
-use.
+This function is like @code{start-process}, except that it uses a
+shell to execute the specified @var{command}.  The argument
address@hidden is a shell command string.  The variable
address@hidden specifies which shell to use.
 
 The point of running a program through the shell, rather than directly
-with @code{start-process}, is so that you can employ shell features such
-as wildcards in the arguments.  It follows that if you include any
-arbitrary user-specified arguments in the command, you should quote them
-with @code{shell-quote-argument} first, so that any special shell
-characters do @emph{not} have their special shell meanings.  @xref{Shell
-Arguments}.  Of course, when executing commands based on user input
-you should also consider the security implications.
+with @code{make-process} or @code{start-process}, is so that you can
+employ shell features such as wildcards in the arguments.  It follows
+that if you include any arbitrary user-specified arguments in the
+command, you should quote them with @code{shell-quote-argument} first,
+so that any special shell characters do @emph{not} have their special
+shell meanings.  @xref{Shell Arguments}.  Of course, when executing
+commands based on user input you should also consider the security
+implications.
 @end defun
 
 @defun start-file-process-shell-command name buffer-or-name command
@@ -681,9 +838,14 @@ asynchronous subprocesses.  If it is address@hidden, then 
ptys are
 used, when available.  Otherwise, pipes are used.
 
 The value of @code{process-connection-type} takes effect when
address@hidden is called.  So you can specify how to communicate
-with one subprocess by binding the variable around the call to
address@hidden
address@hidden or @code{start-process} is called.  So you can
+specify how to communicate with one subprocess by binding the variable
+around the call to these functions.
+
+Note that the value of this variable is ignored when
address@hidden is called with a address@hidden value of the
address@hidden:stderr} parameter; in that case, Emacs will communicate with
+the process using pipes.
 
 @smallexample
 @group
@@ -697,117 +859,6 @@ use the function @code{process-tty-name} (@pxref{Process
 Information}).
 @end defvar
 
address@hidden make-process &rest args
-This function is like @code{start-process}, but takes keyword arguments.
-
-The arguments @var{args} are a list of keyword/argument pairs.
-Omitting a keyword is always equivalent to specifying it with value
address@hidden  Here are the meaningful keywords:
-
address@hidden @asis
address@hidden :name @var{name}
-Use the string @var{name} as the process name.  It is modified if
-necessary to make it unique.
-
address@hidden :buffer @var{buffer}
-Use @var{buffer} as the process buffer.
-
address@hidden :command @var{command}
-Use @var{command} as the command line of the process.  @var{command}
-is a list starting with the program's executable file name, followed
-by strings to give to program as arguments.
-
address@hidden :coding @var{coding}
-If @var{coding} is a symbol, it specifies the coding system to be
-used for both reading and writing of data from and to the
-connection.  If @var{coding} is a cons cell
address@hidden@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
-will be used for reading and @var{encoding} for writing.
-
-If @var{coding} is @code{nil}, the default rules for finding the
-coding system will apply.  @xref{Default Coding Systems}.
-
address@hidden :connection-type @var{TYPE}
-Initialize the type of device used to communicate with the subprocess.
-Possible values are @code{pty} to use a pty, @code{pipe} to use a
-pipe, or @code{nil} to use the default derived from the value of
-the @code{process-connection-type} variable.
-
address@hidden :noquery @var{query-flag}
-Initialize the process query flag to @var{query-flag}.
address@hidden Before Exit}.
-
address@hidden :stop @var{stopped}
-If @var{stopped} is address@hidden, start the process in the
-stopped state.
-
address@hidden :filter @var{filter}
-Initialize the process filter to @var{filter}.  If not specified, a
-default filter will be provided.  @xref{Filter Functions}.
-
address@hidden :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.  If not specified,
-a default sentinel will be used.  @xref{Sentinels}.
-
address@hidden :stderr @var{stderr}
-Associate @var{stderr} with the standard error of the process.
address@hidden is either a buffer or a pipe process created with
address@hidden
address@hidden table
-
-The original argument list, modified with the actual connection
-information, is available via the @code{process-contact} function.
address@hidden defun
-
address@hidden make-pipe-process &rest args
-This function creates a bidirectional pipe which can be attached to a
-child process (currently only useful with the @code{:stderr} keyword
-of @code{make-process}).
-
-The arguments @var{args} are a list of keyword/argument pairs.
-Omitting a keyword is always equivalent to specifying it with value
address@hidden, except for @code{:coding}.
-Here are the meaningful keywords:
-
address@hidden @asis
address@hidden :name @var{name}
-Use the string @var{name} as the process name.  It is modified if
-necessary to make it unique.
-
address@hidden :buffer @var{buffer}
-Use @var{buffer} as the process buffer.
-
address@hidden :coding @var{coding}
-If @var{coding} is a symbol, it specifies the coding system to be
-used for both reading and writing of data from and to the
-connection.  If @var{coding} is a cons cell
address@hidden@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
-will be used for reading and @var{encoding} for writing.
-
-If @var{coding} is @code{nil}, the default rules for finding the
-coding system will apply.  @xref{Default Coding Systems}.
-
address@hidden :noquery @var{query-flag}
-Initialize the process query flag to @var{query-flag}.
address@hidden Before Exit}.
-
address@hidden :stop @var{stopped}
-If @var{stopped} is address@hidden, start the process in the
-stopped state.
-
address@hidden :filter @var{filter}
-Initialize the process filter to @var{filter}.  If not specified, a
-default filter will be provided.  @xref{Filter Functions}.
-
address@hidden :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.  If not specified,
-a default sentinel will be used.  @xref{Sentinels}.
address@hidden table
-
-The original argument list, modified with the actual connection
-information, is available via the @code{process-contact} function.
address@hidden defun
-
 @node Deleting Processes
 @section Deleting Processes
 @cindex deleting processes
@@ -837,14 +888,19 @@ they exit.
 
 @defun delete-process process
 This function deletes a process, killing it with a @code{SIGKILL}
-signal.  The argument may be a process, the name of a process, a
-buffer, or the name of a buffer.  (A buffer or buffer-name stands for
-the process that @code{get-buffer-process} returns.)  Calling
address@hidden on a running process terminates it, updates the
-process status, and runs the sentinel immediately.  If the
-process has already terminated, calling @code{delete-process} has no
-effect on its status, or on the running of its sentinel (which will
-happen sooner or later).
+signal if the process was running a program.  The argument may be a
+process, the name of a process, a buffer, or the name of a buffer.  (A
+buffer or buffer-name stands for the process that
address@hidden returns.)  Calling @code{delete-process} on
+a running process terminates it, updates the process status, and runs
+the sentinel immediately.  If the process has already terminated,
+calling @code{delete-process} has no effect on its status, or on the
+running of its sentinel (which will happen sooner or later).
+
+If the process object represents a network, serial, or pipe
+connection, its status changes to @code{closed}; otherwise, it changes
+to @code{signal}, unless the process already exited.  @xref{Process
+Information, process-status}.
 
 @smallexample
 @group
@@ -886,7 +942,8 @@ This function returns a list of all processes that have not 
been deleted.
 
 @defun get-process name
 This function returns the process named @var{name} (a string), or
address@hidden if there is none.
address@hidden if there is none.  The argument @var{name} can also be a
+process object, in which case it is returned.
 
 @smallexample
 @group
@@ -900,7 +957,9 @@ This function returns the process named @var{name} (a 
string), or
 This function returns the command that was executed to start
 @var{process}.  This is a list of strings, the first string being the
 program executed and the rest of the strings being the arguments that
-were given to the program.
+were given to the program.  For a network, serial, or pipe connection,
+this is either @code{nil}, which means the process is running or
address@hidden (process is stopped).
 
 @smallexample
 @group
@@ -911,18 +970,19 @@ were given to the program.
 @end defun
 
 @defun process-contact process &optional key
-
-This function returns information about how a network or serial
-process was set up.  When @var{key} is @code{nil}, it returns
address@hidden(@var{hostname} @var{service})} for a network process, and
address@hidden(@var{port} @var{speed})} for a serial process.
-For an ordinary child process, this function always returns @code{t}.
+This function returns information about how a network, a serial, or a
+pipe connection was set up.  When @var{key} is @code{nil}, it returns
address@hidden(@var{hostname} @var{service})} for a network connection,
address@hidden(@var{port} @var{speed})} for a serial connection, and @code{t}
+for a pipe connection.  For an ordinary child process, this function
+always returns @code{t} when called with a @code{nil} @var{key}.
 
 If @var{key} is @code{t}, the value is the complete status information
-for the connection, server, or serial port; that is, the list of
-keywords and values specified in @code{make-network-process} or
address@hidden, except that some of the values represent
-the current status instead of what you specified.
+for the connection, server, serial port, or pipe; that is, the list of
+keywords and values specified in @code{make-network-process},
address@hidden, or @code{make-pipe-process}, except that
+some of the values represent the current status instead of what you
+specified.
 
 For a network process, the values include (see
 @code{make-network-process} for a complete list):
@@ -947,8 +1007,9 @@ this value is the actual port number.
 @code{:local} and @code{:remote} are included even if they were not
 specified explicitly in @code{make-network-process}.
 
-For a serial process, see @code{make-serial-process} and
address@hidden for a list of keys.
+For a serial connection, see @code{make-serial-process} and
address@hidden for the list of keys.  For a pipe
+connection, see @code{make-pipe-process} for the list of keys.
 
 If @var{key} is a keyword, the function returns the value corresponding
 to that keyword.
@@ -956,10 +1017,12 @@ to that keyword.
 
 @defun process-id process
 This function returns the @acronym{PID} of @var{process}.  This is an
-integer that distinguishes the process @var{process} from all other
-processes running on the same computer at the current time.  The
address@hidden of a process is chosen by the operating system kernel when the
-process is started and remains constant as long as the process exists.
+integral number that distinguishes the process @var{process} from all
+other processes running on the same computer at the current time.  The
address@hidden of a process is chosen by the operating system kernel
+when the process is started and remains constant as long as the
+process exists.  For network, serial, and pipe connections, this
+function returns @code{nil}.
 @end defun
 
 @defun process-name process
@@ -983,11 +1046,11 @@ for a process that has exited.
 @item signal
 for a process that has received a fatal signal.
 @item open
-for a network connection that is open.
+for a network, serial, or pipe connection that is open.
 @item closed
-for a network connection that is closed.  Once a connection
-is closed, you cannot reopen it, though you might be able to open
-a new connection to the same place.
+for a network, serial, or pipe connection that is closed.  Once a
+connection is closed, you cannot reopen it, though you might be able
+to open a new connection to the same place.
 @item connect
 for a non-blocking connection that is waiting to complete.
 @item failed
@@ -1005,9 +1068,11 @@ if @var{process-name} is not the name of an existing 
process.
 @end group
 @end smallexample
 
-For a network connection, @code{process-status} returns one of the symbols
address@hidden or @code{closed}.  The latter means that the other side
-closed the connection, or Emacs did @code{delete-process}.
+For a network, serial, or pipe connection, @code{process-status}
+returns one of the symbols @code{open}, @code{stop}, or @code{closed}.
+The latter means that the other side closed the connection, or Emacs
+did @code{delete-process}.  The value @code{stop} means that
address@hidden was called on the connection.
 @end defun
 
 @defun process-live-p process
@@ -1018,24 +1083,29 @@ process is considered alive if its status is 
@code{run}, @code{open},
 
 @defun process-type process
 This function returns the symbol @code{network} for a network
-connection or server, @code{serial} for a serial port connection, or
address@hidden for a real subprocess.
+connection or server, @code{serial} for a serial port connection,
address@hidden for a pipe connection, or @code{real} for a subprocess
+created for running a program.
 @end defun
 
 @defun process-exit-status process
 This function returns the exit status of @var{process} or the signal
 number that killed it.  (Use the result of @code{process-status} to
 determine which of those it is.)  If @var{process} has not yet
-terminated, the value is 0.
+terminated, the value is 0.  For network, serial, and pipe connections
+that are already closed, the value is either 0 or 256, depending on
+whether the connection was closed normally or abnormally.
 @end defun
 
 @defun process-tty-name process
 This function returns the terminal name that @var{process} is using for
 its communication with Emacs---or @code{nil} if it is using pipes
-instead of a terminal (see @code{process-connection-type} in
+instead of a pty (see @code{process-connection-type} in
 @ref{Asynchronous Processes}).  If @var{process} represents a program
 running on a remote host, the terminal name used by that program on
-the remote host is provided as process property @code{remote-tty}.
+the remote host is provided as process property @code{remote-tty}.  If
address@hidden represents a network, serial, or pipe connection, the
+value is @code{nil}.
 @end defun
 
 @defun process-coding-system process
@@ -1079,8 +1149,10 @@ This function sets the process plist of @var{process} to 
@var{plist}.
 
   Asynchronous subprocesses receive input when it is sent to them by
 Emacs, which is done with the functions in this section.  You must
-specify the process to send input to, and the input data to send.  The
-data appears on the standard input of the subprocess.
+specify the process to send input to, and the input data to send.  If
+the subprocess runs a program, the data appears on the standard input
+of that program; for connections, the data is sent to the connected
+device or program.
 
 @c FIXME which?
   Some operating systems have limited space for buffered input in a
@@ -1143,12 +1215,14 @@ The function returns @var{process}.
 @end defun
 
 @defun process-running-child-p &optional process
-This function will tell you whether a @var{process} has given control
-of its terminal to its own child process.  If this is true, the
-function returns the numeric ID of the foreground process group of
address@hidden; it returns @code{nil} if Emacs can be certain that this
-is not so.  The value is @code{t} if Emacs cannot tell whether this is
-true.
+This function will tell you whether a @var{process}, which must not be
+a connection but a real subprocess, has given control of its terminal
+to a child process of its own.  If this is true, the function returns
+the numeric ID of the foreground process group of @var{process}; it
+returns @code{nil} if Emacs can be certain that this is not so.  The
+value is @code{t} if Emacs cannot tell whether this is true.  This
+function signals an error if @var{process} is a network, serial, or
+pipe connection, or is the subprocess is not active.
 @end defun
 
 @node Signals to Processes
@@ -1181,17 +1255,22 @@ user ``hung up the phone'', i.e., disconnected.)
   The argument @var{process} must be either a process, a process
 name, a buffer, a buffer name, or @code{nil}.  A buffer or buffer name
 stands for a process through @code{get-buffer-process}.  @code{nil}
-stands for the process associated with the current buffer.  An error
-is signaled if @var{process} does not identify a process.
+stands for the process associated with the current buffer.  Except
+with @code{stop-process} and @code{continue-process}, an error is
+signaled if @var{process} does not identify an active process, or if
+it represents a network, serial, or pipe connection.
 
   The argument @var{current-group} is a flag that makes a difference
 when you are running a job-control shell as an Emacs subprocess.  If it
 is address@hidden, then the signal is sent to the current process-group
 of the terminal that Emacs uses to communicate with the subprocess.  If
 the process is a job-control shell, this means the shell's current
-subjob.  If it is @code{nil}, the signal is sent to the process group of
-the immediate subprocess of Emacs.  If the subprocess is a job-control
-shell, this is the shell itself.
+subjob.  If @var{current-group} is @code{nil}, the signal is
+sent to the process group of the immediate subprocess of Emacs.  If
+the subprocess is a job-control shell, this is the shell itself.  If
address@hidden is @code{lambda}, the signal is sent to the
+process-group that owns the terminal, but only if it is not the shell
+itself.
 
   The flag @var{current-group} has no effect when a pipe is used to
 communicate with the subprocess, because the operating system does not
@@ -1222,21 +1301,29 @@ Emacs.
 @end defun
 
 @defun stop-process &optional process current-group
-This function stops the process @var{process} by sending the
-signal @code{SIGTSTP}.  Use @code{continue-process} to resume its
+This function stops the specified @var{process}.  If it is a real
+subprocess running a program, it sends the signal @code{SIGTSTP} to
+that subprocess.  If @var{process} represents a network, serial, or
+pipe connection, this function inhibits handling of the incoming data
+from the connection; for a network server, this means not accepting
+new connections.  Use @code{continue-process} to resume normal
 execution.
 
 Outside of Emacs, on systems with job control, the stop character
-(usually @kbd{C-z}) normally sends this signal.  When
address@hidden is address@hidden, you can think of this function as
-typing @kbd{C-z} on the terminal Emacs uses to communicate with the
-subprocess.
+(usually @kbd{C-z}) normally sends the @code{SIGTSTP} signal to a
+subprocess.  When @var{current-group} is address@hidden, you can think
+of this function as typing @kbd{C-z} on the terminal Emacs uses to
+communicate with the subprocess.
 @end defun
 
 @defun continue-process &optional process current-group
-This function resumes execution of the process @var{process} by sending
-it the signal @code{SIGCONT}.  This presumes that @var{process} was
-stopped previously.
+This function resumes execution of the process @var{process}.  If it
+is a real subprocess running a program, it sends the signal
address@hidden to that subprocess; this presumes that @var{process}
+was stopped previously.  If @var{process} represents a network,
+serial, or pipe connection, this function resumes handling of the
+incoming data from the connection.  For serial connections, data that
+arrived during the time the process was stopped might be lost.
 @end defun
 
 @deffn Command signal-process process signal
@@ -1254,12 +1341,28 @@ children of Emacs.  @xref{System Processes}.
 @cindex process output
 @cindex output from processes
 
-  The output that a subprocess writes to its standard output stream
-is passed to a function called the @dfn{filter function}.  The default
-filter function simply inserts the output into a buffer, which is
-called the associated buffer of the process (@pxref{Process
-Buffers}).  If the process has no buffer then the default filter
-discards the output.
+  The output that an asynchronous subprocess writes to its standard
+output stream is passed to a function called the @dfn{filter
+function}.  The default filter function simply inserts the output into
+a buffer, which is called the associated buffer of the process
+(@pxref{Process Buffers}).  If the process has no buffer then the
+default filter discards the output.
+
+  If the subprocess writes to its standard error stream, by default
+the error output is also passed to the process filter function.  If
+Emacs uses a pseudo-TTY (pty) for communication with the subprocess,
+then it is impossible to separate the standard output and standard
+error streams of the subprocess, because a pseudo-TTY has only one
+output channel.  In that case, if you want to keep the output to those
+streams separate, you should redirect one of them to a file---for
+example, by using an appropriate shell command via
address@hidden or a similar function.
+
+  Alternatively, you could use the @code{:stderr} parameter with a
address@hidden value in a call to @code{make-process}
+(@pxref{Asynchronous Processes, make-process}) to make the destination
+of the error output separate from the standard output; in that case,
+Emacs will use pipes for communicating with the subprocess.
 
   When a subprocess terminates, Emacs reads any pending output,
 then stops reading output from that subprocess.  Therefore, if the
@@ -1286,13 +1389,6 @@ from such processes, thus allowing them to produce more 
output before
 Emacs tries to read it.
 @end defvar
 
-  It is impossible to separate the standard output and standard error
-streams of the subprocess, because Emacs normally spawns the subprocess
-inside a pseudo-TTY, and a pseudo-TTY has only one output channel.  If
-you want to keep the output to those streams separate, you should
-redirect one of them to a file---for example, by using an appropriate
-shell command.
-
 @menu
 * Process Buffers::         By default, output is put in a buffer.
 * Filter Functions::        Filter functions accept output from the process.
@@ -1327,7 +1423,7 @@ Before Exit}).  This confirmation is done by the function
 @code{kill-buffer-query-functions} (@pxref{Killing Buffers}).
 
 @defun process-buffer process
-This function returns the associated buffer of the process
+This function returns the associated buffer of the specified
 @var{process}.
 
 @smallexample
@@ -1449,6 +1545,11 @@ standard output from the associated process.  @emph{All} 
output from
 that process is passed to the filter.  The default filter simply
 outputs directly to the process buffer.
 
+  By default, the error output from the process, if any, is also
+passed to the filter function, unless the destination for the standard
+error stream of the process was separated from the standard output
+when the process was created (@pxref{Output from Processes}).
+
   The filter function can only be called when Emacs is waiting for
 something, because process output arrives only at such times.  Emacs
 waits when reading terminal input (see the function
@@ -1472,8 +1573,8 @@ cases, the right way to do this is with the macro
 caught automatically, so that it doesn't stop the execution of whatever
 program was running when the filter function was started.  However, if
 @code{debug-on-error} is address@hidden, errors are not caught.
-This makes it possible to use the Lisp debugger to debug the
-filter function.  @xref{Debugger}.
+This makes it possible to use the Lisp debugger to debug filter
+functions.  @xref{Debugger}.
 
   Many filter functions sometimes (or always) insert the output in the
 process's buffer, mimicking the actions of the default filter.
@@ -1511,8 +1612,8 @@ text arrives, you could insert a line like the following 
just before the
 @end smallexample
 
   To force point to the end of the new output, no matter where it was
-previously, eliminate the variable @code{moving} and call
address@hidden unconditionally.
+previously, eliminate the variable @code{moving} from the example and
+call @code{goto-char} unconditionally.
 
 @ignore
   In earlier Emacs versions, every filter function that did regular
@@ -1835,10 +1936,11 @@ was not.
 @node Query Before Exit
 @section Querying Before Exit
 
-  When Emacs exits, it terminates all its subprocesses by sending them
-the @code{SIGHUP} signal.  Because subprocesses may be doing
-valuable work, Emacs normally asks the user to confirm that it is ok
-to terminate them.  Each process has a query flag, which, if
+  When Emacs exits, it terminates all its subprocesses.  For
+subprocesses that run a program, it sends them the @code{SIGHUP}
+signal; connections are simply closed.  Because subprocesses may be
+doing valuable work, Emacs normally asks the user to confirm that it
+is ok to terminate them.  Each process has a query flag, which, if
 address@hidden, says that Emacs should ask for confirmation before
 exiting and thus killing that process.  The default for the query flag
 is @code{t}, meaning @emph{do} query.
@@ -2132,13 +2234,14 @@ the @code{open-network-stream} function described below.
   To distinguish the different types of processes, the
 @code{process-type} function returns the symbol @code{network} for a
 network connection or server, @code{serial} for a serial port
-connection, or @code{real} for a real subprocess.
+connection, @code{pipe} for a pipe connection, or @code{real} for a
+real subprocess.
 
   The @code{process-status} function returns @code{open},
address@hidden, @code{connect}, or @code{failed} for network
-connections.  For a network server, the status is always
address@hidden  None of those values is possible for a real
-subprocess.  @xref{Process Information}.
address@hidden, @code{connect}, @code{stop}, or @code{failed} for
+network connections.  For a network server, the status is always
address@hidden  Except for @code{stop}, none of those values is
+possible for a real subprocess.  @xref{Process Information}.
 
   You can stop and resume operation of a network process by calling
 @code{stop-process} and @code{continue-process}.  For a server
diff --git a/src/process.c b/src/process.c
index 0593429..7ab92b0 100644
--- a/src/process.c
+++ b/src/process.c
@@ -928,7 +928,7 @@ If PROCESS has not yet exited or died, return 0.  */)
 DEFUN ("process-id", Fprocess_id, Sprocess_id, 1, 1, 0,
        doc: /* Return the process id of PROCESS.
 This is the pid of the external process which PROCESS uses or talks to.
-For a network connection, this value is nil.  */)
+For a network, serial, and pipe connections, this value is nil.  */)
   (register Lisp_Object process)
 {
   pid_t pid;
@@ -952,8 +952,8 @@ DEFUN ("process-command", Fprocess_command, 
Sprocess_command, 1, 1, 0,
        doc: /* Return the command that was executed to start PROCESS.
 This is a list of strings, the first string being the program executed
 and the rest of the strings being the arguments given to it.
-For a network or serial process, this is nil (process is running) or t
-\(process is stopped).  */)
+For a network or serial or pipe connection, this is nil (process is running)
+or t (process is stopped).  */)
   (register Lisp_Object process)
 {
   CHECK_PROCESS (process);
@@ -1181,13 +1181,13 @@ DEFUN ("process-query-on-exit-flag",
 DEFUN ("process-contact", Fprocess_contact, Sprocess_contact,
        1, 2, 0,
        doc: /* Return the contact info of PROCESS; t for a real child.
-For a network or serial connection, the value depends on the optional
-KEY arg.  If KEY is nil, value is a cons cell of the form (HOST
-SERVICE) for a network connection or (PORT SPEED) for a serial
-connection.  If KEY is t, the complete contact information for the
-connection is returned, else the specific value for the keyword KEY is
-returned.  See `make-network-process' or `make-serial-process' for a
-list of keywords.  */)
+For a network or serial or pipe connection, the value depends on the
+optional KEY arg.  If KEY is nil, value is a cons cell of the form
+\(HOST SERVICE) for a network connection or (PORT SPEED) for a serial
+connection; it is t for a pipe connection.  If KEY is t, the complete
+contact information for the connection is returned, else the specific
+value for the keyword KEY is returned.  See `make-network-process',
+\`make-serial-process', or `make-pipe-process' for the list of keywords.  */)
   (register Lisp_Object process, Lisp_Object key)
 {
   Lisp_Object contact;
@@ -1254,7 +1254,7 @@ a socket connection.  */)
 
 DEFUN ("process-type", Fprocess_type, Sprocess_type, 1, 1, 0,
        doc: /* Return the connection type of PROCESS.
-The value is either the symbol `real', `network', or `serial'.
+The value is either the symbol `real', `network', `serial', or `pipe'.
 PROCESS may be a process, a buffer, the name of a process or buffer, or
 nil, indicating the current buffer's process.  */)
   (Lisp_Object process)
@@ -6156,8 +6156,8 @@ See function `interrupt-process' for more details on 
usage.  */)
 DEFUN ("stop-process", Fstop_process, Sstop_process, 0, 2, 0,
        doc: /* Stop process PROCESS.  May be process or name of one.
 See function `interrupt-process' for more details on usage.
-If PROCESS is a network or serial process, inhibit handling of incoming
-traffic.  */)
+If PROCESS is a network or serial or pipe connection, inhibit handling
+of incoming traffic.  */)
   (Lisp_Object process, Lisp_Object current_group)
 {
   if (PROCESSP (process) && (NETCONN_P (process) || SERIALCONN_P (process)