@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, Display, Abbrevs, Top
+@node Processes
@chapter Processes
@cindex child process
@cindex parent process
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}.
Executing a program can also try adding suffixes to the specified
name:
-@defvar exec-suffixes
+@defopt exec-suffixes
This variable is a list of suffixes (strings) to try adding to the
specified program file name. The list should include @code{""} if you
want the name to be tried exactly as specified. The default value is
system-dependent.
-@end defvar
+@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
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 filter function
+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.
@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
at any time. If you explicitly delete a terminated process before it
is deleted automatically, no harm results. Deleting a running
process sends a signal to terminate it (and its child processes, if
-any), and calls the process sentinel if it has one. @xref{Sentinels}.
+any), and calls the process sentinel. @xref{Sentinels}.
When a process is deleted, the process object itself continues to
exist as long as other Lisp objects point to it. All the Lisp
buffer, or the name of a buffer. (A buffer or buffer-name stands for
the process that @code{get-buffer-process} returns.) Calling
@code{delete-process} on a running process terminates it, updates the
-process status, and runs the sentinel (if any) immediately. If 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).
@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 interrupt-process &optional process current-group
This function interrupts the process @var{process} by sending the
signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt
-character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
+character'' (normally @kbd{C-c} on some systems, and @key{DEL} on
others) sends this signal. When the argument @var{current-group} is
non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
on the terminal by which Emacs talks to the subprocess.
@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.
stopped previously.
@end defun
-@defun signal-process process signal
+@deffn Command signal-process process signal
This function sends a signal to process @var{process}. The argument
@var{signal} specifies which signal to send; it should be an integer,
or a symbol whose name is a signal.
The @var{process} argument can be a system process @acronym{ID} (an
integer); that allows you to send signals to processes that are not
children of Emacs. @xref{System Processes}.
-@end defun
+@end deffn
@node Output from Processes
@section Receiving Output from Processes
@cindex process output
@cindex output from processes
- There are two ways to receive the output that a subprocess writes to
-its standard output stream. The output can be inserted in a buffer,
-which is called the associated buffer of the process (@pxref{Process
-Buffers}), or a function called the @dfn{filter function} can be
-called to act on the output. If the process has no buffer and no
-filter function, its output is discarded.
+ 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.
When a subprocess terminates, Emacs reads any pending output,
then stops reading output from that subprocess. Therefore, if the
shell command.
@menu
-* Process Buffers:: If no filter, output is put in a buffer.
+* Process Buffers:: By default, output is put in a buffer.
* Filter Functions:: Filter functions accept output from the process.
* Decoding Output:: Filters can get unibyte or multibyte strings.
* Accepting Output:: How to wait until process output arrives.
Many applications of processes also use the buffer for editing input to
be sent to the process, but this is not built into Emacs Lisp.
- Unless the process has a filter function (@pxref{Filter Functions}),
-its output is inserted in the associated buffer. The position to insert
-the output is determined by the @code{process-mark}, which is then
-updated to point to the end of the text just inserted. Usually, but not
-always, the @code{process-mark} is at the end of the buffer.
+ By default, process output is inserted in the associated buffer.
+(You can change this by defining a custom filter function,
+@pxref{Filter Functions}.) The position to insert the output is
+determined by the @code{process-mark}, which is then updated to point
+to the end of the text just inserted. Usually, but not always, the
+@code{process-mark} is at the end of the buffer.
@findex process-kill-buffer-query-function
Killing the associated buffer of a process also kills the process.
If @var{process} does not have a buffer, @code{process-mark} returns a
marker that points nowhere.
-Insertion of process output in a buffer uses this marker to decide where
-to insert, and updates it to point after the inserted text. That is why
-successive batches of output are inserted consecutively.
+The default filter function uses this marker to decide where to
+insert process output, and updates it to point after the inserted text.
+That is why successive batches of output are inserted consecutively.
-Filter functions normally should use this marker in the same fashion
-as is done by direct insertion of output in the buffer. For an
-example of a filter function that uses @code{process-mark},
+Custom filter functions normally should use this marker in the same fashion.
+For an example of a filter function that uses @code{process-mark},
@pxref{Process Filter Example}.
When the user is expected to enter input in the process buffer for
@cindex process filter
A process @dfn{filter function} is a function that receives the
-standard output from the associated process. If a process has a filter,
-then @emph{all} output from that process is passed to the filter. The
-process buffer is used directly for output from the process only when
-there is no filter.
+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.
The filter function can only be called when Emacs is waiting for
something, because process output arrives only at such times. Emacs
filter function. @xref{Debugger}.
Many filter functions sometimes (or always) insert the output in the
-process's buffer, mimicking the actions of Emacs when there is no
-filter. Such filter functions need to make sure that they save the
+process's buffer, mimicking the actions of the default filter.
+Such filter functions need to make sure that they save the
current buffer, select the correct buffer (if different) before
inserting output, and then restore the original buffer.
They should also check whether the buffer is still alive, update the
@defun set-process-filter process filter
This function gives @var{process} the filter function @var{filter}. If
-@var{filter} is @code{nil}, it gives the process no filter.
+@var{filter} is @code{nil}, it gives the process the default filter,
+which inserts the process output into the process buffer.
@end defun
@defun process-filter process
-This function returns the filter function of @var{process}, or @code{nil}
-if it has none.
+This function returns the filter function of @var{process}.
@end defun
Here is an example of the use of a filter function:
@ignore @c The code in this example doesn't show the right way to do things.
Here is another, more realistic example, which demonstrates how to use
-the process mark to do insertion in the same fashion as is done when
-there is no filter function:
+the process mark to do insertion in the same fashion as the default filter:
@smallexample
@group
@defun accept-process-output &optional process seconds millisec just-this-one
This function allows Emacs to read pending output from processes. The
-output is inserted in the associated buffers or given to their filter
-functions. If @var{process} is non-@code{nil} then this function does
-not return until some output has been received from @var{process}.
+output is given to their filter functions. If @var{process} is
+non-@code{nil} then this function does not return until some output
+has been received from @var{process}.
The arguments @var{seconds} and @var{millisec} let you specify timeout
periods. The former specifies a period measured in seconds and the
@defun set-process-sentinel process sentinel
This function associates @var{sentinel} with @var{process}. If
-@var{sentinel} is @code{nil}, then the process will have no sentinel.
-The default behavior when there is no sentinel is to insert a message in
-the process's buffer when the process status changes.
+@var{sentinel} is @code{nil}, then the process will have the default
+sentinel, which inserts a message in the process's buffer when the
+process status changes.
Changes in process sentinels take effect immediately---if the sentinel
is slated to be run but has not been called yet, and you specify a new
@end defun
@defun process-sentinel process
-This function returns the sentinel of @var{process}, or @code{nil} if it
-has none.
+This function returns the sentinel of @var{process}.
@end defun
@defun waiting-for-user-input-p
@item utime
Time spent by the process in the user context, for running the
application's code. The corresponding @var{value} is in the
-@w{@code{(@var{high} @var{low} @var{microsec})}} format, the same
+@w{@code{(@var{high} @var{low} @var{microsec} @var{picosec})}} format, the same
format used by functions @code{current-time} (@pxref{Time of Day,
current-time}) and @code{file-attributes} (@pxref{File Attributes}).
@item start
The time when the process was started, in the same
-@w{@code{(@var{high} @var{low} @var{microsec})}} format used by
-@code{current-time} and @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})}} 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.
The @var{buffer} argument is the buffer to associate with the
connection. Output from the connection is inserted in the buffer,
-unless you specify a filter function to handle the output. If
+unless you specify your own filter function to handle the output. If
@var{buffer} is @code{nil}, it means that the connection is not
associated with any buffer.
is unique for each connection in the Emacs session.
@item
-If the server's filter is non-@code{nil}, the connection process does
+If the server has a non-default filter, the connection process does
not get a separate process buffer; otherwise, Emacs creates a new
buffer for the purpose. The buffer name is the server's buffer name
or process name, concatenated with the client identification string.
@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