mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-11-24 07:20:37 +00:00
1169 lines
44 KiB
Plaintext
1169 lines
44 KiB
Plaintext
@c -*-texinfo-*-
|
|
@c This is part of the GNU Emacs Lisp Reference Manual.
|
|
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
@c See the file elisp.texi for copying conditions.
|
|
@setfilename ../info/processes
|
|
@node Processes, System Interface, Abbrevs, Top
|
|
@chapter Processes
|
|
@cindex child process
|
|
@cindex parent process
|
|
@cindex subprocess
|
|
@cindex process
|
|
|
|
In the terminology of operating systems, a @dfn{process} is a space in
|
|
which a program can execute. Emacs runs in a process. Emacs Lisp
|
|
programs can invoke other programs in processes of their own. These are
|
|
called @dfn{subprocesses} or @dfn{child processes} of the Emacs process,
|
|
which is their @dfn{parent process}.
|
|
|
|
A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous},
|
|
depending on how it is created. When you create a synchronous
|
|
subprocess, the Lisp program waits for the subprocess to terminate
|
|
before continuing execution. When you create an asynchronous
|
|
subprocess, it can run in parallel with the Lisp program. This kind of
|
|
subprocess is represented within Emacs by a Lisp object which is also
|
|
called a ``process''. Lisp programs can use this object to communicate
|
|
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.
|
|
|
|
@defun processp object
|
|
This function returns @code{t} if @var{object} is a process,
|
|
@code{nil} otherwise.
|
|
@end defun
|
|
|
|
@menu
|
|
* Subprocess Creation:: Functions that start subprocesses.
|
|
* Synchronous Processes:: Details of using synchronous subprocesses.
|
|
* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
|
|
for data sent to and from a subprocess.
|
|
* Asynchronous Processes:: Starting up an asynchronous subprocess.
|
|
* Deleting Processes:: Eliminating an asynchronous subprocess.
|
|
* Process Information:: Accessing run-status and other attributes.
|
|
* Input to Processes:: Sending input to an asynchronous subprocess.
|
|
* Signals to Processes:: Stopping, continuing or interrupting
|
|
an asynchronous subprocess.
|
|
* Output from Processes:: Collecting output from an asynchronous subprocess.
|
|
* Sentinels:: Sentinels run when process run-status changes.
|
|
* Transaction Queues:: Transaction-based communication with subprocesses.
|
|
* TCP:: Opening network connections.
|
|
@end menu
|
|
|
|
@node Subprocess Creation
|
|
@section Functions that Create Subprocesses
|
|
|
|
There are three functions that create a new subprocess in which to run
|
|
a program. One of them, @code{start-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
|
|
(@pxref{Synchronous Processes}).
|
|
|
|
Synchronous and asynchronous processes are explained in following
|
|
sections. Since the three functions are all called in a similar
|
|
fashion, their common arguments are described here.
|
|
|
|
@cindex execute program
|
|
@cindex @code{PATH} environment variable
|
|
@cindex @code{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
|
|
@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 @code{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}).
|
|
|
|
Each of the subprocess-creating functions has a @var{buffer-or-name}
|
|
argument which specifies where the standard output from the program will
|
|
go. If @var{buffer-or-name} is @code{nil}, that says to discard the
|
|
output unless a 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.
|
|
|
|
@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 are not allowed in these strings,
|
|
since they are passed directly to the specified program.
|
|
|
|
@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 @var{args} to provide those.
|
|
|
|
The subprocess gets its current directory from the value of
|
|
@code{default-directory} (@pxref{File Name Expansion}).
|
|
|
|
@cindex environment variables, subprocesses
|
|
The subprocess inherits its environment from Emacs; but you can
|
|
specify overrides for it with @code{process-environment}. @xref{System
|
|
Environment}.
|
|
|
|
@defvar exec-directory
|
|
@pindex wakeup
|
|
The value of this variable is the name of a directory (a string) that
|
|
contains programs that come with GNU Emacs, that are intended for Emacs
|
|
to invoke. The program @code{wakeup} is an example of such a program;
|
|
the @code{display-time} command uses it to get a reminder once per
|
|
minute.
|
|
@end defvar
|
|
|
|
@defopt exec-path
|
|
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}).
|
|
@cindex program directories
|
|
|
|
The value of @code{exec-path} is used by @code{call-process} and
|
|
@code{start-process} when the @var{program} argument is not an absolute
|
|
file name.
|
|
@end defopt
|
|
|
|
@node Synchronous Processes
|
|
@section Creating a Synchronous Process
|
|
@cindex synchronous subprocess
|
|
|
|
After a @dfn{synchronous process} is created, Emacs waits for the
|
|
process to terminate before continuing. Starting Dired is an example of
|
|
this: it runs @code{ls} in a synchronous process, then modifies the
|
|
output slightly. Because the process is synchronous, the entire
|
|
directory listing arrives in the buffer before Emacs tries to do
|
|
anything with it.
|
|
|
|
While Emacs waits for the synchronous subprocess to terminate, the
|
|
user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
|
|
the subprocess with a @code{SIGINT} signal; but it waits until the
|
|
subprocess actually terminates before quitting. If during that time the
|
|
user types another @kbd{C-g}, that kills the subprocess instantly with
|
|
@code{SIGKILL} and quits immediately. @xref{Quitting}.
|
|
|
|
The synchronous subprocess functions returned @code{nil} in version
|
|
18. In version 19, they return an indication of how the process
|
|
terminated.
|
|
|
|
@defun call-process program &optional infile buffer-or-name display &rest args
|
|
This function calls @var{program} in a separate process and waits for
|
|
it to finish.
|
|
|
|
The standard input for the process comes from file @var{infile} if
|
|
@var{infile} is not @code{nil} and from @file{/dev/null} otherwise. The
|
|
process output gets inserted in buffer @var{buffer-or-name} before point,
|
|
if that argument names a buffer. If @var{buffer-or-name} is @code{t},
|
|
output is sent to the current buffer; if @var{buffer-or-name} is
|
|
@code{nil}, output is discarded.
|
|
|
|
If @var{buffer-or-name} is the integer 0, @code{call-process} returns
|
|
@code{nil} immediately and discards any output. In this case, the
|
|
process is not truly synchronous, since it can run in parallel with
|
|
Emacs; but you can think of it as synchronous in that Emacs is
|
|
essentially finished with the subprocess as soon as this function
|
|
returns.
|
|
|
|
If @var{display} is non-@code{nil}, then @code{call-process} redisplays
|
|
the buffer as output is inserted. Otherwise the function does no
|
|
redisplay, and the 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.
|
|
|
|
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,
|
|
@code{call-process} returns a string describing the signal.
|
|
|
|
In the examples below, the buffer @samp{foo} is current.
|
|
|
|
@smallexample
|
|
@group
|
|
(call-process "pwd" nil t)
|
|
@result{} nil
|
|
|
|
---------- Buffer: foo ----------
|
|
/usr/user/lewis/manual
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
|
|
@group
|
|
(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
|
|
@result{} nil
|
|
|
|
---------- Buffer: bar ----------
|
|
lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
|
|
|
|
---------- Buffer: bar ----------
|
|
@end group
|
|
@end smallexample
|
|
|
|
The @code{insert-directory} function contains a good example of the use
|
|
of @code{call-process}:
|
|
|
|
@smallexample
|
|
@group
|
|
(call-process insert-directory-program nil t nil switches
|
|
(if full-directory-p
|
|
(concat (file-name-as-directory file) ".")
|
|
file))
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@defun call-process-region start end program &optional delete buffer-or-name display &rest args
|
|
This function sends the text between @var{start} to @var{end} as
|
|
standard input to a process running @var{program}. It deletes the text
|
|
sent if @var{delete} is non-@code{nil}; this is useful when @var{buffer}
|
|
is @code{t}, to insert the output in the current buffer.
|
|
|
|
The arguments @var{buffer-or-name} and @var{display} control what to do
|
|
with the output from the subprocess, and whether to update the display
|
|
as it comes in. For details, see the description of
|
|
@code{call-process}, above. If @var{buffer-or-name} is the integer 0,
|
|
@code{call-process-region} discards the output and returns @code{nil}
|
|
immediately, without waiting for the subprocess to finish.
|
|
|
|
The remaining arguments, @var{args}, are strings that specify command
|
|
line arguments for the program.
|
|
|
|
The return value of @code{call-process-region} is just like that of
|
|
@code{call-process}: @code{nil} if you told it to return without
|
|
waiting; otherwise, a number or string which indicates how the
|
|
subprocess terminated.
|
|
|
|
In the following example, we use @code{call-process-region} to run the
|
|
@code{cat} utility, with standard input being the first five characters
|
|
in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
|
|
standard input into its standard output. Since the argument
|
|
@var{buffer-or-name} is @code{t}, this output is inserted in the current
|
|
buffer.
|
|
|
|
@smallexample
|
|
@group
|
|
---------- Buffer: foo ----------
|
|
input@point{}
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
|
|
@group
|
|
(call-process-region 1 6 "cat" nil t)
|
|
@result{} nil
|
|
|
|
---------- Buffer: foo ----------
|
|
inputinput@point{}
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
@end smallexample
|
|
|
|
The @code{shell-command-on-region} command uses
|
|
@code{call-process-region} like this:
|
|
|
|
@smallexample
|
|
@group
|
|
(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}.}
|
|
nil ; @r{No redisplay during output.}
|
|
"-c" command) ; @r{Arguments for the shell.}
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@node MS-DOS Subprocesses
|
|
@section MS-DOS Subprocesses
|
|
|
|
On MS-DOS, you must indicate whether the data going to and from
|
|
a synchronous subprocess are text or binary. Text data requires
|
|
translation between the end-of-line convention used within Emacs
|
|
(a single newline character) and the convention used outside Emacs
|
|
(the two-character sequence, CRLF).
|
|
|
|
The variable @code{binary-process-input} applies to input sent to the
|
|
subprocess, and @code{binary-process-output} applies to output received
|
|
from it. A non-@code{nil} value means the data is non-text; @code{nil}
|
|
means the data is text, and calls for conversion.
|
|
|
|
@defvar binary-process-input
|
|
If this variable is @code{nil}, convert newlines to CRLF sequences in
|
|
the input to a synchronous subprocess.
|
|
@end defvar
|
|
|
|
@defvar binary-process-output
|
|
If this variable is @code{nil}, convert CRLF sequences to newlines in
|
|
the output from a synchronous subprocess.
|
|
@end defvar
|
|
|
|
@xref{Files and MS-DOS}, for related information.
|
|
|
|
@node Asynchronous Processes
|
|
@section Creating an Asynchronous Process
|
|
@cindex asynchronous subprocess
|
|
|
|
After an @dfn{asynchronous process} is created, Emacs and the Lisp
|
|
program both continue running immediately. The process may thereafter
|
|
run in parallel with Emacs, and the two may communicate with each other
|
|
using the functions described in following sections. Here we describe
|
|
how to create an asynchronous process with @code{start-process}.
|
|
|
|
@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 adding @samp{<1>}, etc.)
|
|
to be unique. The buffer @var{buffer-or-name} is the buffer to
|
|
associate with the process.
|
|
|
|
The remaining arguments, @var{args}, are strings that specify command
|
|
line arguments for the program.
|
|
|
|
In the example below, the first process is started and runs (rather,
|
|
sleeps) for 100 seconds. Meanwhile, the second process is started, and
|
|
given the name @samp{my-process<1>} for the sake of uniqueness. It
|
|
inserts the directory listing at the end of the buffer @samp{foo},
|
|
before the first process finishes. Then it finishes, and a message to
|
|
that effect is inserted in the buffer. Much later, the first process
|
|
finishes, and another message is inserted in the buffer for it.
|
|
|
|
@smallexample
|
|
@group
|
|
(start-process "my-process" "foo" "sleep" "100")
|
|
@result{} #<process my-process>
|
|
@end group
|
|
|
|
@group
|
|
(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
|
|
@result{} #<process my-process<1>>
|
|
|
|
---------- Buffer: foo ----------
|
|
total 2
|
|
lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
|
|
-rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
|
|
|
|
Process my-process<1> finished
|
|
|
|
Process my-process finished
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@defun start-process-shell-command name buffer-or-name command &rest command-args
|
|
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, and @var{command-args} are the arguments for the shell
|
|
command.
|
|
@end defun
|
|
|
|
@defvar process-connection-type
|
|
@cindex pipes
|
|
@cindex @sc{pty}s
|
|
This variable controls the type of device used to communicate with
|
|
asynchronous subprocesses. If it is @code{nil}, then pipes are used.
|
|
If it is @code{t}, then @sc{pty}s are used (or pipes if @sc{pty}s are
|
|
not supported).
|
|
|
|
@sc{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 @sc{pty}s is limited on many systems and it is good not
|
|
to waste them.
|
|
|
|
The value @code{process-connection-type} is used 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}.
|
|
|
|
@smallexample
|
|
@group
|
|
(let ((process-connection-type nil)) ; @r{Use a pipe.}
|
|
(start-process @dots{}))
|
|
@end group
|
|
@end smallexample
|
|
@end defvar
|
|
|
|
@node Deleting Processes
|
|
@section Deleting Processes
|
|
@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.
|
|
|
|
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.
|
|
|
|
@defvar delete-exited-processes
|
|
This variable controls automatic deletion of processes that have
|
|
terminated (due to calling @code{exit} or to a signal). If it is
|
|
@code{nil}, then they continue to exist until the user runs
|
|
@code{list-processes}. Otherwise, they are deleted immediately after
|
|
they exit.
|
|
@end defvar
|
|
|
|
@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.
|
|
|
|
@smallexample
|
|
@group
|
|
(delete-process "*shell*")
|
|
@result{} nil
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@defun process-kill-without-query process
|
|
This function declares that Emacs need not query the user if
|
|
@var{process} is still running when Emacs is exited. The process will
|
|
be deleted silently. The value is @code{t}.
|
|
|
|
@smallexample
|
|
@group
|
|
(process-kill-without-query (get-process "shell"))
|
|
@result{} t
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@node Process Information
|
|
@section Process Information
|
|
|
|
Several functions return information about processes.
|
|
@code{list-processes} is provided for interactive use.
|
|
|
|
@deffn Command list-processes
|
|
This command displays a listing of all living processes. In addition,
|
|
it finally deletes any process whose status was @samp{Exited} or
|
|
@samp{Signaled}. It returns @code{nil}.
|
|
@end deffn
|
|
|
|
@defun process-list
|
|
This function returns a list of all processes that have not been deleted.
|
|
|
|
@smallexample
|
|
@group
|
|
(process-list)
|
|
@result{} (#<process display-time> #<process shell>)
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@defun get-process name
|
|
This function returns the process named @var{name}, or @code{nil} if
|
|
there is none. An error is signaled if @var{name} is not a string.
|
|
|
|
@smallexample
|
|
@group
|
|
(get-process "shell")
|
|
@result{} #<process shell>
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@defun process-command process
|
|
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.
|
|
|
|
@smallexample
|
|
@group
|
|
(process-command (get-process "shell"))
|
|
@result{} ("/bin/csh" "-i")
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@defun process-id process
|
|
This function returns the @sc{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
|
|
@sc{pid} of a process is chosen by the operating system kernel when the
|
|
process is started and remains constant as long as the process exists.
|
|
@end defun
|
|
|
|
@defun process-name process
|
|
This function returns the name of @var{process}.
|
|
@end defun
|
|
|
|
@defun process-status process-name
|
|
This function returns the status of @var{process-name} as a symbol.
|
|
The argument @var{process-name} must be a process, a buffer, a
|
|
process name (string) or a buffer name (string).
|
|
|
|
The possible values for an actual subprocess are:
|
|
|
|
@table @code
|
|
@item run
|
|
for a process that is running.
|
|
@item stop
|
|
for a process that is stopped but continuable.
|
|
@item exit
|
|
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.
|
|
@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.
|
|
@item nil
|
|
if @var{process-name} is not the name of an existing process.
|
|
@end table
|
|
|
|
@smallexample
|
|
@group
|
|
(process-status "shell")
|
|
@result{} run
|
|
@end group
|
|
@group
|
|
(process-status (get-buffer "*shell*"))
|
|
@result{} run
|
|
@end group
|
|
@group
|
|
x
|
|
@result{} #<process xx<1>>
|
|
(process-status x)
|
|
@result{} exit
|
|
@end group
|
|
@end smallexample
|
|
|
|
For a network connection, @code{process-status} returns one of the symbols
|
|
@code{open} or @code{closed}. The latter means that the other side
|
|
closed the connection, or Emacs did @code{delete-process}.
|
|
|
|
In earlier Emacs versions (prior to version 19), the status of a network
|
|
connection was @code{run} if open, and @code{exit} if closed.
|
|
@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.
|
|
@end defun
|
|
|
|
@node Input to Processes
|
|
@section Sending Input to Processes
|
|
@cindex process input
|
|
|
|
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.
|
|
|
|
Some operating systems have limited space for buffered input in a
|
|
@sc{pty}. On these systems, Emacs sends an @sc{eof} periodically amidst
|
|
the other characters, to force them through. For most programs,
|
|
these @sc{eof}s do no harm.
|
|
|
|
@defun process-send-string process-name string
|
|
This function sends @var{process-name} the contents of @var{string} as
|
|
standard input. The argument @var{process-name} must be a process or
|
|
the name of a process. If it is @code{nil}, the current buffer's
|
|
process is used.
|
|
|
|
The function returns @code{nil}.
|
|
|
|
@smallexample
|
|
@group
|
|
(process-send-string "shell<1>" "ls\n")
|
|
@result{} nil
|
|
@end group
|
|
|
|
|
|
@group
|
|
---------- Buffer: *shell* ----------
|
|
...
|
|
introduction.texi syntax-tables.texi~
|
|
introduction.texi~ text.texi
|
|
introduction.txt text.texi~
|
|
...
|
|
---------- Buffer: *shell* ----------
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@deffn Command process-send-region process-name start end
|
|
This function sends the text in the region defined by @var{start} and
|
|
@var{end} as standard input to @var{process-name}, which is a process or
|
|
a process name. (If it is @code{nil}, the current buffer's process is
|
|
used.)
|
|
|
|
An error is signaled unless both @var{start} and @var{end} are
|
|
integers or markers that indicate positions in the current buffer. (It
|
|
is unimportant which number is larger.)
|
|
@end deffn
|
|
|
|
@defun process-send-eof &optional process-name
|
|
This function makes @var{process-name} see an end-of-file in its
|
|
input. The @sc{eof} comes after any text already sent to it.
|
|
|
|
If @var{process-name} is not supplied, or if it is @code{nil}, then
|
|
this function sends the @sc{eof} to the current buffer's process. An
|
|
error is signaled if the current buffer has no process.
|
|
|
|
The function returns @var{process-name}.
|
|
|
|
@smallexample
|
|
@group
|
|
(process-send-eof "shell")
|
|
@result{} "shell"
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@node Signals to Processes
|
|
@section Sending Signals to Processes
|
|
@cindex process signals
|
|
@cindex sending signals
|
|
@cindex signals
|
|
|
|
@dfn{Sending a signal} to a subprocess is a way of interrupting its
|
|
activities. There are several different signals, each with its own
|
|
meaning. The set of signals and their names is defined by the operating
|
|
system. For example, the signal @code{SIGINT} means that the user has
|
|
typed @kbd{C-c}, or that some analogous thing has happened.
|
|
|
|
Each signal has a standard effect on the subprocess. Most signals
|
|
kill the subprocess, but some stop or resume execution instead. Most
|
|
signals can optionally be handled by programs; if the program handles
|
|
the signal, then we can say nothing in general about its effects.
|
|
|
|
You can send signals explicitly by calling the functions in this
|
|
section. Emacs also sends signals automatically at certain times:
|
|
killing a buffer sends a @code{SIGHUP} signal to all its associated
|
|
processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
|
|
processes. (@code{SIGHUP} is a signal that usually indicates that the
|
|
user hung up the phone.)
|
|
|
|
Each of the signal-sending functions takes two optional arguments:
|
|
@var{process-name} and @var{current-group}.
|
|
|
|
The argument @var{process-name} must be either a process, the name of
|
|
one, or @code{nil}. If it is @code{nil}, the process defaults to the
|
|
process associated with the current buffer. An error is signaled if
|
|
@var{process-name} does not identify a process.
|
|
|
|
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 non-@code{nil}, 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.
|
|
|
|
The flag @var{current-group} has no effect when a pipe is used to
|
|
communicate with the subprocess, because the operating system does not
|
|
support the distinction in the case of pipes. For the same reason,
|
|
job-control shells won't work when a pipe is used. See
|
|
@code{process-connection-type} in @ref{Asynchronous Processes}.
|
|
|
|
@defun interrupt-process &optional process-name current-group
|
|
This function interrupts the process @var{process-name} by sending the
|
|
signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt
|
|
character'' (normally @kbd{C-c} on some systems, and @code{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.
|
|
@end defun
|
|
|
|
@defun kill-process &optional process-name current-group
|
|
This function kills the process @var{process-name} by sending the
|
|
signal @code{SIGKILL}. This signal kills the subprocess immediately,
|
|
and cannot be handled by the subprocess.
|
|
@end defun
|
|
|
|
@defun quit-process &optional process-name current-group
|
|
This function sends the signal @code{SIGQUIT} to the process
|
|
@var{process-name}. This signal is the one sent by the ``quit
|
|
character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
|
|
Emacs.
|
|
@end defun
|
|
|
|
@defun stop-process &optional process-name current-group
|
|
This function stops the process @var{process-name} by sending the
|
|
signal @code{SIGTSTP}. Use @code{continue-process} to resume its
|
|
execution.
|
|
|
|
On systems with job control, the ``stop character'' (usually @kbd{C-z})
|
|
sends this signal (outside of Emacs). 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 subprocess.
|
|
@end defun
|
|
|
|
@defun continue-process &optional process-name current-group
|
|
This function resumes execution of the process @var{process} by sending
|
|
it the signal @code{SIGCONT}. This presumes that @var{process-name} was
|
|
stopped previously.
|
|
@end defun
|
|
|
|
@c Emacs 19 feature
|
|
@defun signal-process pid signal
|
|
This function sends a signal to process @var{pid}, which need not be
|
|
a child of Emacs. The argument @var{signal} specifies which signal
|
|
to send; it should be an integer.
|
|
@end defun
|
|
|
|
@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, 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.
|
|
|
|
@menu
|
|
* Process Buffers:: If no filter, output is put in a buffer.
|
|
* Filter Functions:: Filter functions accept output from the process.
|
|
* Accepting Output:: Explicitly permitting subprocess output.
|
|
Waiting for subprocess output.
|
|
@end menu
|
|
|
|
@node Process Buffers
|
|
@subsection Process Buffers
|
|
|
|
A process can (and usually does) have an @dfn{associated buffer},
|
|
which is an ordinary Emacs buffer that is used for two purposes: storing
|
|
the output from the process, and deciding when to kill the process. You
|
|
can also use the buffer to identify a process to operate on, since in
|
|
normal practice only one process is associated with any given buffer.
|
|
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.
|
|
|
|
@defun process-buffer process
|
|
This function returns the associated buffer of the process
|
|
@var{process}.
|
|
|
|
@smallexample
|
|
@group
|
|
(process-buffer (get-process "shell"))
|
|
@result{} #<buffer *shell*>
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@defun process-mark process
|
|
This function returns the process marker for @var{process}, which is the
|
|
marker that says where to insert output from 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.
|
|
|
|
Filter functions normally should use this marker in the same fashion
|
|
as is done by direct insertion of output in the buffer. A good
|
|
example of a filter function that uses @code{process-mark} is found at
|
|
the end of the following section.
|
|
|
|
When the user is expected to enter input in the process buffer for
|
|
transmission to the process, the process marker is useful for
|
|
distinguishing the new input from previous output.
|
|
@end defun
|
|
|
|
@defun set-process-buffer process buffer
|
|
This function sets the buffer associated with @var{process} to
|
|
@var{buffer}. If @var{buffer} is @code{nil}, the process becomes
|
|
associated with no buffer.
|
|
@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.
|
|
(Presently, 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.
|
|
|
|
@smallexample
|
|
@group
|
|
(get-buffer-process "*shell*")
|
|
@result{} #<process shell>
|
|
@end group
|
|
@end smallexample
|
|
|
|
Killing the process's buffer deletes the process, which kills the
|
|
subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
|
|
@end defun
|
|
|
|
@node Filter Functions
|
|
@subsection Process Filter Functions
|
|
@cindex filter function
|
|
@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.
|
|
|
|
A filter function must accept two arguments: the associated process and
|
|
a string, which is the output. The function is then free to do whatever it
|
|
chooses with the output.
|
|
|
|
A filter function 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 filters at random places in
|
|
the middle of other Lisp programs. You may explicitly cause Emacs to
|
|
wait, so that filter functions will run, by calling @code{sit-for} or
|
|
@code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output}
|
|
(@pxref{Accepting Output}). Emacs is also waiting when the command loop
|
|
is reading input.
|
|
|
|
Quitting is normally inhibited within a filter function---otherwise,
|
|
the effect of typing @kbd{C-g} at command level or to quit a user
|
|
command would be unpredictable. If you want to permit quitting inside a
|
|
filter function, bind @code{inhibit-quit} to @code{nil}.
|
|
@xref{Quitting}.
|
|
|
|
Many filter functions sometimes or always insert the text in the
|
|
process's buffer, mimicking the actions of Emacs when there is no
|
|
filter. Such filter functions need to use @code{set-buffer} in order to
|
|
be sure to insert in that buffer. To avoid setting the current buffer
|
|
semipermanently, these filter functions must use @code{unwind-protect}
|
|
to make sure to restore the previous current buffer. They should also
|
|
update the process marker, and in some cases update the value of point.
|
|
Here is how to do these things:
|
|
|
|
@smallexample
|
|
@group
|
|
(defun ordinary-insertion-filter (proc string)
|
|
(let ((old-buffer (current-buffer)))
|
|
(unwind-protect
|
|
(let (moving)
|
|
(set-buffer (process-buffer proc))
|
|
(setq moving (= (point) (process-mark proc)))
|
|
@end group
|
|
@group
|
|
(save-excursion
|
|
;; @r{Insert the text, moving the process-marker.}
|
|
(goto-char (process-mark proc))
|
|
(insert string)
|
|
(set-marker (process-mark proc) (point)))
|
|
(if moving (goto-char (process-mark proc))))
|
|
(set-buffer old-buffer))))
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The reason to use an explicit @code{unwind-protect} rather than letting
|
|
@code{save-excursion} restore the current buffer is so as to preserve
|
|
the change in point made by @code{goto-char}.
|
|
|
|
To make the filter force the process buffer to be visible whenever new
|
|
text arrives, insert the following line just before the
|
|
@code{unwind-protect}:
|
|
|
|
@smallexample
|
|
(display-buffer (process-buffer proc))
|
|
@end smallexample
|
|
|
|
To force point to move to the end of the new output no matter where
|
|
it was previously, eliminate the variable @code{moving} and call
|
|
@code{goto-char} unconditionally.
|
|
|
|
In earlier Emacs versions, every filter function that did regexp
|
|
searching or matching had to explicitly save and restore the match data.
|
|
Now Emacs does this automatically; filter functions never need to do it
|
|
explicitly. @xref{Match Data}.
|
|
|
|
A filter function that writes the output into the buffer of the
|
|
process should check whether the process is still alive. If it tries to
|
|
insert into a dead buffer, it will get an error. If the buffer is dead,
|
|
@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
|
|
|
|
The output to the function may come in chunks of any size. A program
|
|
that produces the same output twice in a row may send it as one batch
|
|
of 200 characters one time, and five batches of 40 characters the next.
|
|
|
|
@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.
|
|
@end defun
|
|
|
|
@defun process-filter process
|
|
This function returns the filter function of @var{process}, or @code{nil}
|
|
if it has none.
|
|
@end defun
|
|
|
|
Here is an example of use of a filter function:
|
|
|
|
@smallexample
|
|
@group
|
|
(defun keep-output (process output)
|
|
(setq kept (cons output kept)))
|
|
@result{} keep-output
|
|
@end group
|
|
@group
|
|
(setq kept nil)
|
|
@result{} nil
|
|
@end group
|
|
@group
|
|
(set-process-filter (get-process "shell") 'keep-output)
|
|
@result{} keep-output
|
|
@end group
|
|
@group
|
|
(process-send-string "shell" "ls ~/other\n")
|
|
@result{} nil
|
|
kept
|
|
@result{} ("lewis@@slug[8] % "
|
|
@end group
|
|
@group
|
|
"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
|
|
address.txt backup.psf kolstad.psf
|
|
backup.bib~ david.mss resume-Dec-86.mss~
|
|
backup.err david.psf resume-Dec.psf
|
|
backup.mss dland syllabus.mss
|
|
"
|
|
"#backups.mss# backup.mss~ kolstad.mss
|
|
")
|
|
@end group
|
|
@end 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:
|
|
|
|
@smallexample
|
|
@group
|
|
;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
|
|
;; @r{and make sure that buffer is shown in some window.}
|
|
(defun my-process-filter (proc str)
|
|
(let ((cur (selected-window))
|
|
(pop-up-windows t))
|
|
(pop-to-buffer my-shell-buffer)
|
|
@end group
|
|
@group
|
|
(goto-char (point-max))
|
|
(insert str)
|
|
(set-marker (process-mark proc) (point-max))
|
|
(select-window cur)))
|
|
@end group
|
|
@end smallexample
|
|
@end ignore
|
|
|
|
@node Accepting Output
|
|
@subsection Accepting Output from Processes
|
|
|
|
Output from asynchronous subprocesses normally arrives only while
|
|
Emacs is waiting for some sort of external event, such as elapsed time
|
|
or terminal input. Occasionally it is useful in a Lisp program to
|
|
explicitly permit output to arrive at a specific point, or even to wait
|
|
until output arrives from a process.
|
|
|
|
@defun accept-process-output &optional process seconds millisec
|
|
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}.
|
|
|
|
@c Emacs 19 feature
|
|
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
|
|
subprocess output.
|
|
|
|
Not all operating systems support waiting periods other than multiples
|
|
of a second; on those that do not, you get an error if you specify
|
|
nonzero @var{millisec}.
|
|
|
|
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
|
|
arrived.
|
|
@end defun
|
|
|
|
@node Sentinels
|
|
@section Sentinels: Detecting Process Status Changes
|
|
@cindex process sentinel
|
|
@cindex sentinel
|
|
|
|
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.
|
|
|
|
The string describing the event looks like one of the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{"finished\n"}.
|
|
|
|
@item
|
|
@code{"exited abnormally with code @var{exitcode}\n"}.
|
|
|
|
@item
|
|
@code{"@var{name-of-signal}\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}
|
|
(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
|
|
Output}). Emacs is also waiting when the command loop is reading input.
|
|
|
|
Quitting is normally inhibited within a sentinel---otherwise, the
|
|
effect of typing @kbd{C-g} at command level or to quit a user command
|
|
would be unpredictable. If you want to permit quitting inside a
|
|
sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}.
|
|
|
|
A sentinel that writes the output into the buffer of the process
|
|
should check whether the process is still alive. If it tries to insert
|
|
into a dead buffer, it will get an error. If the buffer is dead,
|
|
@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
|
|
|
|
In earlier Emacs versions, every sentinel that did regexp searching or
|
|
matching had to explicitly save and restore the match data. Now Emacs
|
|
does this automatically; sentinels never need to do it explicitly.
|
|
@xref{Match Data}.
|
|
|
|
@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.
|
|
|
|
@smallexample
|
|
@group
|
|
(defun msg-me (process event)
|
|
(princ
|
|
(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'
|
|
@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.
|
|
@end defun
|
|
|
|
@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
|
|
the time the sentinel or filter function was called, @code{nil} if it
|
|
was not.
|
|
@end defun
|
|
|
|
@node Transaction Queues
|
|
@section Transaction Queues
|
|
@cindex transaction queue
|
|
|
|
You can use a @dfn{transaction queue} for more convenient communication
|
|
with subprocesses using transactions. First use @code{tq-create} to
|
|
create a transaction queue communicating with a specified process. Then
|
|
you can call @code{tq-enqueue} to send a transaction.
|
|
|
|
@defun tq-create process
|
|
This function creates and returns a transaction queue communicating with
|
|
@var{process}. The argument @var{process} should be a subprocess
|
|
capable of sending and receiving streams of bytes. It may be a child
|
|
process, or it may be a TCP connection to a server, possibly on another
|
|
machine.
|
|
@end defun
|
|
|
|
@defun tq-enqueue queue question regexp closure fn
|
|
This function sends a transaction to queue @var{queue}. Specifying the
|
|
queue has the effect of specifying the subprocess to talk to.
|
|
|
|
The argument @var{question} is the outgoing message that starts the
|
|
transaction. The argument @var{fn} is the function to call when the
|
|
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 return value of @code{tq-enqueue} itself is not meaningful.
|
|
@end defun
|
|
|
|
@defun tq-close queue
|
|
Shut down transaction queue @var{queue}, waiting for all pending transactions
|
|
to complete, and then terminate the connection or child process.
|
|
@end defun
|
|
|
|
Transaction queues are implemented by means of a filter function.
|
|
@xref{Filter Functions}.
|
|
|
|
@node TCP
|
|
@section TCP
|
|
@cindex TCP
|
|
|
|
Emacs Lisp programs can open TCP connections to other processes on the
|
|
same machine or other machines. A network connection is handled by Lisp
|
|
much like a subprocess, and is represented by a process object.
|
|
However, the process you are communicating with is not a child of the
|
|
Emacs process, so you can't kill it or send it signals. All you can do
|
|
is send and receive data. @code{delete-process} closes the connection,
|
|
but does not kill the process at the other end; that process must decide
|
|
what to do about closure of the connection.
|
|
|
|
You can distinguish process objects representing network connections
|
|
from those representing subprocesses with the @code{process-status}
|
|
function. @xref{Process Information}.
|
|
|
|
@defun open-network-stream name buffer-or-name host service
|
|
This function opens a TCP connection for a service to a host. It
|
|
returns a process object to represent the connection.
|
|
|
|
The @var{name} argument specifies the name for the process object. It
|
|
is modified as necessary to make it unique.
|
|
|
|
The @var{buffer-or-name} 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
|
|
@var{buffer-or-name} is @code{nil}, it means that the connection is not
|
|
associated with any buffer.
|
|
|
|
The arguments @var{host} and @var{service} specify where to connect to;
|
|
@var{host} is the host name (a string), and @var{service} is the name of
|
|
a defined network service (a string) or a port number (an integer).
|
|
@end defun
|