@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/processes
@node Processes, Display, Abbrevs, Top
an asynchronous subprocess.
* Output from Processes:: Collecting output from an asynchronous subprocess.
* Sentinels:: Sentinels run when process run-status changes.
+* Query Before Exit:: Whether to query if exiting will kill a process.
* Transaction Queues:: Transaction-based communication with subprocesses.
* Network:: Opening network connections.
@end menu
specify overrides for it with @code{process-environment}. @xref{System
Environment}.
-@defvar exec-directory
+@defvar exec-directory
@pindex movemail
The value of this variable is a string, the name of a directory that
contains programs that come with GNU Emacs, programs intended for Emacs
@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 subprocess are supported).
+works if asynchronous subprocesses are supported).
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program.
@smallexample
@group
-(call-process-region
- start end
+(call-process-region
+ start end
shell-file-name ; @r{Name of program.}
nil ; @r{Do not delete region.}
buffer ; @r{Send output to @code{buffer}.}
@end defun
@defun shell-command-to-string command
-@tindex shell-command-to-string
This function executes @var{command} (a string) as a shell command,
then returns the command's output as a string.
@end defun
addition, the total number of @sc{pty}s is limited on many systems and
it is good not to waste them.
-The value of @code{process-connection-type} is used when
+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
@code{start-process}.
@cindex deleting processes
@dfn{Deleting a process} disconnects Emacs immediately from the
-subprocess, and removes it from the list of active processes. It sends
-a signal to the subprocess to make the subprocess terminate, but this is
-not guaranteed to happen immediately. The process object itself
-continues to exist as long as other Lisp objects point to it. The
-process mark continues to point to the same place as before (usually
-into a buffer where output from the process was being inserted).
-
- You can delete a process explicitly at any time. Processes are
-deleted automatically after they terminate, but not necessarily right
-away. If you delete a terminated process explicitly before it is
-deleted automatically, no harm results.
+subprocess. Processes are deleted automatically after they terminate,
+but not necessarily right away. You can delete a process explicitly
+at any time. If you delete a terminated process explicitly before it
+is deleted automatically, no harm results. Deletion of a running
+process sends a signal to terminate it (and its child processes if
+any), and calls the process sentinel if it has one.
+
+ @code{get-buffer-process} and @code{process-list} do not remember a
+deleted process, but the process object itself continues to exist as
+long as other Lisp objects point to it. All the Lisp primitives that
+work on process objects accept deleted processes, but those that do
+I/O or send signals will report an error. The process mark continues
+to point to the same place as before, usually into a buffer where
+output from the process was being inserted.
@defopt delete-exited-processes
This variable controls automatic deletion of processes that have
@end defopt
@defun delete-process name
-This function deletes the process associated with @var{name}, killing it
-with a @code{SIGHUP} signal. The argument @var{name} may be a process,
-the name of a process, a buffer, or the name of a buffer.
+This function deletes the process associated with @var{name}, killing
+it with a @code{SIGKILL} signal. The argument @var{name} may be a
+process, the name of a process, a buffer, or the name of a buffer.
+Calling @code{delete-process} on a running process terminates it,
+updates the process status, and runs the sentinel (if any) 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).
@smallexample
@group
@end smallexample
@end defun
-@defun process-kill-without-query process &optional do-query
-This function specifies whether Emacs should query the user if
-@var{process} is still running when Emacs is exited. If @var{do-query}
-is @code{nil}, the process will be deleted silently.
-Otherwise, Emacs will query about killing it.
-
-The value is @code{t} if the process was formerly set up to require
-query, @code{nil} otherwise. A newly-created process always requires
-query.
-
-@smallexample
-@group
-(process-kill-without-query (get-process "shell"))
- @result{} t
-@end group
-@end smallexample
-@end defun
-
@node Process Information
@section Process Information
@end defun
@defun process-contact process
-@tindex process-contact
This function returns @code{t} for an ordinary child process, and
@code{(@var{hostname} @var{service})} for a net connection
(@pxref{Network}).
@end defun
@defun process-coding-system process
-@tindex process-coding-system
This function returns a cons cell describing the coding systems in use
for decoding output from @var{process} and for encoding input to
@var{process} (@pxref{Coding Systems}). The value has this form:
@end defun
@defun set-process-coding-system process decoding-system encoding-system
-@tindex set-process-coding-system
This function specifies the coding systems to use for subsequent output
from and input to @var{process}. It will use @var{decoding-system} to
decode subprocess output, and @var{encoding-system} to encode subprocess
the process has no buffer and no filter function, its output is
discarded.
+ When a subprocess terminates, Emacs reads any pending output,
+then stops reading output from that subprocess. Therefore, if the
+subprocess has children that are still live and still producing
+output, Emacs won't receive that output.
+
Output from a subprocess can arrive only while Emacs is waiting: when
reading terminal input, in @code{sit-for} and @code{sleep-for}
(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
can arrive before you finish, if the code in between does not call any
primitive that waits.
+ 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.
+
Subprocess output is normally decoded using a coding system before the
buffer or filter function receives it, much like text read from a file.
You can use @code{set-process-coding-system} to specify which coding
@end defun
@defun get-buffer-process buffer-or-name
-This function returns the process associated with @var{buffer-or-name}.
-If there are several processes associated with it, then one is chosen.
-(Currently, the one chosen is the one most recently created.) It is
-usually a bad idea to have more than one process associated with the
-same buffer.
+This function returns a nondeleted process associated with the buffer
+specified by @var{buffer-or-name}. If there are several processes
+associated with it, this function chooses one (currently, the one most
+recently created, but don't count on that). Deletion of a process
+(see @code{delete-process}) makes it ineligible for this function to
+return.
+
+It is usually a bad idea to have more than one process associated with
+the same buffer.
@smallexample
@group
A @dfn{process sentinel} is a function that is called whenever the
associated process changes status for any reason, including signals
(whether sent by Emacs or caused by the process's own actions) that
-terminate, stop, or continue the process. The process sentinel is also
-called if the process exits. The sentinel receives two arguments: the
-process for which the event occurred, and a string describing the type
-of event.
+terminate, stop, or continue the process. The process sentinel is
+also called if the process exits. The sentinel receives two
+arguments: the process for which the event occurred, and a string
+describing the type of event.
The string describing the event looks like one of the following:
@itemize @bullet
-@item
+@item
@code{"finished\n"}.
@item
@code{"@var{name-of-signal} (core dumped)\n"}.
@end itemize
- A sentinel runs only while Emacs is waiting (e.g., for terminal input,
-or for time to elapse, or for process output). This avoids the timing
-errors that could result from running them at random places in the
-middle of other Lisp programs. A program can wait, so that sentinels
-will run, by calling @code{sit-for} or @code{sleep-for}
+ A sentinel runs only while Emacs is waiting (e.g., for terminal
+input, or for time to elapse, or for process output). This avoids the
+timing errors that could result from running them at random places in
+the middle of other Lisp programs. A program can wait, so that
+sentinels will run, by calling @code{sit-for} or @code{sleep-for}
(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
Output}). Emacs also allows sentinels to run when the command loop is
-reading input.
+reading input. @code{delete-process} calls the sentinel when it
+terminates a running process.
+
+ Emacs does not keep a queue of multiple reasons to call the sentinel
+of one process; it records just the current status and the fact that
+there has been a change. Therefore two changes in status, coming in
+quick succession, can call the sentinel just once. However, process
+termination will always run the sentinel exactly once. This is
+because the process status can't change again after termination.
Quitting is normally inhibited within a sentinel---otherwise, the
effect of typing @kbd{C-g} at command level or to quit a user command
off. This makes it possible to use the Lisp debugger to debug the
sentinel. @xref{Debugger}.
+ While a sentinel is running, the process sentinel is temporarily
+set to @code{nil} so that the sentinel won't run recursively.
+For this reason it is not possible for a sentinel to specify
+a new sentinel.
+
In earlier Emacs versions, every sentinel that did regular expression
searching or matching had to explicitly save and restore the match data.
Now Emacs does this automatically for sentinels; they never need to do
The default behavior when there is no sentinel is to insert a message in
the process's buffer when the process status changes.
+Changes in process sentinel take effect immediately---if the sentinel
+is slated to be run but has not been called yet, and you specify a new
+sentinel, the eventual call to the sentinel will use the new one.
+
@smallexample
@group
(defun msg-me (process event)
was not.
@end defun
+@node Query Before Exit
+@section Querying Before Exit
+
+ When Emacs exits, it terminates all its subprocesses by sending them
+the @code{SIGHUP} signal. Because some subprocesses are 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
+non-@code{nil}, 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.
+
+@tindex process-query-on-exit-flag
+@defun process-query-on-exit-flag process
+This returns the query flag of @var{process}.
+@end defun
+
+@tindex set-process-query-on-exit-flag
+@defun set-process-query-on-exit-flag process flag
+This function sets the query flag of @var{process} to @var{flag}. It
+returns @var{flag}.
+
+@smallexample
+@group
+;; @r{Don't query about the shell process}
+(set-process-query-on-exit-flag (get-process "shell") nil)
+ @result{} t
+@end group
+@end smallexample
+@end defun
+
+@defun process-kill-without-query process &optional do-query
+This function clears the query flag of @var{process}, so that
+Emacs will not query the user on account of that process.
+
+Actually, the function does more than that: it returns the old value of
+the process's query flag, and sets the query flag to @var{do-query}.
+Please don't use this function to do those things any more---please
+use the newer, cleaner functions @code{process-query-on-exit-flag} and
+@code{set-process-query-on-exit-flag} in all but the simplest cases.
+The only way you should use @code{process-kill-without-query} nowadays
+is like this:
+
+@smallexample
+@group
+;; @r{Don't query about the shell process}
+(process-kill-without-query (get-process "shell"))
+@end group
+@end smallexample
+@end defun
+
@node Transaction Queues
@section Transaction Queues
@cindex transaction queue
corresponding answer comes back; it is called with two arguments:
@var{closure}, and the answer received.
-The argument @var{regexp} is a regular expression that should match the
-entire answer, but nothing less; that's how @code{tq-enqueue} determines
-where the answer ends.
+The argument @var{regexp} is a regular expression that should match
+text at the end of the entire answer, but nothing before; that's how
+@code{tq-enqueue} determines where the answer ends.
The return value of @code{tq-enqueue} itself is not meaningful.
@end defun