@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Processes
@chapter Processes
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
+(@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}.
@code{call-process}, above. If @var{destination} is the integer 0,
@code{call-process-region} discards the output and returns @code{nil}
immediately, without waiting for the subprocess to finish (this only
-works if asynchronous subprocesses are supported; i.e. not on MS-DOS).
+works if asynchronous subprocesses are supported; i.e., not on MS-DOS).
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program.
@section Creating an Asynchronous Process
@cindex asynchronous subprocess
- After an @dfn{asynchronous process} is created, Emacs and the subprocess
-both continue running immediately. The process thereafter runs
-in parallel with Emacs, and the two can communicate with each other
-using the functions described in the following sections. However,
+ In this section, we describe how to create an @dfn{asynchronous
+process}. After an asynchronous process is created, it runs in
+parallel with Emacs, and Emacs can communicate with it using the
+functions described in the following sections (@pxref{Input to
+Processes}, and @pxref{Output from Processes}). Note that process
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 when Emacs is waiting for input or for a time
-delay.
-
- Here we describe how to create an asynchronous process.
+from the process only while waiting for input or for a time delay.
+
+@cindex pty
+@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
+@code{process-connection-type} (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.
@defun start-process name buffer-or-name program &rest args
This function creates a new asynchronous subprocess and starts the
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
+etc.)@: to be unique. The buffer @var{buffer-or-name} is the buffer to
associate with the process.
If @var{program} is @code{nil}, Emacs opens a new pseudoterminal (pty)
possible to apply @code{process-filter} or @code{process-sentinel} to
the resulting process object. @xref{Filter Functions}, and @ref{Sentinels}.
-@c FIXME Can we find a better example (i.e. a more modern function
+@c FIXME Can we find a better example (i.e., a more modern function
@c that is actually documented).
Some file handlers may not support @code{start-file-process} (for
example the function @code{ange-ftp-hook-function}). In such cases,
@end defun
@defvar process-connection-type
-@cindex pipes
-@cindex @acronym{PTY}s
This variable controls the type of device used to communicate with
-asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are
+asynchronous subprocesses. If it is non-@code{nil}, then ptys are
used, when available. Otherwise, pipes are used.
-@acronym{PTY}s are usually preferable for processes visible to the user, as
-in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
-etc.) to work 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. In
-addition, the total number of @acronym{PTY}s is limited on many systems and
-it is good not to waste them.
-
The value of @code{process-connection-type} takes effect when
@code{start-process} is called. So you can specify how to communicate
with one subprocess by binding the variable around the call to
@end group
@end smallexample
-To determine whether a given subprocess actually got a pipe or a
-@acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process
+To determine whether a given subprocess actually got a pipe or a pty,
+use the function @code{process-tty-name} (@pxref{Process
Information}).
@end defvar
@c FIXME which?
Some operating systems have limited space for buffered input in a
-@acronym{PTY}. On these systems, Emacs sends an @acronym{EOF}
-periodically amidst the other characters, to force them through. For
-most programs, these @acronym{EOF}s do no harm.
+pty. On these systems, Emacs sends an @acronym{EOF} periodically
+amidst the other characters, to force them through. For most
+programs, these @acronym{EOF}s do no harm.
Subprocess input is normally encoded using a coding system before the
subprocess receives it, much like text written into a file. You can use
@defun quit-process &optional process current-group
This function sends the signal @code{SIGQUIT} to the process
@var{process}. This signal is the one sent by the ``quit
-@c FIXME? Never heard of C-b being used for this. In readline, eg
+@c FIXME? Never heard of C-b being used for this. In readline, e.g.,
@c bash, that is backward-word.
character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
Emacs.
@item start
The time when the process was started, in the same
-@w{@code{(@var{high} @var{low} @var{microsec} @var{picosec})}} format used by
-@code{current-time} and by @code{file-attributes}.
+@code{(@var{high} @var{low} @var{microsec} @var{picosec})} format used by
+@code{file-attributes} and @code{current-time}.
@item etime
-The time elapsed since the process started, in the @w{@code{(@var{high}
-@var{low} @var{microsec} @var{picosec})}} format.
+The time elapsed since the process started, in the format @code{(@var{high}
+@var{low} @var{microsec} @var{picosec})}.
@item vsize
The virtual memory size of the process, measured in kilobytes.
@cindex stopbits, in serial connections
@cindex flowcontrol, in serial connections
-This functions configures a serial port connection. Arguments are
+This function configures a serial port connection. Arguments are
specified as keyword/argument pairs. Attributes that are not given
are re-initialized from the process's current configuration (available
via the function @code{process-contact}), or set to reasonable default
HCoop / bpt / emacs.git / blobdiff