@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Processes
@node Subprocess Creation
@section Functions that Create Subprocesses
+@cindex create subprocess
+@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
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.
Precisely what this function does depends on your operating system. The
function is designed to work with the syntax of your system's standard
shell; if you use an unusual shell, you will need to redefine this
-function.
+function. @xref{Security Considerations}.
@example
;; @r{This example shows the behavior on GNU and Unix systems.}
a shell command:
@example
-(concat "diff -c "
+(concat "diff -u "
(shell-quote-argument oldfile)
" "
(shell-quote-argument newfile))
Insert the output in that buffer, before point. This includes both the
standard output stream and the standard error stream of the process.
-@item a string
+@item a buffer name (a string)
Insert the output in a buffer with that name, before point.
@item @code{t}
@c It actually uses shell-command-switch, but no need to mention that here.
@end defun
-@defun call-process-shell-command command &optional infile destination display &rest args
+@defun call-process-shell-command command &optional infile destination display
This function executes the shell command @var{command} synchronously.
-The final arguments @var{args} are additional arguments to add at the
-end of @var{command}. The other arguments are handled as in
-@code{call-process}.
+The arguments are handled as in @code{call-process}. An old calling
+convention allowed to pass 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 &rest args
+@defun process-file-shell-command command &optional infile destination display
This function is like @code{call-process-shell-command}, but uses
@code{process-file} internally. Depending on @code{default-directory},
-@var{command} can be executed also on remote hosts.
+@var{command} can be executed also on remote hosts. An old calling
+convention allowed to pass any number of additional arguments after
+@var{display}, which were concatenated to @var{command}; this is still
+supported, but strongly discouraged.
@end defun
@defun shell-command-to-string command
Information}).
@end defvar
+@defun 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
+@code{nil}. Here are the meaningful keywords:
+
+@table @asis
+@item :name @var{name}
+Use the string @var{name} as the process name. It is modified if
+necessary to make it unique.
+
+@item :buffer @var{buffer}
+Use @var{buffer} as the process buffer.
+
+@item :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.
+
+@item :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
+@w{@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}.
+
+@item :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.
+
+@item :noquery @var{query-flag}
+Initialize the process query flag to @var{query-flag}.
+@xref{Query Before Exit}.
+
+@item :stop @var{stopped}
+If @var{stopped} is non-@code{nil}, start the process in the
+stopped state.
+
+@item :filter @var{filter}
+Initialize the process filter to @var{filter}. If not specified, a
+default filter will be provided. @xref{Filter Functions}.
+
+@item :sentinel @var{sentinel}
+Initialize the process sentinel to @var{sentinel}. If not specified,
+a default sentinel will be used. @xref{Sentinels}.
+
+@item :stderr @var{stderr}
+Associate @var{stderr} with the standard error of the process.
+@var{stderr} is either a buffer or a pipe process created with
+@code{make-pipe-process}.
+@end table
+
+The original argument list, modified with the actual connection
+information, is available via the @code{process-contact} function.
+@end defun
+
+@defun 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
+@code{nil}, except for @code{:coding}.
+Here are the meaningful keywords:
+
+@table @asis
+@item :name @var{name}
+Use the string @var{name} as the process name. It is modified if
+necessary to make it unique.
+
+@item :buffer @var{buffer}
+Use @var{buffer} as the process buffer.
+
+@item :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
+@w{@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}.
+
+@item :noquery @var{query-flag}
+Initialize the process query flag to @var{query-flag}.
+@xref{Query Before Exit}.
+
+@item :stop @var{stopped}
+If @var{stopped} is non-@code{nil}, start the process in the
+stopped state.
+
+@item :filter @var{filter}
+Initialize the process filter to @var{filter}. If not specified, a
+default filter will be provided. @xref{Filter Functions}.
+
+@item :sentinel @var{sentinel}
+Initialize the process sentinel to @var{sentinel}. If not specified,
+a default sentinel will be used. @xref{Sentinels}.
+@end table
+
+The original argument list, modified with the actual connection
+information, is available via the @code{process-contact} function.
+@end defun
+
@node Deleting Processes
@section Deleting Processes
@cindex deleting processes
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).
@node Process Information
@section Process Information
+@cindex process information
Several functions return information about processes.
@item :buffer
The associated value is the process buffer.
@item :filter
-The associated value is the process filter function.
+The associated value is the process filter function. @xref{Filter
+Functions}.
@item :sentinel
-The associated value is the process sentinel function.
+The associated value is the process sentinel function. @xref{Sentinels}.
@item :remote
In a connection, the address in internal format of the remote peer.
@item :local
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.
+data appears on the standard input of the subprocess.
@c FIXME which?
Some operating systems have limited space for buffered input in a
@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 @key{DEL} on
+signal @code{SIGINT}. Outside of Emacs, typing the interrupt
+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}''
+non-@code{nil}, you can think of this function as typing @kbd{C-c}
on the terminal by which Emacs talks to the subprocess.
@end defun
@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, e.g.,
-@c bash, that is backward-word.
-character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
+@var{process}. This signal is the one sent by the quit
+character (usually @kbd{C-\}) when you are not inside
Emacs.
@end defun
signal @code{SIGTSTP}. Use @code{continue-process} to resume its
execution.
-Outside of Emacs, on systems with job control, the ``stop character''
+Outside of Emacs, on systems with job control, the stop character
(usually @kbd{C-z}) normally sends this signal. When
@var{current-group} is non-@code{nil}, you can think of this function as
-``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
+typing @kbd{C-z} on the terminal Emacs uses to communicate with the
subprocess.
@end defun
@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 filter function
@cindex process filter
+@cindex default filter function of a process
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
+In case the process's output needs to be passed to several filters, you can
+use @code{add-function} to combine an existing filter with a new one.
+@xref{Advising Functions}.
+
Here is an example of the use of a filter function:
@smallexample
@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
latter specifies one measured in milliseconds. The two time periods
thus specified are added together, and @code{accept-process-output}
-returns after that much time, whether or not there has been any
+returns after that much time, even if there is no
subprocess output.
The argument @var{millisec} is obsolete (and should not be used),
-because @var{seconds} can be a floating point number to specify
+because @var{seconds} can be floating point to specify
waiting a fractional number of seconds. If @var{seconds} is 0, the
function accepts whatever output is pending but does not wait.
speech synthesis.
The function @code{accept-process-output} returns non-@code{nil} if it
-did get some output, or @code{nil} if the timeout expired before output
+got output from @var{process}, or from any process if @var{process} is
+@code{nil}. It returns @code{nil} if the timeout expired before output
arrived.
@end defun
arguments: the process for which the event occurred, and a string
describing the type of event.
+@cindex default sentinel function of a process
+ If no sentinel function was specified for a process, it will use the
+default sentinel function, which inserts a message in the process's
+buffer with the process name and the string describing the event.
+
The string describing the event looks like one of the following:
-@c FIXME? Also "killed\n" - see example below?
@itemize @bullet
@item
@code{"finished\n"}.
@item
-@code{"exited abnormally with code @var{exitcode}\n"}.
+@code{"deleted\n"}.
+
+@item
+@code{"exited abnormally with code @var{exitcode} (core dumped)\n"}.
+The ``core dumped'' part is optional, and only appears if the process
+dumped core.
@item
-@code{"@var{name-of-signal}\n"}.
+@code{"failed with code @var{fail-code}\n"}.
@item
-@code{"@var{name-of-signal} (core dumped)\n"}.
+@code{"@var{signal-description} (core dumped)\n"}. The
+@var{signal-description} is a system-dependent textual description of
+a signal, e.g., @code{"killed"} for @code{SIGKILL}. The ``core
+dumped'' part is optional, and only appears if the process dumped
+core.
+
+@item
+@code{"open from @var{host-name}\n"}.
+
+@item
+@code{"open\n"}.
+
+@item
+@code{"connection broken by remote peer\n"}.
@end itemize
A sentinel runs only while Emacs is waiting (e.g., for terminal
@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
@group
(defun msg-me (process event)
(princ
- (format "Process: %s had the event `%s'" process event)))
+ (format "Process: %s had the event '%s'" process event)))
(set-process-sentinel (get-process "shell") 'msg-me)
@result{} msg-me
@end group
@group
(kill-process (get-process "shell"))
- @print{} Process: #<process shell> had the event `killed'
+ @print{} Process: #<process shell> had the event 'killed'
@result{} #<process shell>
@end group
@end smallexample
@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
+In case a process status changes need to be passed to several sentinels, you
+can use @code{add-function} to combine an existing sentinel with a new one.
+@xref{Advising Functions}.
+
@defun waiting-for-user-input-p
While a sentinel or filter function is running, this function returns
non-@code{nil} if Emacs was waiting for keyboard input from the user at
attribute @var{key}s that this function can return are listed below.
Not all platforms support all of these attributes; if an attribute is
not supported, its association will not appear in the returned alist.
-Values that are numbers can be either integer or floating-point,
+Values that are numbers can be either integer or floating point,
depending on the magnitude of the value.
@table @code
@item "T"
stopped, e.g., by a job control signal
@item "Z"
-``zombie'': a process that terminated, but was not reaped by its parent
+zombie: a process that terminated, but was not reaped by its parent
@end table
@noindent
@cindex @acronym{STARTTLS} network connections
Emacs can create encrypted network connections, using either built-in
or external support. The built-in support uses the GnuTLS
-(``Transport Layer Security'') library; see
+Transport Layer Security Library; see
@uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}.
If your Emacs was compiled with GnuTLS support, the function
@code{gnutls-available-p} is defined and returns non-@code{nil}. For
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.
An ordinary, unencrypted connection.
@item tls
@itemx ssl
-A @acronym{TLS} (``Transport Layer Security'') connection.
+A @acronym{TLS} (Transport Layer Security) connection.
@item nil
@itemx network
Start with a plain connection, and if parameters @samp{:success}
If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs
doesn't have built-in @acronym{TLS} support.
+@item :warn-unless-encrypted @var{boolean}
+If non-@code{nil}, and @code{:return-value} is also non-@code{nil},
+Emacs will warn if the connection isn't encrypted. This is useful for
+protocols like @acronym{IMAP} and the like, where most users would
+expect the network traffic to be encrypted.
+
@item :client-certificate @var{list-or-t}
Either a list of the form @code{(@var{key-file} @var{cert-file})},
naming the certificate key file and certificate file itself, or
@end defun
+
@node Network Servers
@section Network Servers
@cindex network servers
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.
@item :type @var{type}
Specify the communication type. A value of @code{nil} specifies a
stream connection (the default); @code{datagram} specifies a datagram
-connection; @code{seqpacket} specifies a ``sequenced packet stream''
+connection; @code{seqpacket} specifies a sequenced packet stream
connection. Both connections and servers can be of these types.
@item :server @var{server-flag}
in the local address space.
@item
-An ``unsupported family'' address is represented by a cons
+An unsupported-family address is represented by a cons
@code{(@var{f} . @var{av})}, where @var{f} is the family number and
@var{av} is a vector specifying the socket address using one element
per address data byte. Do not rely on this format in portable code,
@item :stop @var{stopped}
If @var{stopped} is non-@code{nil}, start the network connection or
-server in the ``stopped'' state.
+server in the stopped state.
@item :buffer @var{buffer}
Use @var{buffer} as the process buffer.
Before Exit}. The flags defaults to @code{nil} if unspecified.
@item :stop @var{bool}
-Start process in the ``stopped'' state if @var{bool} is
+Start process in the stopped state if @var{bool} is
non-@code{nil}. In the stopped state, a serial process does not
accept incoming data, but you can send outgoing data. The stopped
state is cleared by @code{continue-process} and set by
@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
@dfn{fields}. This specification controls the length of each field to be
processed, and how to pack or unpack it. We normally keep bindat specs
in variables whose names end in @samp{-bindat-spec}; that kind of name
-is automatically recognized as ``risky''.
+is automatically recognized as risky.
@cindex endianness
@cindex big endian
A field's @dfn{type} describes the size (in bytes) of the object
that the field represents and, in the case of multibyte fields, how
the bytes are ordered within the field. The two possible orderings
-are ``big endian'' (also known as ``network byte ordering'') and
-``little endian''. For instance, the number @code{#x23cd} (decimal
+are @dfn{big endian} (also known as ``network byte ordering'') and
+@dfn{little endian}. For instance, the number @code{#x23cd} (decimal
9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
and in little endian, @code{#xcd} @code{#x23}. Here are the possible
type values: