mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-22 10:26:20 +00:00
2002 lines
78 KiB
Plaintext
2002 lines
78 KiB
Plaintext
@c -*-texinfo-*-
|
|
@c This is part of the GNU Emacs Lisp Reference Manual.
|
|
@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
|
|
@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.
|
|
* Shell Arguments:: Quoting an argument to pass it to a shell.
|
|
* Synchronous Processes:: Details of using synchronous subprocesses.
|
|
* 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.
|
|
* Query Before Exit:: Whether to query if exiting will kill a process.
|
|
* Transaction Queues:: Transaction-based communication with subprocesses.
|
|
* Network:: Opening network connections.
|
|
* Network Servers:: Network servers let Emacs accept net connections.
|
|
* Datagrams::
|
|
* Low-Level Network:: Lower-level but more general function
|
|
to create connections and servers.
|
|
@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 the 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}).
|
|
|
|
Executing a program can also try adding suffixes to the specified
|
|
name:
|
|
|
|
@defvar 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
|
|
|
|
Each of the subprocess-creating functions has a @var{buffer-or-name}
|
|
argument which 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
|
|
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 have no special meanings in these
|
|
strings, since the whole strings 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 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
|
|
to invoke. The program @code{movemail} is an example of such a program;
|
|
Rmail uses it to fetch new mail from an inbox.
|
|
@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 Shell Arguments
|
|
@section Shell Arguments
|
|
|
|
Lisp programs sometimes need to run a shell and give it a command
|
|
that contains file names that were specified by the user. These
|
|
programs ought to be able to support any valid file name. But the shell
|
|
gives special treatment to certain characters, and if these characters
|
|
occur in the file name, they will confuse the shell. To handle these
|
|
characters, use the function @code{shell-quote-argument}:
|
|
|
|
@defun shell-quote-argument argument
|
|
This function returns a string which represents, in shell syntax,
|
|
an argument whose actual contents are @var{argument}. It should
|
|
work reliably to concatenate the return value into a shell command
|
|
and then pass it to a shell for execution.
|
|
|
|
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.
|
|
|
|
@example
|
|
;; @r{This example shows the behavior on GNU and Unix systems.}
|
|
(shell-quote-argument "foo > bar")
|
|
@result{} "foo\\ \\>\\ bar"
|
|
|
|
;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.}
|
|
(shell-quote-argument "foo > bar")
|
|
@result{} "\"foo > bar\""
|
|
@end example
|
|
|
|
Here's an example of using @code{shell-quote-argument} to construct
|
|
a shell command:
|
|
|
|
@example
|
|
(concat "diff -c "
|
|
(shell-quote-argument oldfile)
|
|
" "
|
|
(shell-quote-argument newfile))
|
|
@end example
|
|
@end defun
|
|
|
|
@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 on GNU or
|
|
Unix@footnote{On other systems, Emacs uses a Lisp emulation of
|
|
@code{ls}; see @ref{Contents of Directories}.} 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 (except on MS-DOS, where killing
|
|
other processes doesn't work). @xref{Quitting}.
|
|
|
|
The synchronous subprocess functions return an indication of how the
|
|
process terminated.
|
|
|
|
The output from a synchronous subprocess is generally decoded using a
|
|
coding system, much like text read from a file. The input sent to a
|
|
subprocess by @code{call-process-region} is encoded using a coding
|
|
system, much like text written into a file. @xref{Coding Systems}.
|
|
|
|
@defun call-process program &optional infile destination 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 the null device otherwise.
|
|
The argument @var{destination} says where to put the process output.
|
|
Here are the possibilities:
|
|
|
|
@table @asis
|
|
@item a buffer
|
|
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
|
|
Insert the output in a buffer with that name, before point.
|
|
|
|
@item @code{t}
|
|
Insert the output in the current buffer, before point.
|
|
|
|
@item @code{nil}
|
|
Discard the output.
|
|
|
|
@item 0
|
|
Discard the output, and return @code{nil} immediately without waiting
|
|
for the subprocess to finish.
|
|
|
|
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.
|
|
|
|
MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
|
|
work there.
|
|
|
|
@item @code{(@var{real-destination} @var{error-destination})}
|
|
Keep the standard output stream separate from the standard error stream;
|
|
deal with the ordinary output as specified by @var{real-destination},
|
|
and dispose of the error output according to @var{error-destination}.
|
|
If @var{error-destination} is @code{nil}, that means to discard the
|
|
error output, @code{t} means mix it with the ordinary output, and a
|
|
string specifies a file name to redirect error output into.
|
|
|
|
You can't directly specify a buffer to put the error output in; that is
|
|
too difficult to implement. But you can achieve this result by sending
|
|
the error output to a temporary file and then inserting the file into a
|
|
buffer.
|
|
@end table
|
|
|
|
If @var{display} is non-@code{nil}, then @code{call-process} redisplays
|
|
the buffer as output is inserted. (However, if the coding system chosen
|
|
for decoding output is @code{undecided}, meaning deduce the encoding
|
|
from the actual data, then redisplay sometimes cannot continue once
|
|
non-@acronym{ASCII} characters are encountered. There are fundamental
|
|
reasons why it is hard to fix this; see @ref{Output from Processes}.)
|
|
|
|
Otherwise the function @code{call-process} 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{} 0
|
|
|
|
---------- Buffer: foo ----------
|
|
/usr/user/lewis/manual
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
|
|
@group
|
|
(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
|
|
@result{} 0
|
|
|
|
---------- Buffer: bar ----------
|
|
lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
|
|
|
|
---------- Buffer: bar ----------
|
|
@end group
|
|
@end smallexample
|
|
|
|
Here is a good example of the use of @code{call-process}, which used to
|
|
be found in the definition of @code{insert-directory}:
|
|
|
|
@smallexample
|
|
@group
|
|
(call-process insert-directory-program nil t nil @var{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 destination display &rest args
|
|
This function sends the text from @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{destination} is @code{t}, to insert the output in the current
|
|
buffer in place of the input.
|
|
|
|
The arguments @var{destination} 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{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).
|
|
|
|
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{destination} 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{} 0
|
|
|
|
---------- 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
|
|
|
|
@defun call-process-shell-command command &optional infile destination display &rest args
|
|
This function executes the shell command @var{command} synchronously
|
|
in separate process. 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}.
|
|
@end defun
|
|
|
|
@defun shell-command-to-string command
|
|
This function executes @var{command} (a string) as a shell command,
|
|
then returns the command's output as a string.
|
|
@end defun
|
|
|
|
@node Asynchronous Processes
|
|
@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,
|
|
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.
|
|
|
|
@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 appending @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. The variable @code{shell-file-name} specifies which shell to
|
|
use.
|
|
|
|
The point of running a program through the shell, rather than directly
|
|
with @code{start-process}, is so that you can employ shell features such
|
|
as wildcards in the arguments. It follows that if you include an
|
|
arbitrary user-specified arguments in the command, you should quote it
|
|
with @code{shell-quote-argument} first, so that any special shell
|
|
characters do @emph{not} have their special shell meanings. @xref{Shell
|
|
Arguments}.
|
|
@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
|
|
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
|
|
@code{start-process}.
|
|
|
|
@smallexample
|
|
@group
|
|
(let ((process-connection-type nil)) ; @r{Use a pipe.}
|
|
(start-process @dots{}))
|
|
@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
|
|
Information}).
|
|
@end defvar
|
|
|
|
@node Deleting Processes
|
|
@section Deleting Processes
|
|
@cindex deleting processes
|
|
|
|
@dfn{Deleting a process} disconnects Emacs immediately from the
|
|
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
|
|
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 defopt
|
|
|
|
@defun delete-process name
|
|
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
|
|
(delete-process "*shell*")
|
|
@result{} nil
|
|
@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 &optional query-only
|
|
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}.
|
|
|
|
If @var{query-only} is non-@code{nil} then it lists only processes
|
|
whose query flag is non-@code{nil}. @xref{Query Before Exit}.
|
|
@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 @acronym{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
|
|
@acronym{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 connect
|
|
for a non-blocking connection that is waiting to complete.
|
|
@item failed
|
|
for a non-blocking connection that has failed to complete.
|
|
@item listen
|
|
for a network server that is listening.
|
|
@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}.
|
|
@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
|
|
|
|
@defun process-tty-name process
|
|
This function returns the terminal name that @var{process} is using for
|
|
its communication with Emacs---or @code{nil} if it is using pipes
|
|
instead of a terminal (see @code{process-connection-type} in
|
|
@ref{Asynchronous Processes}).
|
|
@end defun
|
|
|
|
@anchor{Coding systems for a subprocess}
|
|
@defun process-coding-system process
|
|
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:
|
|
|
|
@example
|
|
(@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
|
|
@end example
|
|
@end defun
|
|
|
|
@defun set-process-coding-system process decoding-system encoding-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
|
|
input.
|
|
@end defun
|
|
|
|
Every process also has a property list that you can use to store
|
|
miscellaneous values associated with the process.
|
|
|
|
@defun process-get process propname
|
|
This function returns the value of the @var{propname} property
|
|
of @var{process}.
|
|
@end defun
|
|
|
|
@defun process-put process propname value
|
|
This function sets the value of the @var{propname} property
|
|
of @var{process} to @var{value}.
|
|
@end defun
|
|
|
|
@defun process-plist process
|
|
This function returns the process plist of @var{process}.
|
|
@end defun
|
|
|
|
@defun set-process-plist process plist
|
|
This function sets the process plist of @var{process} to @var{plist}.
|
|
@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
|
|
@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.
|
|
|
|
Subprocess input is normally encoded using a coding system before the
|
|
subprocess receives it, much like text written into a file. You can use
|
|
@code{set-process-coding-system} to specify which coding system to use
|
|
(@pxref{Process Information}). Otherwise, the coding system comes from
|
|
@code{coding-system-for-write}, if that is non-@code{nil}; or else from
|
|
the defaulting mechanism (@pxref{Default Coding Systems}).
|
|
|
|
Sometimes the system is unable to accept input for that process,
|
|
because the input buffer is full. When this happens, the send functions
|
|
wait a short while, accepting output from subprocesses, and then try
|
|
again. This gives the subprocess a chance to read more of its pending
|
|
input and make space in the buffer. It also allows filters, sentinels
|
|
and timers to run---so take account of that in writing your code.
|
|
|
|
@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
|
|
|
|
@defun 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 defun
|
|
|
|
@defun process-send-eof &optional process-name
|
|
This function makes @var{process-name} see an end-of-file in its
|
|
input. The @acronym{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 @acronym{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
|
|
|
|
@defun process-running-child-p process
|
|
@tindex process-running-child-p process
|
|
This function will tell you whether a subprocess has given control of
|
|
its terminal to its own child process. The value is @code{t} if this is
|
|
true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
|
|
that this is not so.
|
|
@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.
|
|
|
|
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
|
|
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 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.
|
|
|
|
You can specify the target process by its process @acronym{ID}; that allows
|
|
you to send signals to processes that are not children of Emacs.
|
|
@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.
|
|
|
|
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
|
|
Output}). This minimizes the problem of timing errors that usually
|
|
plague parallel programming. For example, you can safely create a
|
|
process and only then specify its buffer or filter function; no output
|
|
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.
|
|
|
|
@menu
|
|
* Process Buffers:: If no filter, 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.
|
|
@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 separates 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 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
|
|
(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.
|
|
|
|
The filter function can only be called when Emacs is waiting for
|
|
something, because process output arrives only at such times. Emacs
|
|
waits when reading terminal input, in @code{sit-for} and
|
|
@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
|
|
(@pxref{Accepting Output}).
|
|
|
|
A filter function must accept two arguments: the associated process
|
|
and a string, which is output just received from it. The function is
|
|
then free to do whatever it chooses with the output.
|
|
|
|
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}.
|
|
|
|
If an error happens during execution of a filter function, it is
|
|
caught automatically, so that it doesn't stop the execution of whatever
|
|
program was running when the filter function was started. However, if
|
|
@code{debug-on-error} is non-@code{nil}, the error-catching is turned
|
|
off. This makes it possible to use the Lisp debugger to debug the
|
|
filter function. @xref{Debugger}.
|
|
|
|
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 save and restore the
|
|
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)
|
|
(with-current-buffer (process-buffer proc)
|
|
(let ((moving (= (point) (process-mark proc))))
|
|
@end group
|
|
@group
|
|
(save-excursion
|
|
;; @r{Insert the text, advancing the process marker.}
|
|
(goto-char (process-mark proc))
|
|
(insert string)
|
|
(set-marker (process-mark proc) (point)))
|
|
(if moving (goto-char (process-mark proc))))))
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The reason to use @code{with-current-buffer}, rather than using
|
|
@code{save-excursion} to save and restore the current buffer, is so as
|
|
to preserve the change in point made by the second call to
|
|
@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{with-current-buffer} construct:
|
|
|
|
@smallexample
|
|
(display-buffer (process-buffer proc))
|
|
@end smallexample
|
|
|
|
To force point 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 regular
|
|
expression searching or matching had to explicitly save and restore the
|
|
match data. Now Emacs does this automatically for filter functions;
|
|
they 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 buffer is still alive. If it tries to
|
|
insert into a dead buffer, it will get an error. The expression
|
|
@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
|
|
if the buffer is dead.
|
|
|
|
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. If
|
|
the filter looks for certain text strings in the subprocess output, make
|
|
sure to handle the case where one of these strings is split across two
|
|
or more batches of output.
|
|
|
|
@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 Decoding Output
|
|
@subsection Decoding Process Output
|
|
|
|
When Emacs writes process output directly into a multibyte buffer,
|
|
it decodes the output according to the process output coding system.
|
|
If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
|
|
converts the unibyte output to multibyte using
|
|
@code{string-to-multibyte}, inserts the resulting multibyte text.
|
|
|
|
You can use @code{set-process-coding-system} to specify which coding
|
|
system to use (@pxref{Process Information}). Otherwise, the coding
|
|
system comes from @code{coding-system-for-read}, if that is
|
|
non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
|
|
Coding Systems}).
|
|
|
|
@strong{Warning:} Coding systems such as @code{undecided} which
|
|
determine the coding system from the data do not work entirely
|
|
reliably with asynchronous subprocess output. This is because Emacs
|
|
has to process asynchronous subprocess output in batches, as it
|
|
arrives. Emacs must try to detect the proper coding system from one
|
|
batch at a time, and this does not always work. Therefore, if at all
|
|
possible, specify a coding system that determines both the character
|
|
code conversion and the end of line conversion---that is, one like
|
|
@code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
|
|
|
|
@cindex filter multibyte flag, of process
|
|
@cindex process filter multibyte flag
|
|
When Emacs calls a process filter function, it provides the process
|
|
output as a multibyte string or as a unibyte string according to the
|
|
process's filter multibyte flag. If the flag is non-@code{nil}, Emacs
|
|
decodes the output according to the process output coding system to
|
|
produce a multibyte string, and passes that to the process. If the
|
|
flag is @code{nil}, Emacs puts the output into a unibyte string, with
|
|
no decoding, and passes that.
|
|
|
|
When you create a process, the filter multibyte flag takes its
|
|
initial value from @code{default-enable-multibyte-characters}. If you
|
|
want to change the flag later on, use
|
|
@code{set-process-filter-multibyte}.
|
|
|
|
@defun set-process-filter-multibyte process multibyte
|
|
This function sets the filter multibyte flag of @var{process}
|
|
to @var{multibyte}.
|
|
@end defun
|
|
|
|
@defun process-filter-multibyte-p process
|
|
This function returns the filter multibyte flag of @var{process}.
|
|
@end defun
|
|
|
|
@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.
|
|
|
|
The argument @var{seconds} need not be an integer. If it is a floating
|
|
point number, this function waits for a fractional number of seconds.
|
|
Some systems support only a whole number of seconds; on these systems,
|
|
@var{seconds} is rounded down.
|
|
|
|
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 also allows sentinels to run when the command loop is
|
|
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
|
|
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 buffer 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}.
|
|
|
|
If an error happens during execution of a sentinel, it is caught
|
|
automatically, so that it doesn't stop the execution of whatever
|
|
programs was running when the sentinel was started. However, if
|
|
@code{debug-on-error} is non-@code{nil}, the error-catching is turned
|
|
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
|
|
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.
|
|
|
|
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)
|
|
(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 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
|
|
|
|
You can use a @dfn{transaction queue} to communicate with a subprocess
|
|
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
|
|
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
|
|
|
|
@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 Network
|
|
@section Network Connections
|
|
@cindex network connection
|
|
@cindex TCP
|
|
@cindex UDP
|
|
|
|
Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
|
|
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 it has no
|
|
process @acronym{ID}, and 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 program at the other end; that
|
|
program must decide what to do about closure of the connection.
|
|
|
|
Lisp programs can listen for connections by creating network
|
|
servers. A network server is also represented by a kind of process
|
|
object, but unlike a network connection, the network server never
|
|
transfers data itself. When it receives a connection request, it
|
|
creates a new network connection to represent the connection just
|
|
made. (The network connection inherits certain information, including
|
|
the process plist, from the server.) The network server then goes
|
|
back to listening for more connection requests.
|
|
|
|
Network connections and servers are created by calling
|
|
@code{make-network-process} with an argument list consisting of
|
|
keyword/argument pairs, for example @code{:server t} to create a
|
|
server process, or @code{:type 'datagram} to create a datagram
|
|
connection. @xref{Low-Level Network}, for details. You can also use
|
|
one of the @code{open-network-...} functions descibed below;
|
|
internally, they just call @code{make-network-process} with suitable
|
|
arguments.
|
|
|
|
You can distinguish process objects representing network connections
|
|
and servers from those representing subprocesses with the
|
|
@code{process-status} function. The possible status values for
|
|
network connections are @code{open}, @code{closed}, @code{connect},
|
|
and @code{failed}. For a network server, the status is always
|
|
@code{listen}. None of those values is possible for a real
|
|
subprocess. @xref{Process Information}.
|
|
|
|
You can stop and resume operation of a network processes by calling
|
|
@code{stop-process} and @code{continue-process}. For a server
|
|
process, being stopped means not accepting new connections. (Up to 5
|
|
connection requests will be queued for when you resume the server; you
|
|
can increase this limit, unless it is imposed by the operating
|
|
systems.) For a network stream connection, being stopped means not
|
|
processing input (any arriving input waits until you resume the
|
|
connection). For a datagram connection, some number of packets may be
|
|
queued but input may be lost. You can use the function
|
|
@code{process-command} to determine whether a network connection or
|
|
server is stopped; a non-@code{nil} value means yes.
|
|
|
|
@defun open-network-stream name buffer-or-name host service
|
|
This function opens a TCP connection, and returns a process object
|
|
that represents 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
|
|
|
|
@defun open-network-stream-nowait name buffer-or-name host service &optional sentinel filter
|
|
This function opens a TCP connection, like @code{open-network-stream},
|
|
but it returns immediately without waiting for the request to be
|
|
accepted or rejected by the remote server. When the request is
|
|
subsequently accepted or rejected, the process's sentinel function
|
|
will be called with a string that starts with @code{"open"} (on
|
|
success) or @code{"failed"} (on error).
|
|
|
|
Some systems do not support non-blocking connections; on those
|
|
systems, @code{open-network-stream-nowait} returns @code{nil}
|
|
and does nothing.
|
|
|
|
The optional arguments @var{sentinel} and @var{filter} specify the
|
|
sentinel and filter functions for this network connection. It is
|
|
useful to specify them when opening the connection, because they will
|
|
be used later asynchronously. The other arguments mean the same as in
|
|
@code{open-network-stream}.
|
|
@end defun
|
|
|
|
@defun process-contact process &optional key
|
|
This function returns information about how a network process was set
|
|
up. For a connection, when @var{key} is @code{nil}, it returns
|
|
@code{(@var{hostname} @var{service})} which specifies what you
|
|
connected to.
|
|
|
|
If @var{key} is @code{t}, the value is the complete status information
|
|
for the connection or server; that is, the list of keywords and values
|
|
specified in @code{make-network-process}, except that some of the
|
|
values represent the current status instead of what you specified:
|
|
|
|
@table @code
|
|
@item :buffer
|
|
The associated value is the process buffer.
|
|
@item :filter
|
|
The associated value is the process filter function.
|
|
@item :sentinel
|
|
The associated value is the process sentinel function.
|
|
@item :remote
|
|
In a connection, this is the address in internal format of the remote peer.
|
|
@item :local
|
|
The local address, in internal format.
|
|
@item :service
|
|
In a server, if you specified @code{t} for @var{service},
|
|
this value is the actual port number.
|
|
@end table
|
|
|
|
@code{:local} and @code{:remote} are included even if they were not
|
|
specified explicitly in @code{make-network-process}.
|
|
|
|
If @var{key} is a keyword, the function returns the value corresponding
|
|
to that keyword.
|
|
|
|
For an ordinary child process, this function always returns @code{t}.
|
|
@end defun
|
|
|
|
@node Network Servers
|
|
@section Network Servers
|
|
|
|
You create a server by calling @code{make-network-process} with
|
|
@code{:server t}. The server will listen for connection requests from
|
|
clients. When it accepts a client connection request, that creates a
|
|
new network connection, itself a process object, with the following
|
|
parameters:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The connection's process name is constructed by concatenating the
|
|
server process' @var{name} with a client identification string. The
|
|
client identification string for an IPv4 connection looks like
|
|
@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a
|
|
unique number in brackets, as in @samp{<@var{nnn}>}. The number
|
|
is unique for each connection in the Emacs session.
|
|
|
|
@item
|
|
If the server's filter is non-@code{nil}, 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.
|
|
|
|
The server's process buffer value is never used directly by Emacs, but
|
|
it is passed to the log function, which can log connections by
|
|
inserting text there.
|
|
|
|
@item
|
|
The communication type and the process filter and sentinel are
|
|
inherited from those of the server. The server never directly
|
|
uses its filter and sentinel; their sole purpose is to initialize
|
|
connections made to the server.
|
|
|
|
@item
|
|
The connection's process contact info is set according to the client's
|
|
addressing information (typically an IP address and a port number).
|
|
This information is associated with the @code{process-contact}
|
|
keywords @code{:host}, @code{:service}, @code{:remote}.
|
|
|
|
@item
|
|
The connection's local address is set up according to the port
|
|
number used for the connection.
|
|
|
|
@item
|
|
The client process' plist is initialized from the server's plist.
|
|
@end itemize
|
|
|
|
@defun open-network-stream-server name buffer-or-name service &optional sentinel filter
|
|
Create a network server process for a TCP service.
|
|
It returns nil if server processes are not supported; otherwise,
|
|
it returns a subprocess-object to represent the server.
|
|
|
|
When a client connects to the specified service, Emacs creates a new
|
|
subprocess to handle the new connection, and then calls its sentinel
|
|
function (which it has inherited from the server).
|
|
|
|
The optional arguments @var{sentinel} and @var{filter} specify the
|
|
sentinel and filter functions for the server. It is useful to specify
|
|
them now, because they will be used later asynchronously when the
|
|
server receives a connection request. The three arguments @var{name},
|
|
@var{buffer-or-name} and @var{service} mean the same thing as in
|
|
@code{open-network-stream}, but @var{service} can be @code{t}
|
|
meaning ask the system to allocate an unused port to listen on.
|
|
@end defun
|
|
|
|
@node Datagrams
|
|
@section Datagrams
|
|
@cindex datagrams
|
|
|
|
A datagram connection communicates with individual packets
|
|
rather than streams of data. Each call to @code{process-send}
|
|
sends one datagram packet, and each datagram received results
|
|
in one call to the filter function.
|
|
|
|
The datagram connection doesn't have to talk with the same remote
|
|
peer all the time. It has a @dfn{remote peer address} which specifies
|
|
where to send datagrams to. Each time an incoming datagram is passed
|
|
to the filter function, the peer address is set to the address that
|
|
datagram came from; that way, if the filter function sends a datagram,
|
|
it will go back to that place. You can specify the remote peer
|
|
address when you create the datagram connection using the
|
|
@code{:remote} keyword. You can change it later on by calling
|
|
@code{set-process-datagram-address}.
|
|
|
|
@defun process-datagram-address process
|
|
If @var{process} is a datagram connection or server, this function
|
|
returns its remote peer address.
|
|
@end defun
|
|
|
|
@defun set-process-datagram-address process address
|
|
If @var{process} is a datagram connection or server, this function
|
|
sets its remote peer address to @var{address}.
|
|
@end defun
|
|
|
|
@node Low-Level Network
|
|
@section Low-Level Network Access
|
|
|
|
The basic function for creating network connections and network
|
|
servers is @code{make-network-process}. It can do either of those
|
|
jobs, depending on the arguments you give it.
|
|
|
|
@defun make-network-process &rest args
|
|
This function creates a network connection or server and returns the
|
|
process object that represents it. 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}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here
|
|
are the meaningful keywords:
|
|
|
|
@table @asis
|
|
@item :name name
|
|
Use the string @var{name} as the process name. It is modified if
|
|
necessary to make it unique.
|
|
|
|
@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. Both connections and servers can be of either type.
|
|
|
|
@item :server @var{server-flag}
|
|
If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
|
|
create a connection. For a stream type server, @var{server-flag} may
|
|
be an integer which then specifies the length of the queue of pending
|
|
connections to the server. The default queue length is 5.
|
|
|
|
@item :host @var{host}
|
|
Specify the host to connect to. @var{host} should be a host name or
|
|
internet address, as a string, or the symbol @code{local} to specify
|
|
the local host. If you specify @var{host} for a server, it must
|
|
specify a valid address for the local host, and only clients
|
|
connecting to that address will be accepted.
|
|
|
|
@item :service @var{service}
|
|
@var{service} specifies a port number to connect to, or, for a server,
|
|
the port number to listen on. It should be a service name that
|
|
translates to a port number, or an integer specifying the port number
|
|
directly. For a server, it can also be @code{t}, which means to let
|
|
the system select an unused port number.
|
|
|
|
@item :family @var{family}
|
|
@var{family} specifies the address (and protocol) family for
|
|
communication. @code{nil} stands for IPv4. @code{local} specifies a
|
|
Unix socket, in which case @var{host} is ignored.
|
|
|
|
@item :local @var{local-address}
|
|
For a server process, @var{local-address} is the address to listen on.
|
|
It overrides @var{family}, @var{host} and @var{service}, and you
|
|
may as well not specify them.
|
|
|
|
@item :remote @var{remote-address}
|
|
For a connection, @var{remote-address} is the address to connect to.
|
|
It overrides @var{family}, @var{host} and @var{service}, and you
|
|
may as well not specify them.
|
|
|
|
For a datagram server, @var{remote-address} specifies the initial
|
|
setting of the remote datagram address.
|
|
|
|
The format of @var{local-address} or @var{remote-address} depends on
|
|
the address family:
|
|
|
|
@itemize -
|
|
@item
|
|
An IPv4 address is represented as a vector of integers @code{[@var{a}
|
|
@var{b} @var{c} @var{d} @var{p}]} corresponding to numeric IP address
|
|
@var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
|
|
|
|
@item
|
|
A local address is represented as a string which specifies the address
|
|
in the local address space.
|
|
|
|
@item
|
|
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 with one
|
|
element per address data byte. Do not rely on this format in portable
|
|
code, as it may depend on implementation defined constants, data
|
|
sizes, and data structure alignment.
|
|
@end itemize
|
|
|
|
@item :nowait @var{bool}
|
|
If @var{bool} is non-@code{nil} for a stream connection, return
|
|
without waiting for the connection to complete. When the connection
|
|
succeeds or fails, Emacs will call the sentinel function, with a
|
|
second argument matching @code{"open"} (if successful) or
|
|
@code{"failed"}. The default is to block, so that
|
|
@code{make-network-process} does not return until the connection
|
|
has succeeded or failed.
|
|
|
|
@item :stop @var{stopped}
|
|
Start the network connection or server in the `stopped' state if
|
|
@var{stopped} is non-@code{nil}.
|
|
|
|
@item :buffer @var{buffer}
|
|
Use @var{buffer} as the process buffer.
|
|
|
|
@item :coding @var{coding}
|
|
Use @var{coding} as the coding system for this process. To specify
|
|
different coding systems for decoding data from the connection and for
|
|
encoding data sent to it, specify @code{(@var{decoding} .
|
|
@var{encoding})} for @var{coding}.
|
|
|
|
If you don't specify this keyword at all, the default
|
|
is to determine the coding systems from the data.
|
|
|
|
@item :noquery @var{query-flag}
|
|
Initialize the process query flag to @var{query-flag}. @xref{Query Before Exit}.
|
|
|
|
@item :filter @var{filter}
|
|
Initialize the process filter to @var{filter}.
|
|
|
|
@item :filter-multibyte @var{bool}
|
|
If @var{bool} is non-@code{nil}, strings given to the process filter
|
|
are multibyte, otherwise they are unibyte. If you don't specify this
|
|
keyword at all, the default is that the strings are multibyte if
|
|
@code{default-enable-multibyte-characters} is non-@code{nil}.
|
|
|
|
@item :sentinel @var{sentinel}
|
|
Initialize the process sentinel to @var{sentinel}.
|
|
|
|
@item :log @var{log}
|
|
Initialize the log function of a server process to @var{log}. The log
|
|
function is called each time the server accepts a network connection
|
|
from a client. The arguments passed to the log function are
|
|
@var{server}, @var{connection}, and @var{message}, where @var{server}
|
|
is the server process, @var{connection} is the new process for the
|
|
connection, and @var{message} is a string describing what has
|
|
happened.
|
|
|
|
@item :plist @var{plist}
|
|
Initialize the process plist to @var{plist}.
|
|
@end table
|
|
|
|
The following network options can be specified for the network
|
|
process. Except for @code{:reuseaddr}, you can set or modify these
|
|
options later using @code{set-network-process-option}.
|
|
|
|
For a server process, the options specified with
|
|
@code{make-network-process} are not inherited by the client
|
|
connections, so you will need to set the necessary options for each
|
|
child connection as they are created.
|
|
|
|
@table @asis
|
|
@item :bindtodevice @var{device-name}
|
|
If @var{device-name} is a non-empty string identifying a network
|
|
interface name (see @code{network-interface-list}), only handle
|
|
packets received on that interface. If @var{device-name} is nil (the
|
|
default), handle packets received on any interface.
|
|
|
|
Using this option may require special privileges on some systems.
|
|
|
|
@item :broadcast @var{broadcast-flag}
|
|
If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
|
|
process will receive datagram packet sent to a broadcast address, and
|
|
be able to send packets to a broadcast address. Ignored for a stream
|
|
connection.
|
|
|
|
@item :dontroute @var{dontroute-flag}
|
|
If @var{dontroute-flag} is non-@code{nil}, the process can only send
|
|
to hosts on the same network as the local host.
|
|
|
|
@item :keepalive @var{keepalive-flag}
|
|
If @var{keepalive-flag} is non-@code{nil} for a stream connection,
|
|
enable exchange of low-level keep-alive messages.
|
|
|
|
@item :linger @var{linger-arg}
|
|
If @var{linger-arg} is non-@code{nil}, wait for successful
|
|
transmission of all queued packets on the connection before it is
|
|
deleted (see @code{delete-process}). If @var{linger-arg} is an
|
|
integer, it specifies the maximum time in seconds to wait for queued
|
|
packets to be sent before closing the connection. Default is
|
|
@code{nil} which means to discard unsent queued packets when the
|
|
process is deleted.
|
|
|
|
@item :oobinline @var{oobinline-flag}
|
|
If @var{oobinline-flag} is non-@code{nil} for a stream connection,
|
|
receive out-of-band data in the normal data stream. Otherwise, ignore
|
|
out-of-band data.
|
|
|
|
@item :priority @var{priority}
|
|
Set the priority for packets sent on this connection to the integer
|
|
@var{priority}. The interpretation of this number is protocol
|
|
specific, such as setting the TOS (type of service) field on IP
|
|
packets sent on this connection. It may also have system dependent
|
|
effects, such as selecting a specific output queue on the network
|
|
interface.
|
|
|
|
@item :reuseaddr @var{reuseaddr-flag}
|
|
If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
|
|
server process, allow this server to reuse a specific port number (see
|
|
@code{:service}) unless another process on this host is already
|
|
listening on that port. If @var{reuseaddr-flag} is @code{nil}, there
|
|
may be a period of time after the last use of that port (by any
|
|
process on the host), where it is not possible to make a new server on
|
|
that port.
|
|
|
|
@end table
|
|
|
|
The original argument list, modified with the actual connection
|
|
information, is available via the `process-contact' function.
|
|
@end defun
|
|
|
|
@defun set-network-process-option process option value
|
|
This function sets or modifies a network option for network process
|
|
@var{process}. See @code{make-network-process} for details of options
|
|
@var{option} and their corresponding values @var{value}.
|
|
|
|
The current setting of an option is available via the
|
|
`process-contact' function.
|
|
@end defun
|
|
|
|
@defun network-interface-list
|
|
This function returns a list describing the network interfaces
|
|
of the machine you are using. The value is an alist whose
|
|
elements have the form @code{(@var{name} . @var{address})}.
|
|
@var{address} has the same form as the @var{local-address}
|
|
and @var{remote-address} arguments to @code{make-network-process}.
|
|
@end defun
|
|
|
|
@defun network-interface-info ifname
|
|
This function returns information about the network interface named
|
|
@var{ifname}. The value is a list of the form @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
|
|
|
|
@table @var
|
|
@item addr
|
|
The internet protocol address.
|
|
@item bcast
|
|
The broadcast address.
|
|
@item netmask
|
|
The network mask.
|
|
@item hwaddr
|
|
The layer 2 address (Ethernet MAC address, for instance).
|
|
@item flags
|
|
The current flags of the interface.
|
|
@end table
|
|
@end defun
|
|
|
|
@defun format-network-address address &optional omit-port
|
|
This function converts the Lisp representation of a network address to
|
|
a string. For example, a five-element vector @code{[@var{a} @var{b}
|
|
@var{c} @var{d} @var{p}]} represents an IP address
|
|
@var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
|
|
@code{format-network-address} converts that to the string
|
|
@code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
|
|
|
|
If @var{omit-port} is non-@code{nil}, the value does not include
|
|
the port number.
|
|
@end defun
|
|
|
|
To test for the availability of a given network feature, use
|
|
@code{featurep} like this:
|
|
|
|
@example
|
|
(featurep 'make-network-process '(@var{keyword} @var{value}))
|
|
@end example
|
|
|
|
@noindent
|
|
The result of the first form is @code{t} if it works to specify
|
|
@var{keyword} with value @var{value} in @code{make-network-process}.
|
|
The result of the second form is @code{t} if @var{keyword} is
|
|
supported by @code{make-network-process}. Here are some of the
|
|
@var{keyword}---@var{value} pairs you can test in
|
|
this way.
|
|
|
|
@table @code
|
|
@item (:nowait t)
|
|
Non-@code{nil} if non-blocking connect is supported.
|
|
@item (:type datagram)
|
|
Non-@code{nil} if datagrams are supported.
|
|
@item (:family local)
|
|
Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported.
|
|
@item (:service t)
|
|
Non-@code{nil} if the system can select the port for a server.
|
|
@end table
|
|
|
|
To test for the availability of a given network option, use
|
|
@code{featurep} like this:
|
|
|
|
@example
|
|
(featurep 'make-network-process '@var{keyword})
|
|
@end example
|
|
|
|
Here are some of the option @var{keyword}s you can test in
|
|
this way.
|
|
|
|
@table @code
|
|
@item :bindtodevice
|
|
@itemx :broadcast
|
|
@itemx :dontroute
|
|
@itemx :keepalive
|
|
@itemx :linger
|
|
@itemx :oobinline
|
|
@itemx :priority
|
|
@itemx :reuseaddr
|
|
That particular network option is supported by
|
|
@code{make-network-process} and @code{set-network-process-option}.
|
|
@end table
|
|
|
|
@ignore
|
|
arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
|
|
@end ignore
|
|
|