annotate lispref/processes.texi @ 53583:45ae41a57a36

*** empty log message ***
author Stefan Monnier <monnier@iro.umontreal.ca>
date Wed, 14 Jan 2004 14:40:24 +0000
parents 5408fe43d709
children 8cc16a7bf4ce
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
27189
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
4 @c Free Software Foundation, Inc.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/processes
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
7 @node Processes, Display, Abbrevs, Top
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex child process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 @cindex parent process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 @cindex subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 @cindex process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 In the terminology of operating systems, a @dfn{process} is a space in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 which a program can execute. Emacs runs in a process. Emacs Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 programs can invoke other programs in processes of their own. These are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 called @dfn{subprocesses} or @dfn{child processes} of the Emacs process,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 which is their @dfn{parent process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 depending on how it is created. When you create a synchronous
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 subprocess, the Lisp program waits for the subprocess to terminate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 before continuing execution. When you create an asynchronous
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 subprocess, it can run in parallel with the Lisp program. This kind of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 subprocess is represented within Emacs by a Lisp object which is also
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 called a ``process''. Lisp programs can use this object to communicate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 with the subprocess or to control it. For example, you can send
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 signals, obtain status information, receive output from the process, or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 send input to it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 @defun processp object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 This function returns @code{t} if @var{object} is a process,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 @code{nil} otherwise.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 * Subprocess Creation:: Functions that start subprocesses.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
38 * Shell Arguments:: Quoting an argument to pass it to a shell.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 * Synchronous Processes:: Details of using synchronous subprocesses.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 * Asynchronous Processes:: Starting up an asynchronous subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 * Deleting Processes:: Eliminating an asynchronous subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 * Process Information:: Accessing run-status and other attributes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 * Input to Processes:: Sending input to an asynchronous subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 * Signals to Processes:: Stopping, continuing or interrupting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 an asynchronous subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 * Output from Processes:: Collecting output from an asynchronous subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 * Sentinels:: Sentinels run when process run-status changes.
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
48 * Query Before Exit:: Whether to query if exiting will kill a process.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 * Transaction Queues:: Transaction-based communication with subprocesses.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
50 * Network:: Opening network connections.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
51 * Network Servers:: Network servers let Emacs accept net connections.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
52 * Datagrams::
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
53 * Low-Level Network:: Lower-level but more general function
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
54 to create connections and servers.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 @node Subprocess Creation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 @section Functions that Create Subprocesses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 There are three functions that create a new subprocess in which to run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 a program. One of them, @code{start-process}, creates an asynchronous
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 process and returns a process object (@pxref{Asynchronous Processes}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 The other two, @code{call-process} and @code{call-process-region},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 create a synchronous process and do not return a process object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 (@pxref{Synchronous Processes}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
67 Synchronous and asynchronous processes are explained in the following
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 sections. Since the three functions are all called in a similar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 fashion, their common arguments are described here.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 @cindex execute program
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 @cindex @code{PATH} environment variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 @cindex @code{HOME} environment variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 In all cases, the function's @var{program} argument specifies the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 program to be run. An error is signaled if the file is not found or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 cannot be executed. If the file name is relative, the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 @code{exec-path} contains a list of directories to search. Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 initializes @code{exec-path} when it starts up, based on the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 the environment variable @code{PATH}. The standard file name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81 in @code{exec-path}, but environment variable substitutions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 (@samp{$HOME}, etc.) are not recognized; use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 @code{substitute-in-file-name} to perform them (@pxref{File Name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 Expansion}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85
51922
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
86 Executing a program can also try adding suffixes to the specified
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
87 name:
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
88
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
89 @defvar exec-suffixes
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
90 This variable is a list of suffixes (strings) to try adding to the
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
91 specified program file name. The list should include @code{""} if you
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
92 want the name to be tried exactly as specified. The default value is
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
93 system-dependent.
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
94 @end defvar
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
95
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 Each of the subprocess-creating functions has a @var{buffer-or-name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 argument which specifies where the standard output from the program will
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
98 go. It should be a buffer or a buffer name; if it is a buffer name,
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
99 that will create the buffer if it does not already exist. It can also
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
100 be @code{nil}, which says to discard the output unless a filter function
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
101 handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
102 Normally, you should avoid having multiple processes send output to the
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
103 same buffer because their output would be intermixed randomly.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 @cindex program arguments
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 All three of the subprocess-creating functions have a @code{&rest}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 argument, @var{args}. The @var{args} must all be strings, and they are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 supplied to @var{program} as separate command line arguments. Wildcard
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
109 characters and other shell constructs have no special meanings in these
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
110 strings, since the whole strings are passed directly to the specified
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
111 program.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7411
diff changeset
113 @strong{Please note:} The argument @var{program} contains only the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 name of the program; it may not contain any command-line arguments. You
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 must use @var{args} to provide those.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 The subprocess gets its current directory from the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @code{default-directory} (@pxref{File Name Expansion}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 @cindex environment variables, subprocesses
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
121 The subprocess inherits its environment from Emacs, but you can
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 specify overrides for it with @code{process-environment}. @xref{System
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 Environment}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
125 @defvar exec-directory
17611
1b2afa6391ca (exec-directory): Wakeup no longer exists, so use movemail as example.
Richard M. Stallman <rms@gnu.org>
parents: 16664
diff changeset
126 @pindex movemail
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
127 The value of this variable is a string, the name of a directory that
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
128 contains programs that come with GNU Emacs, programs intended for Emacs
17611
1b2afa6391ca (exec-directory): Wakeup no longer exists, so use movemail as example.
Richard M. Stallman <rms@gnu.org>
parents: 16664
diff changeset
129 to invoke. The program @code{movemail} is an example of such a program;
1b2afa6391ca (exec-directory): Wakeup no longer exists, so use movemail as example.
Richard M. Stallman <rms@gnu.org>
parents: 16664
diff changeset
130 Rmail uses it to fetch new mail from an inbox.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @defopt exec-path
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 The value of this variable is a list of directories to search for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 programs to run in subprocesses. Each element is either the name of a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 directory (i.e., a string), or @code{nil}, which stands for the default
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 directory (which is the value of @code{default-directory}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 @cindex program directories
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 The value of @code{exec-path} is used by @code{call-process} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 @code{start-process} when the @var{program} argument is not an absolute
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 file name.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
145 @node Shell Arguments
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
146 @section Shell Arguments
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
147
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
148 Lisp programs sometimes need to run a shell and give it a command
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
149 that contains file names that were specified by the user. These
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
150 programs ought to be able to support any valid file name. But the shell
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
151 gives special treatment to certain characters, and if these characters
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
152 occur in the file name, they will confuse the shell. To handle these
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
153 characters, use the function @code{shell-quote-argument}:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
154
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
155 @defun shell-quote-argument argument
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
156 This function returns a string which represents, in shell syntax,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
157 an argument whose actual contents are @var{argument}. It should
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
158 work reliably to concatenate the return value into a shell command
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
159 and then pass it to a shell for execution.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
160
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
161 Precisely what this function does depends on your operating system. The
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
162 function is designed to work with the syntax of your system's standard
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
163 shell; if you use an unusual shell, you will need to redefine this
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
164 function.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
165
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
166 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
167 ;; @r{This example shows the behavior on GNU and Unix systems.}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
168 (shell-quote-argument "foo > bar")
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
169 @result{} "foo\\ \\>\\ bar"
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
170
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
171 ;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
172 (shell-quote-argument "foo > bar")
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
173 @result{} "\"foo > bar\""
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
174 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
175
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
176 Here's an example of using @code{shell-quote-argument} to construct
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
177 a shell command:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
178
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
179 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
180 (concat "diff -c "
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
181 (shell-quote-argument oldfile)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
182 " "
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
183 (shell-quote-argument newfile))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
184 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
185 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
186
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 @node Synchronous Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 @section Creating a Synchronous Process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 @cindex synchronous subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 After a @dfn{synchronous process} is created, Emacs waits for the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
192 process to terminate before continuing. Starting Dired on GNU or
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
193 Unix@footnote{On other systems, Emacs uses a Lisp emulation of
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
194 @code{ls}; see @ref{Contents of Directories}.} is an example of this: it
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
195 runs @code{ls} in a synchronous process, then modifies the output
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
196 slightly. Because the process is synchronous, the entire directory
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
197 listing arrives in the buffer before Emacs tries to do anything with it.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 While Emacs waits for the synchronous subprocess to terminate, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 the subprocess with a @code{SIGINT} signal; but it waits until the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 subprocess actually terminates before quitting. If during that time the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 user types another @kbd{C-g}, that kills the subprocess instantly with
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
204 @code{SIGKILL} and quits immediately (except on MS-DOS, where killing
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
205 other processes doesn't work). @xref{Quitting}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
207 The synchronous subprocess functions return an indication of how the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
208 process terminated.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
209
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
210 The output from a synchronous subprocess is generally decoded using a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
211 coding system, much like text read from a file. The input sent to a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
212 subprocess by @code{call-process-region} is encoded using a coding
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
213 system, much like text written into a file. @xref{Coding Systems}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
215 @defun call-process program &optional infile destination display &rest args
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 This function calls @var{program} in a separate process and waits for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 it to finish.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 The standard input for the process comes from file @var{infile} if
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
220 @var{infile} is not @code{nil}, and from the null device otherwise.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
221 The argument @var{destination} says where to put the process output.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
222 Here are the possibilities:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
223
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
224 @table @asis
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
225 @item a buffer
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
226 Insert the output in that buffer, before point. This includes both the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
227 standard output stream and the standard error stream of the process.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
228
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
229 @item a string
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
230 Insert the output in a buffer with that name, before point.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
231
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
232 @item @code{t}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
233 Insert the output in the current buffer, before point.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
234
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
235 @item @code{nil}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
236 Discard the output.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
238 @item 0
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
239 Discard the output, and return @code{nil} immediately without waiting
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
240 for the subprocess to finish.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
241
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
242 In this case, the process is not truly synchronous, since it can run in
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
243 parallel with Emacs; but you can think of it as synchronous in that
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
244 Emacs is essentially finished with the subprocess as soon as this
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
245 function returns.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
246
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
247 MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
248 work there.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
249
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
250 @item @code{(@var{real-destination} @var{error-destination})}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
251 Keep the standard output stream separate from the standard error stream;
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
252 deal with the ordinary output as specified by @var{real-destination},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
253 and dispose of the error output according to @var{error-destination}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
254 If @var{error-destination} is @code{nil}, that means to discard the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
255 error output, @code{t} means mix it with the ordinary output, and a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
256 string specifies a file name to redirect error output into.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
257
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
258 You can't directly specify a buffer to put the error output in; that is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
259 too difficult to implement. But you can achieve this result by sending
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
260 the error output to a temporary file and then inserting the file into a
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
261 buffer.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
262 @end table
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
265 the buffer as output is inserted. (However, if the coding system chosen
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
266 for decoding output is @code{undecided}, meaning deduce the encoding
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
267 from the actual data, then redisplay sometimes cannot continue once
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
268 non-@acronym{ASCII} characters are encountered. There are fundamental
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
269 reasons why it is hard to fix this; see @ref{Output from Processes}.)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
270
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
271 Otherwise the function @code{call-process} does no redisplay, and the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
272 results become visible on the screen only when Emacs redisplays that
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
273 buffer in the normal course of events.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 The remaining arguments, @var{args}, are strings that specify command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 line arguments for the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 The value returned by @code{call-process} (unless you told it not to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 wait) indicates the reason for process termination. A number gives the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 exit status of the subprocess; 0 means success, and any other value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 means failure. If the process terminated with a signal,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 @code{call-process} returns a string describing the signal.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 In the examples below, the buffer @samp{foo} is current.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 (call-process "pwd" nil t)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
289 @result{} 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 /usr/user/lewis/manual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
298 @result{} 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 ---------- Buffer: bar ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 ---------- Buffer: bar ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
307 Here is a good example of the use of @code{call-process}, which used to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
308 be found in the definition of @code{insert-directory}:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
312 (call-process insert-directory-program nil t nil @var{switches}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 (if full-directory-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 (concat (file-name-as-directory file) ".")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 file))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
320 @defun call-process-region start end program &optional delete destination display &rest args
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
321 This function sends the text from @var{start} to @var{end} as
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 standard input to a process running @var{program}. It deletes the text
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
323 sent if @var{delete} is non-@code{nil}; this is useful when
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
324 @var{destination} is @code{t}, to insert the output in the current
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
325 buffer in place of the input.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
327 The arguments @var{destination} and @var{display} control what to do
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 with the output from the subprocess, and whether to update the display
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 as it comes in. For details, see the description of
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
330 @code{call-process}, above. If @var{destination} is the integer 0,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 @code{call-process-region} discards the output and returns @code{nil}
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
332 immediately, without waiting for the subprocess to finish (this only
27370
70846ee19545 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
333 works if asynchronous subprocesses are supported).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 The remaining arguments, @var{args}, are strings that specify command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 line arguments for the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 The return value of @code{call-process-region} is just like that of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 @code{call-process}: @code{nil} if you told it to return without
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 waiting; otherwise, a number or string which indicates how the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 subprocess terminated.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 In the following example, we use @code{call-process-region} to run the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 @code{cat} utility, with standard input being the first five characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 standard input into its standard output. Since the argument
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
347 @var{destination} is @code{t}, this output is inserted in the current
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 input@point{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 (call-process-region 1 6 "cat" nil t)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
359 @result{} 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 inputinput@point{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 The @code{shell-command-on-region} command uses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 @code{call-process-region} like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
372 (call-process-region
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
373 start end
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 shell-file-name ; @r{Name of program.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 nil ; @r{Do not delete region.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 buffer ; @r{Send output to @code{buffer}.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 nil ; @r{No redisplay during output.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 "-c" command) ; @r{Arguments for the shell.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
383 @defun call-process-shell-command command &optional infile destination display &rest args
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
384 This function executes the shell command @var{command} synchronously
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
385 in separate process. The final arguments @var{args} are additional
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
386 arguments to add at the end of @var{command}. The other arguments
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
387 are handled as in @code{call-process}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
388 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
389
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
390 @defun shell-command-to-string command
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
391 This function executes @var{command} (a string) as a shell command,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
392 then returns the command's output as a string.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
393 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
394
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 @node Asynchronous Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 @section Creating an Asynchronous Process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 @cindex asynchronous subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
399 After an @dfn{asynchronous process} is created, Emacs and the subprocess
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
400 both continue running immediately. The process thereafter runs
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
401 in parallel with Emacs, and the two can communicate with each other
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
402 using the functions described in the following sections. However,
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
403 communication is only partially asynchronous: Emacs sends data to the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
404 process only when certain functions are called, and Emacs accepts data
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
405 from the process only when Emacs is waiting for input or for a time
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
406 delay.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
407
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
408 Here we describe how to create an asynchronous process.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 @defun start-process name buffer-or-name program &rest args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 This function creates a new asynchronous subprocess and starts the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 program @var{program} running in it. It returns a process object that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 stands for the new subprocess in Lisp. The argument @var{name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 specifies the name for the process object; if a process with this name
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
415 already exists, then @var{name} is modified (by appending @samp{<1>},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
416 etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 associate with the process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 The remaining arguments, @var{args}, are strings that specify command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 line arguments for the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 In the example below, the first process is started and runs (rather,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 sleeps) for 100 seconds. Meanwhile, the second process is started, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 given the name @samp{my-process<1>} for the sake of uniqueness. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 inserts the directory listing at the end of the buffer @samp{foo},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 before the first process finishes. Then it finishes, and a message to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 that effect is inserted in the buffer. Much later, the first process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 finishes, and another message is inserted in the buffer for it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 (start-process "my-process" "foo" "sleep" "100")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 @result{} #<process my-process>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 @result{} #<process my-process<1>>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 total 2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 Process my-process<1> finished
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 Process my-process finished
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 @defun start-process-shell-command name buffer-or-name command &rest command-args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 This function is like @code{start-process} except that it uses a shell
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 to execute the specified command. The argument @var{command} is a shell
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 command name, and @var{command-args} are the arguments for the shell
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
457 command. The variable @code{shell-file-name} specifies which shell to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
458 use.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
459
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
460 The point of running a program through the shell, rather than directly
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
461 with @code{start-process}, is so that you can employ shell features such
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
462 as wildcards in the arguments. It follows that if you include an
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
463 arbitrary user-specified arguments in the command, you should quote it
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
464 with @code{shell-quote-argument} first, so that any special shell
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
465 characters do @emph{not} have their special shell meanings. @xref{Shell
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
466 Arguments}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @defvar process-connection-type
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 @cindex pipes
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
471 @cindex @acronym{PTY}s
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 This variable controls the type of device used to communicate with
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
473 asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
474 used, when available. Otherwise, pipes are used.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
476 @acronym{PTY}s are usually preferable for processes visible to the user, as
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
478 etc.) to work between the process and its children, whereas pipes do
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
479 not. For subprocesses used for internal purposes by programs, it is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
480 often better to use a pipe, because they are more efficient. In
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
481 addition, the total number of @acronym{PTY}s is limited on many systems and
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
482 it is good not to waste them.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
484 The value of @code{process-connection-type} takes effect when
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 @code{start-process} is called. So you can specify how to communicate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 with one subprocess by binding the variable around the call to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 @code{start-process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 (let ((process-connection-type nil)) ; @r{Use a pipe.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 (start-process @dots{}))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 @end smallexample
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
495
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
496 To determine whether a given subprocess actually got a pipe or a
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
497 @acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
498 Information}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 @node Deleting Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 @section Deleting Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 @cindex deleting processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505 @dfn{Deleting a process} disconnects Emacs immediately from the
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
506 subprocess. Processes are deleted automatically after they terminate,
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
507 but not necessarily right away. You can delete a process explicitly
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
508 at any time. If you delete a terminated process explicitly before it
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
509 is deleted automatically, no harm results. Deletion of a running
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
510 process sends a signal to terminate it (and its child processes if
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
511 any), and calls the process sentinel if it has one.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
513 @code{get-buffer-process} and @code{process-list} do not remember a
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
514 deleted process, but the process object itself continues to exist as
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
515 long as other Lisp objects point to it. All the Lisp primitives that
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
516 work on process objects accept deleted processes, but those that do
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
517 I/O or send signals will report an error. The process mark continues
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
518 to point to the same place as before, usually into a buffer where
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
519 output from the process was being inserted.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
521 @defopt delete-exited-processes
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 This variable controls automatic deletion of processes that have
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 terminated (due to calling @code{exit} or to a signal). If it is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 @code{nil}, then they continue to exist until the user runs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 @code{list-processes}. Otherwise, they are deleted immediately after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 they exit.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
527 @end defopt
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 @defun delete-process name
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
530 This function deletes the process associated with @var{name}, killing
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
531 it with a @code{SIGKILL} signal. The argument @var{name} may be a
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
532 process, the name of a process, a buffer, or the name of a buffer.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
533 Calling @code{delete-process} on a running process terminates it,
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
534 updates the process status, and runs the sentinel (if any) immediately.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
535 If the process has already terminated, calling @code{delete-process}
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
536 has no effect on its status, or on the running of its sentinel (which
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
537 will happen sooner or later).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 (delete-process "*shell*")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @node Process Information
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 @section Process Information
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 Several functions return information about processes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 @code{list-processes} is provided for interactive use.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
553 @deffn Command list-processes &optional query-only
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 This command displays a listing of all living processes. In addition,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 it finally deletes any process whose status was @samp{Exited} or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 @samp{Signaled}. It returns @code{nil}.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
557
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
558 If @var{query-only} is non-@code{nil} then it lists only processes
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
559 whose query flag is non-@code{nil}. @xref{Query Before Exit}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 @defun process-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 This function returns a list of all processes that have not been deleted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 (process-list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 @result{} (#<process display-time> #<process shell>)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @defun get-process name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 This function returns the process named @var{name}, or @code{nil} if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 there is none. An error is signaled if @var{name} is not a string.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 (get-process "shell")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 @result{} #<process shell>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 @defun process-command process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 This function returns the command that was executed to start
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 @var{process}. This is a list of strings, the first string being the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 program executed and the rest of the strings being the arguments that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 were given to the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 (process-command (get-process "shell"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 @result{} ("/bin/csh" "-i")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
598
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599 @defun process-id process
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
600 This function returns the @acronym{PID} of @var{process}. This is an
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
601 integer that distinguishes the process @var{process} from all other
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 processes running on the same computer at the current time. The
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
603 @acronym{PID} of a process is chosen by the operating system kernel when the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 process is started and remains constant as long as the process exists.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607 @defun process-name process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 This function returns the name of @var{process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 @defun process-status process-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 This function returns the status of @var{process-name} as a symbol.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 The argument @var{process-name} must be a process, a buffer, a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 process name (string) or a buffer name (string).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 The possible values for an actual subprocess are:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 @item run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 for a process that is running.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 @item stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 for a process that is stopped but continuable.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623 @item exit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 for a process that has exited.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 @item signal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 for a process that has received a fatal signal.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @item open
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 for a network connection that is open.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 @item closed
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 for a network connection that is closed. Once a connection
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 is closed, you cannot reopen it, though you might be able to open
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 a new connection to the same place.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
633 @item connect
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
634 for a non-blocking connection that is waiting to complete.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
635 @item failed
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
636 for a non-blocking connection that has failed to complete.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
637 @item listen
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
638 for a network server that is listening.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 @item nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 if @var{process-name} is not the name of an existing process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 (process-status "shell")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 @result{} run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 (process-status (get-buffer "*shell*"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 @result{} run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @result{} #<process xx<1>>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 (process-status x)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656 @result{} exit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 For a network connection, @code{process-status} returns one of the symbols
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 @code{open} or @code{closed}. The latter means that the other side
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662 closed the connection, or Emacs did @code{delete-process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 @defun process-exit-status process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 This function returns the exit status of @var{process} or the signal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 number that killed it. (Use the result of @code{process-status} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 determine which of those it is.) If @var{process} has not yet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 terminated, the value is 0.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
672 @defun process-tty-name process
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
673 This function returns the terminal name that @var{process} is using for
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
674 its communication with Emacs---or @code{nil} if it is using pipes
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
675 instead of a terminal (see @code{process-connection-type} in
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
676 @ref{Asynchronous Processes}).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
677 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
678
53292
5408fe43d709 (Process Information): Add anchor.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
679 @anchor{Coding systems for a subprocess}
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
680 @defun process-coding-system process
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
681 This function returns a cons cell describing the coding systems in use
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
682 for decoding output from @var{process} and for encoding input to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
683 @var{process} (@pxref{Coding Systems}). The value has this form:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
684
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
685 @example
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
686 (@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
687 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
688 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
689
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
690 @defun set-process-coding-system process decoding-system encoding-system
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
691 This function specifies the coding systems to use for subsequent output
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
692 from and input to @var{process}. It will use @var{decoding-system} to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
693 decode subprocess output, and @var{encoding-system} to encode subprocess
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
694 input.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
695 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
696
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
697 Every process also has a property list that you can use to store
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
698 miscellaneous values associated with the process.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
699
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
700 @defun process-get process propname
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
701 This function returns the value of the @var{propname} property
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
702 of @var{process}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
703 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
704
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
705 @defun process-put process propname value
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
706 This function sets the value of the @var{propname} property
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
707 of @var{process} to @var{value}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
708 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
709
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
710 @defun process-plist process
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
711 This function returns the process plist of @var{process}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
712 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
713
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
714 @defun set-process-plist process plist
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
715 This function sets the process plist of @var{process} to @var{plist}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
716 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
717
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 @node Input to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 @section Sending Input to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 @cindex process input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 Asynchronous subprocesses receive input when it is sent to them by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 Emacs, which is done with the functions in this section. You must
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 specify the process to send input to, and the input data to send. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 data appears on the ``standard input'' of the subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 Some operating systems have limited space for buffered input in a
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
728 @acronym{PTY}. On these systems, Emacs sends an @acronym{EOF} periodically amidst
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 the other characters, to force them through. For most programs,
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
730 these @acronym{EOF}s do no harm.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
732 Subprocess input is normally encoded using a coding system before the
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
733 subprocess receives it, much like text written into a file. You can use
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
734 @code{set-process-coding-system} to specify which coding system to use
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
735 (@pxref{Process Information}). Otherwise, the coding system comes from
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
736 @code{coding-system-for-write}, if that is non-@code{nil}; or else from
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
737 the defaulting mechanism (@pxref{Default Coding Systems}).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
738
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
739 Sometimes the system is unable to accept input for that process,
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
740 because the input buffer is full. When this happens, the send functions
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
741 wait a short while, accepting output from subprocesses, and then try
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
742 again. This gives the subprocess a chance to read more of its pending
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
743 input and make space in the buffer. It also allows filters, sentinels
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
744 and timers to run---so take account of that in writing your code.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
745
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 @defun process-send-string process-name string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 This function sends @var{process-name} the contents of @var{string} as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 standard input. The argument @var{process-name} must be a process or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 the name of a process. If it is @code{nil}, the current buffer's
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 process is used.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 The function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 (process-send-string "shell<1>" "ls\n")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
760
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 ---------- Buffer: *shell* ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 ...
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 introduction.texi syntax-tables.texi~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 introduction.texi~ text.texi
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 introduction.txt text.texi~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 ...
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768 ---------- Buffer: *shell* ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
773 @defun process-send-region process-name start end
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774 This function sends the text in the region defined by @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775 @var{end} as standard input to @var{process-name}, which is a process or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776 a process name. (If it is @code{nil}, the current buffer's process is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 used.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779 An error is signaled unless both @var{start} and @var{end} are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780 integers or markers that indicate positions in the current buffer. (It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 is unimportant which number is larger.)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
782 @end defun
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 @defun process-send-eof &optional process-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 This function makes @var{process-name} see an end-of-file in its
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
786 input. The @acronym{EOF} comes after any text already sent to it.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 If @var{process-name} is not supplied, or if it is @code{nil}, then
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
789 this function sends the @acronym{EOF} to the current buffer's process. An
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 error is signaled if the current buffer has no process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 The function returns @var{process-name}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 (process-send-eof "shell")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 @result{} "shell"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
802 @defun process-running-child-p process
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
803 @tindex process-running-child-p process
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
804 This function will tell you whether a subprocess has given control of
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
805 its terminal to its own child process. The value is @code{t} if this is
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
806 true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
807 that this is not so.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
808 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
809
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 @node Signals to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 @section Sending Signals to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812 @cindex process signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 @cindex sending signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814 @cindex signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 @dfn{Sending a signal} to a subprocess is a way of interrupting its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 activities. There are several different signals, each with its own
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 meaning. The set of signals and their names is defined by the operating
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 system. For example, the signal @code{SIGINT} means that the user has
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 typed @kbd{C-c}, or that some analogous thing has happened.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 Each signal has a standard effect on the subprocess. Most signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823 kill the subprocess, but some stop or resume execution instead. Most
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 signals can optionally be handled by programs; if the program handles
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 the signal, then we can say nothing in general about its effects.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 You can send signals explicitly by calling the functions in this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 section. Emacs also sends signals automatically at certain times:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 killing a buffer sends a @code{SIGHUP} signal to all its associated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 processes. (@code{SIGHUP} is a signal that usually indicates that the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 user hung up the phone.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 Each of the signal-sending functions takes two optional arguments:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 @var{process-name} and @var{current-group}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 The argument @var{process-name} must be either a process, the name of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 one, or @code{nil}. If it is @code{nil}, the process defaults to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 process associated with the current buffer. An error is signaled if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 @var{process-name} does not identify a process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 The argument @var{current-group} is a flag that makes a difference
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 when you are running a job-control shell as an Emacs subprocess. If it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844 is non-@code{nil}, then the signal is sent to the current process-group
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
845 of the terminal that Emacs uses to communicate with the subprocess. If
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 the process is a job-control shell, this means the shell's current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 subjob. If it is @code{nil}, the signal is sent to the process group of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 the immediate subprocess of Emacs. If the subprocess is a job-control
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 shell, this is the shell itself.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 The flag @var{current-group} has no effect when a pipe is used to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 communicate with the subprocess, because the operating system does not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 support the distinction in the case of pipes. For the same reason,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 job-control shells won't work when a pipe is used. See
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 @code{process-connection-type} in @ref{Asynchronous Processes}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 @defun interrupt-process &optional process-name current-group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858 This function interrupts the process @var{process-name} by sending the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 others) sends this signal. When the argument @var{current-group} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 on the terminal by which Emacs talks to the subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866 @defun kill-process &optional process-name current-group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 This function kills the process @var{process-name} by sending the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 signal @code{SIGKILL}. This signal kills the subprocess immediately,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869 and cannot be handled by the subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872 @defun quit-process &optional process-name current-group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 This function sends the signal @code{SIGQUIT} to the process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874 @var{process-name}. This signal is the one sent by the ``quit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876 Emacs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
879 @defun stop-process &optional process-name current-group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
880 This function stops the process @var{process-name} by sending the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
881 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
882 execution.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
884 Outside of Emacs, on systems with job control, the ``stop character''
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
885 (usually @kbd{C-z}) normally sends this signal. When
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
886 @var{current-group} is non-@code{nil}, you can think of this function as
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
887 ``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
888 subprocess.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 @defun continue-process &optional process-name current-group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 This function resumes execution of the process @var{process} by sending
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893 it the signal @code{SIGCONT}. This presumes that @var{process-name} was
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894 stopped previously.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 @c Emacs 19 feature
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
898 @defun signal-process process signal
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
899 This function sends a signal to process @var{process}. The argument
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
900 @var{signal} specifies which signal to send; it should be an integer.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
901
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
902 You can specify the target process by its process @acronym{ID}; that allows
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
903 you to send signals to processes that are not children of Emacs.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 @node Output from Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 @section Receiving Output from Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 @cindex process output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909 @cindex output from processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 There are two ways to receive the output that a subprocess writes to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 its standard output stream. The output can be inserted in a buffer,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 which is called the associated buffer of the process, or a function
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
914 called the @dfn{filter function} can be called to act on the output. If
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
915 the process has no buffer and no filter function, its output is
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
916 discarded.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
917
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
918 When a subprocess terminates, Emacs reads any pending output,
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
919 then stops reading output from that subprocess. Therefore, if the
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
920 subprocess has children that are still live and still producing
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
921 output, Emacs won't receive that output.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
922
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
923 Output from a subprocess can arrive only while Emacs is waiting: when
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
924 reading terminal input, in @code{sit-for} and @code{sleep-for}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
925 (@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
926 Output}). This minimizes the problem of timing errors that usually
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
927 plague parallel programming. For example, you can safely create a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
928 process and only then specify its buffer or filter function; no output
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
929 can arrive before you finish, if the code in between does not call any
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
930 primitive that waits.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
931
27259
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
932 It is impossible to separate the standard output and standard error
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
933 streams of the subprocess, because Emacs normally spawns the subprocess
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
934 inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
935 you want to keep the output to those streams separate, you should
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
936 redirect one of them to a file--for example, by using an appropriate
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
937 shell command.
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
938
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 @menu
51993
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
940 * Process Buffers:: If no filter, output is put in a buffer.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
941 * Filter Functions:: Filter functions accept output from the process.
51994
eb38ba134224 Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 51993
diff changeset
942 * Decoding Output:: Filters can get unibyte or multibyte strings.
51993
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
943 * Accepting Output:: How to wait until process output arrives.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 @node Process Buffers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 @subsection Process Buffers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
948
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949 A process can (and usually does) have an @dfn{associated buffer},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 which is an ordinary Emacs buffer that is used for two purposes: storing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951 the output from the process, and deciding when to kill the process. You
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 can also use the buffer to identify a process to operate on, since in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953 normal practice only one process is associated with any given buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954 Many applications of processes also use the buffer for editing input to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955 be sent to the process, but this is not built into Emacs Lisp.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957 Unless the process has a filter function (@pxref{Filter Functions}),
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
958 its output is inserted in the associated buffer. The position to insert
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
959 the output is determined by the @code{process-mark}, which is then
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
960 updated to point to the end of the text just inserted. Usually, but not
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
961 always, the @code{process-mark} is at the end of the buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
962
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963 @defun process-buffer process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 This function returns the associated buffer of the process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 @var{process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 (process-buffer (get-process "shell"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970 @result{} #<buffer *shell*>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 @defun process-mark process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 This function returns the process marker for @var{process}, which is the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 marker that says where to insert output from the process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 If @var{process} does not have a buffer, @code{process-mark} returns a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 marker that points nowhere.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 Insertion of process output in a buffer uses this marker to decide where
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 to insert, and updates it to point after the inserted text. That is why
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 successive batches of output are inserted consecutively.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 Filter functions normally should use this marker in the same fashion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 as is done by direct insertion of output in the buffer. A good
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 example of a filter function that uses @code{process-mark} is found at
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989 the end of the following section.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991 When the user is expected to enter input in the process buffer for
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
992 transmission to the process, the process marker separates the new input
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
993 from previous output.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996 @defun set-process-buffer process buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 This function sets the buffer associated with @var{process} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 associated with no buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 @defun get-buffer-process buffer-or-name
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1003 This function returns a nondeleted process associated with the buffer
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1004 specified by @var{buffer-or-name}. If there are several processes
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1005 associated with it, this function chooses one (currently, the one most
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1006 recently created, but don't count on that). Deletion of a process
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1007 (see @code{delete-process}) makes it ineligible for this function to
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1008 return.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1009
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1010 It is usually a bad idea to have more than one process associated with
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1011 the same buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 (get-buffer-process "*shell*")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016 @result{} #<process shell>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020 Killing the process's buffer deletes the process, which kills the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1021 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1024 @node Filter Functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 @subsection Process Filter Functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026 @cindex filter function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027 @cindex process filter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029 A process @dfn{filter function} is a function that receives the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 standard output from the associated process. If a process has a filter,
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1031 then @emph{all} output from that process is passed to the filter. The
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1032 process buffer is used directly for output from the process only when
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1033 there is no filter.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1035 The filter function can only be called when Emacs is waiting for
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1036 something, because process output arrives only at such times. Emacs
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1037 waits when reading terminal input, in @code{sit-for} and
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1038 @code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1039 (@pxref{Accepting Output}).
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1040
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1041 A filter function must accept two arguments: the associated process
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1042 and a string, which is output just received from it. The function is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1043 then free to do whatever it chooses with the output.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1045 Quitting is normally inhibited within a filter function---otherwise,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 the effect of typing @kbd{C-g} at command level or to quit a user
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 command would be unpredictable. If you want to permit quitting inside a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048 filter function, bind @code{inhibit-quit} to @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 @xref{Quitting}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1051 If an error happens during execution of a filter function, it is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1052 caught automatically, so that it doesn't stop the execution of whatever
12125
995be67f3fd1 updates for version 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
1053 program was running when the filter function was started. However, if
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1054 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1055 off. This makes it possible to use the Lisp debugger to debug the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1056 filter function. @xref{Debugger}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1057
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 Many filter functions sometimes or always insert the text in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059 process's buffer, mimicking the actions of Emacs when there is no
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 filter. Such filter functions need to use @code{set-buffer} in order to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 be sure to insert in that buffer. To avoid setting the current buffer
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1062 semipermanently, these filter functions must save and restore the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1063 current buffer. They should also update the process marker, and in some
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1064 cases update the value of point. Here is how to do these things:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 (defun ordinary-insertion-filter (proc string)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1069 (with-current-buffer (process-buffer proc)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1070 (let ((moving (= (point) (process-mark proc))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1072 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1073 (save-excursion
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1074 ;; @r{Insert the text, advancing the process marker.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1075 (goto-char (process-mark proc))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1076 (insert string)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1077 (set-marker (process-mark proc) (point)))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1078 (if moving (goto-char (process-mark proc))))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 @noindent
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1083 The reason to use @code{with-current-buffer}, rather than using
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1084 @code{save-excursion} to save and restore the current buffer, is so as
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1085 to preserve the change in point made by the second call to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1086 @code{goto-char}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 To make the filter force the process buffer to be visible whenever new
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1089 text arrives, insert the following line just before the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1090 @code{with-current-buffer} construct:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1092 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 (display-buffer (process-buffer proc))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1096 To force point to the end of the new output, no matter where it was
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1097 previously, eliminate the variable @code{moving} and call
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1098 @code{goto-char} unconditionally.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1100 In earlier Emacs versions, every filter function that did regular
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1101 expression searching or matching had to explicitly save and restore the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1102 match data. Now Emacs does this automatically for filter functions;
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1103 they never need to do it explicitly. @xref{Match Data}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105 A filter function that writes the output into the buffer of the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1106 process should check whether the buffer is still alive. If it tries to
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1107 insert into a dead buffer, it will get an error. The expression
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1108 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1109 if the buffer is dead.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111 The output to the function may come in chunks of any size. A program
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1112 that produces the same output twice in a row may send it as one batch of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1113 200 characters one time, and five batches of 40 characters the next. If
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1114 the filter looks for certain text strings in the subprocess output, make
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1115 sure to handle the case where one of these strings is split across two
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1116 or more batches of output.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1118 @defun set-process-filter process filter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119 This function gives @var{process} the filter function @var{filter}. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 @var{filter} is @code{nil}, it gives the process no filter.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1121 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 @defun process-filter process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124 This function returns the filter function of @var{process}, or @code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125 if it has none.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 Here is an example of use of a filter function:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 (defun keep-output (process output)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 (setq kept (cons output kept)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 @result{} keep-output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 (setq kept nil)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1141 (set-process-filter (get-process "shell") 'keep-output)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142 @result{} keep-output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1143 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1144 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 (process-send-string "shell" "ls ~/other\n")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147 kept
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148 @result{} ("lewis@@slug[8] % "
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1150 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152 address.txt backup.psf kolstad.psf
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153 backup.bib~ david.mss resume-Dec-86.mss~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154 backup.err david.psf resume-Dec.psf
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 backup.mss dland syllabus.mss
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156 "
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157 "#backups.mss# backup.mss~ kolstad.mss
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 ")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1160 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162 @ignore @c The code in this example doesn't show the right way to do things.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 Here is another, more realistic example, which demonstrates how to use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 the process mark to do insertion in the same fashion as is done when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165 there is no filter function:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1169 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1170 ;; @r{and make sure that buffer is shown in some window.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1171 (defun my-process-filter (proc str)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1172 (let ((cur (selected-window))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1173 (pop-up-windows t))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1174 (pop-to-buffer my-shell-buffer)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1177 (goto-char (point-max))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1178 (insert str)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1179 (set-marker (process-mark proc) (point-max))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1180 (select-window cur)))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183 @end ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1184
51993
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1185 @node Decoding Output
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1186 @subsection Decoding Process Output
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1187
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1188 When Emacs writes process output directly into a multibyte buffer,
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1189 it decodes the output according to the process output coding system.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1190 If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1191 converts the unibyte output to multibyte using
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1192 @code{string-to-multibyte}, inserts the resulting multibyte text.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1193
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1194 You can use @code{set-process-coding-system} to specify which coding
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1195 system to use (@pxref{Process Information}). Otherwise, the coding
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1196 system comes from @code{coding-system-for-read}, if that is
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1197 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1198 Coding Systems}).
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1199
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1200 @strong{Warning:} Coding systems such as @code{undecided} which
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1201 determine the coding system from the data do not work entirely
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1202 reliably with asynchronous subprocess output. This is because Emacs
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1203 has to process asynchronous subprocess output in batches, as it
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1204 arrives. Emacs must try to detect the proper coding system from one
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1205 batch at a time, and this does not always work. Therefore, if at all
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1206 possible, specify a coding system that determines both the character
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1207 code conversion and the end of line conversion---that is, one like
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1208 @code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1209
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1210 @cindex filter multibyte flag, of process
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1211 @cindex process filter multibyte flag
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1212 When Emacs calls a process filter function, it provides the process
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1213 output as a multibyte string or as a unibyte string according to the
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1214 process's filter multibyte flag. If the flag is non-@code{nil}, Emacs
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1215 decodes the output according to the process output coding system to
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1216 produce a multibyte string, and passes that to the process. If the
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1217 flag is @code{nil}, Emacs puts the output into a unibyte string, with
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1218 no decoding, and passes that.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1219
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1220 When you create a process, the filter multibyte flag takes its
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1221 initial value from @code{default-enable-multibyte-characters}. If you
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1222 want to change the flag later on, use
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1223 @code{set-process-filter-multibyte}.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1224
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1225 @defun set-process-filter-multibyte process multibyte
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1226 This function sets the filter multibyte flag of @var{process}
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1227 to @var{multibyte}.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1228 @end defun
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1229
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1230 @defun process-filter-multibyte-p process
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1231 This function returns the filter multibyte flag of @var{process}.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1232 @end defun
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1233
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234 @node Accepting Output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235 @subsection Accepting Output from Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1237 Output from asynchronous subprocesses normally arrives only while
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238 Emacs is waiting for some sort of external event, such as elapsed time
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 or terminal input. Occasionally it is useful in a Lisp program to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240 explicitly permit output to arrive at a specific point, or even to wait
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241 until output arrives from a process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 @defun accept-process-output &optional process seconds millisec
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 This function allows Emacs to read pending output from processes. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245 output is inserted in the associated buffers or given to their filter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246 functions. If @var{process} is non-@code{nil} then this function does
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 not return until some output has been received from @var{process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 The arguments @var{seconds} and @var{millisec} let you specify timeout
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251 periods. The former specifies a period measured in seconds and the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 latter specifies one measured in milliseconds. The two time periods
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253 thus specified are added together, and @code{accept-process-output}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 returns after that much time whether or not there has been any
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 subprocess output.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1257 The argument @var{seconds} need not be an integer. If it is a floating
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1258 point number, this function waits for a fractional number of seconds.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1259 Some systems support only a whole number of seconds; on these systems,
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1260 @var{seconds} is rounded down.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1261
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262 Not all operating systems support waiting periods other than multiples
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263 of a second; on those that do not, you get an error if you specify
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 nonzero @var{millisec}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 The function @code{accept-process-output} returns non-@code{nil} if it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267 did get some output, or @code{nil} if the timeout expired before output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268 arrived.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271 @node Sentinels
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272 @section Sentinels: Detecting Process Status Changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1273 @cindex process sentinel
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1274 @cindex sentinel
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1275
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276 A @dfn{process sentinel} is a function that is called whenever the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277 associated process changes status for any reason, including signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278 (whether sent by Emacs or caused by the process's own actions) that
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1279 terminate, stop, or continue the process. The process sentinel is
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1280 also called if the process exits. The sentinel receives two
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1281 arguments: the process for which the event occurred, and a string
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1282 describing the type of event.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1283
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1284 The string describing the event looks like one of the following:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1285
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1286 @itemize @bullet
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
1287 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1288 @code{"finished\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1289
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1290 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1291 @code{"exited abnormally with code @var{exitcode}\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1292
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1293 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1294 @code{"@var{name-of-signal}\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1295
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1296 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1297 @code{"@var{name-of-signal} (core dumped)\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1299
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1300 A sentinel runs only while Emacs is waiting (e.g., for terminal
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1301 input, or for time to elapse, or for process output). This avoids the
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1302 timing errors that could result from running them at random places in
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1303 the middle of other Lisp programs. A program can wait, so that
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1304 sentinels will run, by calling @code{sit-for} or @code{sleep-for}
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1305 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1306 Output}). Emacs also allows sentinels to run when the command loop is
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1307 reading input. @code{delete-process} calls the sentinel when it
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1308 terminates a running process.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1309
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1310 Emacs does not keep a queue of multiple reasons to call the sentinel
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1311 of one process; it records just the current status and the fact that
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1312 there has been a change. Therefore two changes in status, coming in
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1313 quick succession, can call the sentinel just once. However, process
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1314 termination will always run the sentinel exactly once. This is
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1315 because the process status can't change again after termination.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1316
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1317 Quitting is normally inhibited within a sentinel---otherwise, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1318 effect of typing @kbd{C-g} at command level or to quit a user command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1319 would be unpredictable. If you want to permit quitting inside a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320 sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1321
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 A sentinel that writes the output into the buffer of the process
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1323 should check whether the buffer is still alive. If it tries to insert
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324 into a dead buffer, it will get an error. If the buffer is dead,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1327 If an error happens during execution of a sentinel, it is caught
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1328 automatically, so that it doesn't stop the execution of whatever
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1329 programs was running when the sentinel was started. However, if
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1330 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1331 off. This makes it possible to use the Lisp debugger to debug the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1332 sentinel. @xref{Debugger}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1333
44428
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1334 While a sentinel is running, the process sentinel is temporarily
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1335 set to @code{nil} so that the sentinel won't run recursively.
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1336 For this reason it is not possible for a sentinel to specify
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1337 a new sentinel.
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1338
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1339 In earlier Emacs versions, every sentinel that did regular expression
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1340 searching or matching had to explicitly save and restore the match data.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1341 Now Emacs does this automatically for sentinels; they never need to do
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1342 it explicitly. @xref{Match Data}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1343
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1344 @defun set-process-sentinel process sentinel
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345 This function associates @var{sentinel} with @var{process}. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1346 @var{sentinel} is @code{nil}, then the process will have no sentinel.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1347 The default behavior when there is no sentinel is to insert a message in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348 the process's buffer when the process status changes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1350 Changes in process sentinel take effect immediately---if the sentinel
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1351 is slated to be run but has not been called yet, and you specify a new
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1352 sentinel, the eventual call to the sentinel will use the new one.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1353
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1354 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1356 (defun msg-me (process event)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357 (princ
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 (format "Process: %s had the event `%s'" process event)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359 (set-process-sentinel (get-process "shell") 'msg-me)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1360 @result{} msg-me
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1362 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 (kill-process (get-process "shell"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364 @print{} Process: #<process shell> had the event `killed'
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 @result{} #<process shell>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1366 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370 @defun process-sentinel process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371 This function returns the sentinel of @var{process}, or @code{nil} if it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372 has none.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1374
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1375 @defun waiting-for-user-input-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1376 While a sentinel or filter function is running, this function returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1377 non-@code{nil} if Emacs was waiting for keyboard input from the user at
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1378 the time the sentinel or filter function was called, @code{nil} if it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1379 was not.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1380 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1381
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1382 @node Query Before Exit
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
1383 @section Querying Before Exit
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1384
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1385 When Emacs exits, it terminates all its subprocesses by sending them
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1386 the @code{SIGHUP} signal. Because some subprocesses are doing
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1387 valuable work, Emacs normally asks the user to confirm that it is ok
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1388 to terminate them. Each process has a query flag which, if
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1389 non-@code{nil}, says that Emacs should ask for confirmation before
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1390 exiting and thus killing that process. The default for the query flag
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1391 is @code{t}, meaning @emph{do} query.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1392
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1393 @tindex process-query-on-exit-flag
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1394 @defun process-query-on-exit-flag process
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1395 This returns the query flag of @var{process}.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1396 @end defun
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1397
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1398 @tindex set-process-query-on-exit-flag
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1399 @defun set-process-query-on-exit-flag process flag
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1400 This function sets the query flag of @var{process} to @var{flag}. It
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1401 returns @var{flag}.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1402
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1403 @smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1404 @group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1405 ;; @r{Don't query about the shell process}
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1406 (set-process-query-on-exit-flag (get-process "shell") nil)
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1407 @result{} t
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1408 @end group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1409 @end smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1410 @end defun
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1411
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1412 @defun process-kill-without-query process &optional do-query
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1413 This function clears the query flag of @var{process}, so that
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1414 Emacs will not query the user on account of that process.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1415
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1416 Actually, the function does more than that: it returns the old value of
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1417 the process's query flag, and sets the query flag to @var{do-query}.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1418 Please don't use this function to do those things any more---please
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1419 use the newer, cleaner functions @code{process-query-on-exit-flag} and
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1420 @code{set-process-query-on-exit-flag} in all but the simplest cases.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1421 The only way you should use @code{process-kill-without-query} nowadays
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1422 is like this:
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1423
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1424 @smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1425 @group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1426 ;; @r{Don't query about the shell process}
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1427 (process-kill-without-query (get-process "shell"))
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1428 @end group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1429 @end smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1430 @end defun
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1431
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1432 @node Transaction Queues
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1433 @section Transaction Queues
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1434 @cindex transaction queue
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1435
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1436 You can use a @dfn{transaction queue} to communicate with a subprocess
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1437 using transactions. First use @code{tq-create} to create a transaction
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1438 queue communicating with a specified process. Then you can call
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1439 @code{tq-enqueue} to send a transaction.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 @defun tq-create process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1442 This function creates and returns a transaction queue communicating with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443 @var{process}. The argument @var{process} should be a subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444 capable of sending and receiving streams of bytes. It may be a child
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1445 process, or it may be a TCP connection to a server, possibly on another
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446 machine.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1447 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1448
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1449 @defun tq-enqueue queue question regexp closure fn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1450 This function sends a transaction to queue @var{queue}. Specifying the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1451 queue has the effect of specifying the subprocess to talk to.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1453 The argument @var{question} is the outgoing message that starts the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 transaction. The argument @var{fn} is the function to call when the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455 corresponding answer comes back; it is called with two arguments:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456 @var{closure}, and the answer received.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457
39426
4520697c8aa5 (tq-enqueue): Clarify meaning of REGEXP.
Richard M. Stallman <rms@gnu.org>
parents: 27370
diff changeset
1458 The argument @var{regexp} is a regular expression that should match
4520697c8aa5 (tq-enqueue): Clarify meaning of REGEXP.
Richard M. Stallman <rms@gnu.org>
parents: 27370
diff changeset
1459 text at the end of the entire answer, but nothing before; that's how
4520697c8aa5 (tq-enqueue): Clarify meaning of REGEXP.
Richard M. Stallman <rms@gnu.org>
parents: 27370
diff changeset
1460 @code{tq-enqueue} determines where the answer ends.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1461
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462 The return value of @code{tq-enqueue} itself is not meaningful.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 @defun tq-close queue
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466 Shut down transaction queue @var{queue}, waiting for all pending transactions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467 to complete, and then terminate the connection or child process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1470 Transaction queues are implemented by means of a filter function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471 @xref{Filter Functions}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1473 @node Network
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1474 @section Network Connections
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1475 @cindex network connection
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476 @cindex TCP
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1477 @cindex UDP
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1479 Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1480 connections to other processes on the same machine or other machines.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1481 A network connection is handled by Lisp much like a subprocess, and is
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1482 represented by a process object. However, the process you are
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1483 communicating with is not a child of the Emacs process, so it has no
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
1484 process @acronym{ID}, and you can't kill it or send it signals. All you
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1485 can do is send and receive data. @code{delete-process} closes the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1486 connection, but does not kill the program at the other end; that
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1487 program must decide what to do about closure of the connection.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1488
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1489 Lisp programs can listen for connections by creating network
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1490 servers. A network server is also represented by a kind of process
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1491 object, but unlike a network connection, the network server never
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1492 transfers data itself. When it receives a connection request, it
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1493 creates a new network connection to represent the connection just
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1494 made. (The network connection inherits certain information, including
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1495 the process plist, from the server.) The network server then goes
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1496 back to listening for more connection requests.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1497
52818
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1498 Network connections and servers are created by calling
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1499 @code{make-network-process} with an argument list consisting of
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1500 keyword/argument pairs, for example @code{:server t} to create a
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1501 server process, or @code{:type 'datagram} to create a datagram
52830
b4281fb5cff8 (Network): Fix typo in xref (from Robert J. Chassell).
Kim F. Storm <storm@cua.dk>
parents: 52818
diff changeset
1502 connection. @xref{Low-Level Network}, for details. You can also use
52818
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1503 one of the @code{open-network-...} functions descibed below;
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1504 internally, they just call @code{make-network-process} with suitable
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1505 arguments.
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1506
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1507 You can distinguish process objects representing network connections
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1508 and servers from those representing subprocesses with the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1509 @code{process-status} function. The possible status values for
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1510 network connections are @code{open}, @code{closed}, @code{connect},
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1511 and @code{failed}. For a network server, the status is always
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1512 @code{listen}. None of those values is possible for a real
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1513 subprocess. @xref{Process Information}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1514
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1515 You can stop and resume operation of a network processes by calling
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1516 @code{stop-process} and @code{continue-process}. For a server
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1517 process, being stopped means not accepting new connections. (Up to 5
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1518 connection requests will be queued for when you resume the server; you
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1519 can increase this limit, unless it is imposed by the operating
52695
e5c94aabfe90 (Network): Say what stopped datagram connections do.
Richard M. Stallman <rms@gnu.org>
parents: 52598
diff changeset
1520 systems.) For a network stream connection, being stopped means not
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1521 processing input (any arriving input waits until you resume the
52695
e5c94aabfe90 (Network): Say what stopped datagram connections do.
Richard M. Stallman <rms@gnu.org>
parents: 52598
diff changeset
1522 connection). For a datagram connection, some number of packets may be
e5c94aabfe90 (Network): Say what stopped datagram connections do.
Richard M. Stallman <rms@gnu.org>
parents: 52598
diff changeset
1523 queued but input may be lost. You can use the function
e5c94aabfe90 (Network): Say what stopped datagram connections do.
Richard M. Stallman <rms@gnu.org>
parents: 52598
diff changeset
1524 @code{process-command} to determine whether a network connection or
e5c94aabfe90 (Network): Say what stopped datagram connections do.
Richard M. Stallman <rms@gnu.org>
parents: 52598
diff changeset
1525 server is stopped; a non-@code{nil} value means yes.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1527 @defun open-network-stream name buffer-or-name host service
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1528 This function opens a TCP connection, and returns a process object
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1529 that represents the connection.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1530
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531 The @var{name} argument specifies the name for the process object. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1532 is modified as necessary to make it unique.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1534 The @var{buffer-or-name} argument is the buffer to associate with the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1535 connection. Output from the connection is inserted in the buffer,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536 unless you specify a filter function to handle the output. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1537 @var{buffer-or-name} is @code{nil}, it means that the connection is not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538 associated with any buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540 The arguments @var{host} and @var{service} specify where to connect to;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1541 @var{host} is the host name (a string), and @var{service} is the name of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542 a defined network service (a string) or a port number (an integer).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543 @end defun
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51994
diff changeset
1544
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1545 @defun open-network-stream-nowait name buffer-or-name host service &optional sentinel filter
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1546 This function opens a TCP connection, like @code{open-network-stream},
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1547 but it returns immediately without waiting for the request to be
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1548 accepted or rejected by the remote server. When the request is
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1549 subsequently accepted or rejected, the process's sentinel function
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1550 will be called with a string that starts with @code{"open"} (on
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1551 success) or @code{"failed"} (on error).
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1552
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1553 Some systems do not support non-blocking connections; on those
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1554 systems, @code{open-network-stream-nowait} returns @code{nil}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1555 and does nothing.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1556
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1557 The optional arguments @var{sentinel} and @var{filter} specify the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1558 sentinel and filter functions for this network connection. It is
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1559 useful to specify them when opening the connection, because they will
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1560 be used later asynchronously. The other arguments mean the same as in
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1561 @code{open-network-stream}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1562 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1563
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1564 @defun process-contact process &optional key
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1565 This function returns information about how a network process was set
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1566 up. For a connection, when @var{key} is @code{nil}, it returns
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1567 @code{(@var{hostname} @var{service})} which specifies what you
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1568 connected to.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1569
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1570 If @var{key} is @code{t}, the value is the complete status information
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1571 for the connection or server; that is, the list of keywords and values
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1572 specified in @code{make-network-process}, except that some of the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1573 values represent the current status instead of what you specified:
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1574
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1575 @table @code
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1576 @item :buffer
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1577 The associated value is the process buffer.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1578 @item :filter
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1579 The associated value is the process filter function.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1580 @item :sentinel
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1581 The associated value is the process sentinel function.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1582 @item :remote
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1583 In a connection, this is the address in internal format of the remote peer.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1584 @item :local
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1585 The local address, in internal format.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1586 @item :service
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1587 In a server, if you specified @code{t} for @var{service},
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1588 this value is the actual port number.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1589 @end table
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1590
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1591 @code{:local} and @code{:remote} are included even if they were not
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1592 specified explicitly in @code{make-network-process}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1593
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1594 If @var{key} is a keyword, the function returns the value corresponding
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1595 to that keyword.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1596
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1597 For an ordinary child process, this function always returns @code{t}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1598 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1599
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1600 @node Network Servers
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1601 @section Network Servers
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1602
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1603 You create a server by calling @code{make-network-process} with
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1604 @code{:server t}. The server will listen for connection requests from
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1605 clients. When it accepts a client connection request, that creates a
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1606 new network connection, itself a process object, with the following
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1607 parameters:
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1608
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1609 @itemize @bullet
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1610 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1611 The connection's process name is constructed by concatenating the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1612 server process' @var{name} with a client identification string. The
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1613 client identification string for an IPv4 connection looks like
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1614 @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1615 unique number in brackets, as in @samp{<@var{nnn}>}. The number
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1616 is unique for each connection in the Emacs session.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1617
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1618 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1619 If the server's filter is non-@code{nil}, the connection process does
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1620 not get a separate process buffer; otherwise, Emacs creates a new
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1621 buffer for the purpose. The buffer name is the server's buffer name
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1622 or process name, concatenated with the client identification string.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1623
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1624 The server's process buffer value is never used directly by Emacs, but
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1625 it is passed to the log function, which can log connections by
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1626 inserting text there.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1627
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1628 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1629 The communication type and the process filter and sentinel are
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1630 inherited from those of the server. The server never directly
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1631 uses its filter and sentinel; their sole purpose is to initialize
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1632 connections made to the server.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1633
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1634 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1635 The connection's process contact info is set according to the client's
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1636 addressing information (typically an IP address and a port number).
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1637 This information is associated with the @code{process-contact}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1638 keywords @code{:host}, @code{:service}, @code{:remote}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1639
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1640 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1641 The connection's local address is set up according to the port
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1642 number used for the connection.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1643
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1644 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1645 The client process' plist is initialized from the server's plist.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1646 @end itemize
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1647
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1648 @defun open-network-stream-server name buffer-or-name service &optional sentinel filter
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1649 Create a network server process for a TCP service.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1650 It returns nil if server processes are not supported; otherwise,
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1651 it returns a subprocess-object to represent the server.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1652
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1653 When a client connects to the specified service, Emacs creates a new
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1654 subprocess to handle the new connection, and then calls its sentinel
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1655 function (which it has inherited from the server).
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1656
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1657 The optional arguments @var{sentinel} and @var{filter} specify the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1658 sentinel and filter functions for the server. It is useful to specify
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1659 them now, because they will be used later asynchronously when the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1660 server receives a connection request. The three arguments @var{name},
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1661 @var{buffer-or-name} and @var{service} mean the same thing as in
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1662 @code{open-network-stream}, but @var{service} can be @code{t}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1663 meaning ask the system to allocate an unused port to listen on.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1664 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1665
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1666 @node Datagrams
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1667 @section Datagrams
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1668 @cindex datagrams
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1669
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1670 A datagram connection communicates with individual packets
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1671 rather than streams of data. Each call to @code{process-send}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1672 sends one datagram packet, and each datagram received results
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1673 in one call to the filter function.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1674
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1675 The datagram connection doesn't have to talk with the same remote
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1676 peer all the time. It has a @dfn{remote peer address} which specifies
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1677 where to send datagrams to. Each time an incoming datagram is passed
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1678 to the filter function, the peer address is set to the address that
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1679 datagram came from; that way, if the filter function sends a datagram,
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1680 it will go back to that place. You can specify the remote peer
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1681 address when you create the datagram connection using the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1682 @code{:remote} keyword. You can change it later on by calling
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1683 @code{set-process-datagram-address}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1684
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1685 @defun process-datagram-address process
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1686 If @var{process} is a datagram connection or server, this function
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1687 returns its remote peer address.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1688 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1689
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1690 @defun set-process-datagram-address process address
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1691 If @var{process} is a datagram connection or server, this function
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1692 sets its remote peer address to @var{address}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1693 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1694
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1695 @node Low-Level Network
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1696 @section Low-Level Network Access
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1697
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1698 The basic function for creating network connections and network
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1699 servers is @code{make-network-process}. It can do either of those
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1700 jobs, depending on the arguments you give it.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1701
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1702 @defun make-network-process &rest args
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1703 This function creates a network connection or server and returns the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1704 process object that represents it. The arguments @var{args} are a
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1705 list of keyword/argument pairs. Omitting a keyword is always
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1706 equivalent to specifying it with value @code{nil}, except for
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1707 @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1708 are the meaningful keywords:
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1709
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1710 @table @asis
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1711 @item :name name
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1712 Use the string @var{name} as the process name. It is modified if
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1713 necessary to make it unique.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1714
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1715 @item :type @var{type}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1716 Specify the communication type. A value of @code{nil} specifies a
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1717 stream connection (the default); @code{datagram} specifies a datagram
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1718 connection. Both connections and servers can be of either type.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1719
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1720 @item :server @var{server-flag}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1721 If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1722 create a connection. For a stream type server, @var{server-flag} may
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1723 be an integer which then specifies the length of the queue of pending
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1724 connections to the server. The default queue length is 5.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1725
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1726 @item :host @var{host}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1727 Specify the host to connect to. @var{host} should be a host name or
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1728 internet address, as a string, or the symbol @code{local} to specify
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1729 the local host. If you specify @var{host} for a server, it must
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1730 specify a valid address for the local host, and only clients
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1731 connecting to that address will be accepted.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1732
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1733 @item :service @var{service}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1734 @var{service} specifies a port number to connect to, or, for a server,
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1735 the port number to listen on. It should be a service name that
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1736 translates to a port number, or an integer specifying the port number
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1737 directly. For a server, it can also be @code{t}, which means to let
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1738 the system select an unused port number.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1739
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1740 @item :family @var{family}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1741 @var{family} specifies the address (and protocol) family for
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1742 communication. @code{nil} stands for IPv4. @code{local} specifies a
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1743 Unix socket, in which case @var{host} is ignored.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1744
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1745 @item :local @var{local-address}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1746 For a server process, @var{local-address} is the address to listen on.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1747 It overrides @var{family}, @var{host} and @var{service}, and you
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1748 may as well not specify them.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1749
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1750 @item :remote @var{remote-address}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1751 For a connection, @var{remote-address} is the address to connect to.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1752 It overrides @var{family}, @var{host} and @var{service}, and you
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1753 may as well not specify them.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1754
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1755 For a datagram server, @var{remote-address} specifies the initial
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1756 setting of the remote datagram address.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1757
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1758 The format of @var{local-address} or @var{remote-address} depends on
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1759 the address family:
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1760
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1761 @itemize -
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1762 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1763 An IPv4 address is represented as a vector of integers @code{[@var{a}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1764 @var{b} @var{c} @var{d} @var{p}]} corresponding to numeric IP address
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1765 @var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1766
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1767 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1768 A local address is represented as a string which specifies the address
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1769 in the local address space.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1770
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1771 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1772 An ``unsupported family'' address is represented by a cons
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1773 @code{(@var{f} . @var{av})}, where @var{f} is the family number and
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1774 @var{av} is a vector specifying the socket address using with one
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1775 element per address data byte. Do not rely on this format in portable
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1776 code, as it may depend on implementation defined constants, data
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1777 sizes, and data structure alignment.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1778 @end itemize
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1779
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1780 @item :nowait @var{bool}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1781 If @var{bool} is non-@code{nil} for a stream connection, return
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1782 without waiting for the connection to complete. When the connection
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1783 succeeds or fails, Emacs will call the sentinel function, with a
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1784 second argument matching @code{"open"} (if successful) or
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1785 @code{"failed"}. The default is to block, so that
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1786 @code{make-network-process} does not return until the connection
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1787 has succeeded or failed.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1788
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1789 @item :stop @var{stopped}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1790 Start the network connection or server in the `stopped' state if
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1791 @var{stopped} is non-@code{nil}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1792
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1793 @item :buffer @var{buffer}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1794 Use @var{buffer} as the process buffer.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1795
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1796 @item :coding @var{coding}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1797 Use @var{coding} as the coding system for this process. To specify
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1798 different coding systems for decoding data from the connection and for
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1799 encoding data sent to it, specify @code{(@var{decoding} .
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1800 @var{encoding})} for @var{coding}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1801
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1802 If you don't specify this keyword at all, the default
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1803 is to determine the coding systems from the data.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1804
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1805 @item :noquery @var{query-flag}
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1806 Initialize the process query flag to @var{query-flag}. @xref{Query Before Exit}.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1807
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1808 @item :filter @var{filter}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1809 Initialize the process filter to @var{filter}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1810
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1811 @item :filter-multibyte @var{bool}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1812 If @var{bool} is non-@code{nil}, strings given to the process filter
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1813 are multibyte, otherwise they are unibyte. If you don't specify this
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1814 keyword at all, the default is that the strings are multibyte if
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1815 @code{default-enable-multibyte-characters} is non-@code{nil}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1816
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1817 @item :sentinel @var{sentinel}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1818 Initialize the process sentinel to @var{sentinel}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1819
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1820 @item :log @var{log}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1821 Initialize the log function of a server process to @var{log}. The log
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1822 function is called each time the server accepts a network connection
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1823 from a client. The arguments passed to the log function are
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1824 @var{server}, @var{connection}, and @var{message}, where @var{server}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1825 is the server process, @var{connection} is the new process for the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1826 connection, and @var{message} is a string describing what has
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1827 happened.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1828
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1829 @item :plist @var{plist}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1830 Initialize the process plist to @var{plist}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1831 @end table
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1832
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1833 The following network options can be specified for the network
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1834 process. Except for @code{:reuseaddr}, you can set or modify these
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1835 options later using @code{set-network-process-option}.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1836
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1837 For a server process, the options specified with
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1838 @code{make-network-process} are not inherited by the client
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1839 connections, so you will need to set the necessary options for each
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1840 child connection as they are created.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1841
52598
a0ba017ef9ef (Low-Level Network): Fix typo.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52596
diff changeset
1842 @table @asis
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1843 @item :bindtodevice @var{device-name}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1844 If @var{device-name} is a non-empty string identifying a network
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1845 interface name (see @code{network-interface-list}), only handle
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1846 packets received on that interface. If @var{device-name} is nil (the
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1847 default), handle packets received on any interface.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1848
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1849 Using this option may require special privileges on some systems.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1850
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1851 @item :broadcast @var{broadcast-flag}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1852 If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1853 process will receive datagram packet sent to a broadcast address, and
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1854 be able to send packets to a broadcast address. Ignored for a stream
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1855 connection.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1856
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1857 @item :dontroute @var{dontroute-flag}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1858 If @var{dontroute-flag} is non-@code{nil}, the process can only send
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1859 to hosts on the same network as the local host.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1860
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1861 @item :keepalive @var{keepalive-flag}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1862 If @var{keepalive-flag} is non-@code{nil} for a stream connection,
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1863 enable exchange of low-level keep-alive messa
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1864
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1865 @item :linger @var{linger-arg}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1866 If @var{linger-arg} is non-@code{nil}, wait for successful
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1867 transmission of all queued packets on the connection before it is
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1868 deleted (see @code{delete-process}). If @var{linger-arg} is an
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1869 integer, it specifies the maximum time in seconds to wait for queued
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1870 packets to be sent before closing the connection. Default is
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1871 @code{nil} which means to discard unsent queued packets when the
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1872 process is deleted.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1873
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1874 @item :oobinline @var{oobinline-flag}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1875 If @var{oobinline-flag} is non-@code{nil} for a stream connection,
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1876 receive out-of-band data in the normal data stream. Otherwise, ignore
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1877 out-of-band data.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1878
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1879 @item :priority @var{priority}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1880 Set the priority for packets sent on this connection to the integer
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1881 @var{priority}. The interpretation of this number is protocol
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1882 specific, such as setting the TOS (type of service) field on IP
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1883 packets sent on this connection. It may also have system dependent
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1884 effects, such as selecting a specific output queue on the network
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1885 interface.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1886
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1887 @item :reuseaddr @var{reuseaddr-flag}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1888 If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1889 server process, allow this server to reuse a specific port number (see
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1890 @code{:service}) unless another process on this host is already
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1891 listening on that port. If @var{reuseaddr-flag} is @code{nil}, there
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1892 may be a period of time after the last use of that port (by any
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1893 process on the host), where it is not possible to make a new server on
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1894 that port.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1895
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1896 @end table
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1897
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1898 The original argument list, modified with the actual connection
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1899 information, is available via the `process-contact' function.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1900 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1901
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1902 @defun set-network-process-option process option value
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1903 This function sets or modifies a network option for network process
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1904 @var{process}. See @code{make-network-process} for details of options
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1905 @var{option} and their corresponding values @var{value}.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1906
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1907 The current setting of an option is available via the
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1908 `process-contact' function.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1909 @end defun
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1910
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1911 @defun network-interface-list
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1912 This function returns a list describing the network interfaces
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1913 of the machine you are using. The value is an alist whose
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1914 elements have the form @code{(@var{name} . @var{address})}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1915 @var{address} has the same form as the @var{local-address}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1916 and @var{remote-address} arguments to @code{make-network-process}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1917 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1918
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1919 @defun network-interface-info ifname
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1920 This function returns information about the network interface named
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1921 @var{ifname}. The value is a list of the form @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1922
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1923 @table @var
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1924 @item addr
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1925 The internet protocol address.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1926 @item bcast
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1927 The broadcast address.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1928 @item netmask
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1929 The network mask.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1930 @item hwaddr
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1931 The layer 2 address (Ethernet MAC address, for instance).
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1932 @item flags
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1933 The current flags of the interface.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1934 @end table
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1935 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1936
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1937 @defun format-network-address address &optional omit-port
52759
b85ed952e000 Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 52695
diff changeset
1938 This function converts the Lisp representation of a network address to
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1939 a string. For example, a five-element vector @code{[@var{a} @var{b}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1940 @var{c} @var{d} @var{p}]} represents an IP address
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1941 @var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1942 @code{format-network-address} converts that to the string
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1943 @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1944
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1945 If @var{omit-port} is non-@code{nil}, the value does not include
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1946 the port number.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1947 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1948
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1949 To test for the availability of a given network feature, use
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1950 @code{featurep} like this:
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1951
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1952 @example
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1953 (featurep 'make-network-process '(@var{keyword} @var{value}))
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1954 @end example
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1955
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1956 @noindent
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1957 The result of the first form is @code{t} if it works to specify
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1958 @var{keyword} with value @var{value} in @code{make-network-process}.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1959 The result of the second form is @code{t} if @var{keyword} is
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1960 supported by @code{make-network-process}. Here are some of the
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1961 @var{keyword}---@var{value} pairs you can test in
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1962 this way.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1963
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1964 @table @code
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1965 @item (:nowait t)
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1966 Non-@code{nil} if non-blocking connect is supported.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1967 @item (:type datagram)
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1968 Non-@code{nil} if datagrams are supported.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1969 @item (:family local)
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1970 Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1971 @item (:service t)
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1972 Non-@code{nil} if the system can select the port for a server.
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1973 @end table
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1974
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1975 To test for the availability of a given network option, use
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1976 @code{featurep} like this:
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1977
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1978 @example
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1979 (featurep 'make-network-process '@var{keyword})
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1980 @end example
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1981
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1982 Here are some of the option @var{keyword}s you can test in
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1983 this way.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1984
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1985 @table @code
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1986 @item :bindtodevice
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1987 @itemx :broadcast
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1988 @itemx :dontroute
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1989 @itemx :keepalive
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1990 @itemx :linger
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1991 @itemx :oobinline
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1992 @itemx :priority
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1993 @itemx :reuseaddr
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1994 That particular network option is supported by
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1995 @code{make-network-process} and @code{set-network-process-option}.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1996 @end table
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1997
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51994
diff changeset
1998 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51994
diff changeset
1999 arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51994
diff changeset
2000 @end ignore
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2001