Mercurial > emacs
annotate lispref/processes.texi @ 26370:5f52cc1417ab
Use block statements in cases and declare v1 and v2
locally there. Rearrange case statements so that thos most
frequently executed come first. Avoid goto's in frequently
executed cases.
author | Gerd Moellmann <gerd@gnu.org> |
---|---|
date | Sun, 07 Nov 1999 13:06:59 +0000 |
parents | 467b88fab665 |
children | f6b52258db6a |
rev | line source |
---|---|
6558 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. |
6558 | 4 @c See the file elisp.texi for copying conditions. |
5 @setfilename ../info/processes | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
6 @node Processes, Display, Abbrevs, Top |
6558 | 7 @chapter Processes |
8 @cindex child process | |
9 @cindex parent process | |
10 @cindex subprocess | |
11 @cindex process | |
12 | |
13 In the terminology of operating systems, a @dfn{process} is a space in | |
14 which a program can execute. Emacs runs in a process. Emacs Lisp | |
15 programs can invoke other programs in processes of their own. These are | |
16 called @dfn{subprocesses} or @dfn{child processes} of the Emacs process, | |
17 which is their @dfn{parent process}. | |
18 | |
19 A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous}, | |
20 depending on how it is created. When you create a synchronous | |
21 subprocess, the Lisp program waits for the subprocess to terminate | |
22 before continuing execution. When you create an asynchronous | |
23 subprocess, it can run in parallel with the Lisp program. This kind of | |
24 subprocess is represented within Emacs by a Lisp object which is also | |
25 called a ``process''. Lisp programs can use this object to communicate | |
26 with the subprocess or to control it. For example, you can send | |
27 signals, obtain status information, receive output from the process, or | |
28 send input to it. | |
29 | |
30 @defun processp object | |
31 This function returns @code{t} if @var{object} is a process, | |
32 @code{nil} otherwise. | |
33 @end defun | |
34 | |
35 @menu | |
36 * Subprocess Creation:: Functions that start subprocesses. | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
37 * Shell Arguments:: Quoting an argument to pass it to a shell. |
6558 | 38 * Synchronous Processes:: Details of using synchronous subprocesses. |
39 * Asynchronous Processes:: Starting up an asynchronous subprocess. | |
40 * Deleting Processes:: Eliminating an asynchronous subprocess. | |
41 * Process Information:: Accessing run-status and other attributes. | |
42 * Input to Processes:: Sending input to an asynchronous subprocess. | |
43 * Signals to Processes:: Stopping, continuing or interrupting | |
44 an asynchronous subprocess. | |
45 * Output from Processes:: Collecting output from an asynchronous subprocess. | |
46 * Sentinels:: Sentinels run when process run-status changes. | |
47 * Transaction Queues:: Transaction-based communication with subprocesses. | |
12098 | 48 * Network:: Opening network connections. |
6558 | 49 @end menu |
50 | |
51 @node Subprocess Creation | |
52 @section Functions that Create Subprocesses | |
53 | |
54 There are three functions that create a new subprocess in which to run | |
55 a program. One of them, @code{start-process}, creates an asynchronous | |
56 process and returns a process object (@pxref{Asynchronous Processes}). | |
57 The other two, @code{call-process} and @code{call-process-region}, | |
58 create a synchronous process and do not return a process object | |
59 (@pxref{Synchronous Processes}). | |
60 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
61 Synchronous and asynchronous processes are explained in the following |
6558 | 62 sections. Since the three functions are all called in a similar |
63 fashion, their common arguments are described here. | |
64 | |
65 @cindex execute program | |
66 @cindex @code{PATH} environment variable | |
67 @cindex @code{HOME} environment variable | |
68 In all cases, the function's @var{program} argument specifies the | |
69 program to be run. An error is signaled if the file is not found or | |
70 cannot be executed. If the file name is relative, the variable | |
71 @code{exec-path} contains a list of directories to search. Emacs | |
72 initializes @code{exec-path} when it starts up, based on the value of | |
73 the environment variable @code{PATH}. The standard file name | |
74 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usual | |
75 in @code{exec-path}, but environment variable substitutions | |
76 (@samp{$HOME}, etc.) are not recognized; use | |
77 @code{substitute-in-file-name} to perform them (@pxref{File Name | |
78 Expansion}). | |
79 | |
80 Each of the subprocess-creating functions has a @var{buffer-or-name} | |
81 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
|
82 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
|
83 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
|
84 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
|
85 handles it. (@xref{Filter Functions}, and @ref{Read and Print}.) |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
86 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
|
87 same buffer because their output would be intermixed randomly. |
6558 | 88 |
89 @cindex program arguments | |
90 All three of the subprocess-creating functions have a @code{&rest} | |
91 argument, @var{args}. The @var{args} must all be strings, and they are | |
92 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
|
93 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
|
94 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
|
95 program. |
6558 | 96 |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7411
diff
changeset
|
97 @strong{Please note:} The argument @var{program} contains only the |
6558 | 98 name of the program; it may not contain any command-line arguments. You |
99 must use @var{args} to provide those. | |
100 | |
101 The subprocess gets its current directory from the value of | |
102 @code{default-directory} (@pxref{File Name Expansion}). | |
103 | |
104 @cindex environment variables, subprocesses | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
105 The subprocess inherits its environment from Emacs, but you can |
6558 | 106 specify overrides for it with @code{process-environment}. @xref{System |
107 Environment}. | |
108 | |
109 @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
|
110 @pindex movemail |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
111 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
|
112 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
|
113 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
|
114 Rmail uses it to fetch new mail from an inbox. |
6558 | 115 @end defvar |
116 | |
117 @defopt exec-path | |
118 The value of this variable is a list of directories to search for | |
119 programs to run in subprocesses. Each element is either the name of a | |
120 directory (i.e., a string), or @code{nil}, which stands for the default | |
121 directory (which is the value of @code{default-directory}). | |
122 @cindex program directories | |
123 | |
124 The value of @code{exec-path} is used by @code{call-process} and | |
125 @code{start-process} when the @var{program} argument is not an absolute | |
126 file name. | |
127 @end defopt | |
128 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
129 @node Shell Arguments |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
130 @section Shell Arguments |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
131 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
132 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
|
133 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
|
134 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
|
135 gives special treatment to certain characters, and if these characters |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
136 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
|
137 characters, use the function @code{shell-quote-argument}: |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
138 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
139 @defun shell-quote-argument argument |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
140 This function returns a string which represents, in shell syntax, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
141 an argument whose actual contents are @var{argument}. It should |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
142 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
|
143 and then pass it to a shell for execution. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
144 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
145 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
|
146 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
|
147 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
|
148 function. |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
149 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
150 @example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
151 ;; @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
|
152 (shell-quote-argument "foo > bar") |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
153 @result{} "foo\\ \\>\\ bar" |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
154 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
155 ;; @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
|
156 (shell-quote-argument "foo > bar") |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
157 @result{} "\"foo > bar\"" |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
158 @end example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
159 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
160 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
|
161 a shell command: |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
162 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
163 @example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
164 (concat "diff -c " |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
165 (shell-quote-argument oldfile) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
166 " " |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
167 (shell-quote-argument newfile)) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
168 @end example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
169 @end defun |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
170 |
6558 | 171 @node Synchronous Processes |
172 @section Creating a Synchronous Process | |
173 @cindex synchronous subprocess | |
174 | |
175 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
|
176 process to terminate before continuing. Starting Dired on GNU or |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
177 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
|
178 @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
|
179 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
|
180 slightly. Because the process is synchronous, the entire directory |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
181 listing arrives in the buffer before Emacs tries to do anything with it. |
6558 | 182 |
183 While Emacs waits for the synchronous subprocess to terminate, the | |
184 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill | |
185 the subprocess with a @code{SIGINT} signal; but it waits until the | |
186 subprocess actually terminates before quitting. If during that time the | |
187 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
|
188 @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
|
189 other processes doesn't work). @xref{Quitting}. |
6558 | 190 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
191 The synchronous subprocess functions return an indication of how the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
192 process terminated. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
193 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
194 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
|
195 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
|
196 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
|
197 system, much like text written into a file. @xref{Coding Systems}. |
6558 | 198 |
12067 | 199 @defun call-process program &optional infile destination display &rest args |
6558 | 200 This function calls @var{program} in a separate process and waits for |
201 it to finish. | |
202 | |
203 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
|
204 @var{infile} is not @code{nil}, and from the null device otherwise. |
12067 | 205 The argument @var{destination} says where to put the process output. |
206 Here are the possibilities: | |
207 | |
208 @table @asis | |
209 @item a buffer | |
210 Insert the output in that buffer, before point. This includes both the | |
211 standard output stream and the standard error stream of the process. | |
212 | |
213 @item a string | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
214 Insert the output in a buffer with that name, before point. |
12067 | 215 |
216 @item @code{t} | |
217 Insert the output in the current buffer, before point. | |
218 | |
219 @item @code{nil} | |
220 Discard the output. | |
6558 | 221 |
12067 | 222 @item 0 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
223 Discard the output, and return @code{nil} immediately without waiting |
12067 | 224 for the subprocess to finish. |
225 | |
226 In this case, the process is not truly synchronous, since it can run in | |
227 parallel with Emacs; but you can think of it as synchronous in that | |
228 Emacs is essentially finished with the subprocess as soon as this | |
229 function returns. | |
230 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
231 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
|
232 work there. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
233 |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
234 @item @code{(@var{real-destination} @var{error-destination})} |
12067 | 235 Keep the standard output stream separate from the standard error stream; |
236 deal with the ordinary output as specified by @var{real-destination}, | |
237 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
|
238 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
|
239 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
|
240 string specifies a file name to redirect error output into. |
12067 | 241 |
242 You can't directly specify a buffer to put the error output in; that is | |
243 too difficult to implement. But you can achieve this result by sending | |
244 the error output to a temporary file and then inserting the file into a | |
245 buffer. | |
246 @end table | |
6558 | 247 |
248 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
|
249 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
|
250 for decoding output is @code{undecided}, meaning deduce the encoding |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
251 from the actual data, then redisplay sometimes cannot continue once |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
252 non-@sc{ascii} characters are encountered. There are fundamental |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
253 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
|
254 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
255 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
|
256 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
|
257 buffer in the normal course of events. |
6558 | 258 |
259 The remaining arguments, @var{args}, are strings that specify command | |
260 line arguments for the program. | |
261 | |
262 The value returned by @code{call-process} (unless you told it not to | |
263 wait) indicates the reason for process termination. A number gives the | |
264 exit status of the subprocess; 0 means success, and any other value | |
265 means failure. If the process terminated with a signal, | |
266 @code{call-process} returns a string describing the signal. | |
267 | |
268 In the examples below, the buffer @samp{foo} is current. | |
269 | |
270 @smallexample | |
271 @group | |
272 (call-process "pwd" nil t) | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
273 @result{} 0 |
6558 | 274 |
275 ---------- Buffer: foo ---------- | |
276 /usr/user/lewis/manual | |
277 ---------- Buffer: foo ---------- | |
278 @end group | |
279 | |
280 @group | |
281 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
282 @result{} 0 |
6558 | 283 |
284 ---------- Buffer: bar ---------- | |
285 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh | |
286 | |
287 ---------- Buffer: bar ---------- | |
288 @end group | |
289 @end smallexample | |
290 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
291 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
|
292 be found in the definition of @code{insert-directory}: |
6558 | 293 |
294 @smallexample | |
295 @group | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
296 (call-process insert-directory-program nil t nil @var{switches} |
6558 | 297 (if full-directory-p |
298 (concat (file-name-as-directory file) ".") | |
299 file)) | |
300 @end group | |
301 @end smallexample | |
302 @end defun | |
303 | |
12067 | 304 @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
|
305 This function sends the text from @var{start} to @var{end} as |
6558 | 306 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
|
307 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
|
308 @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
|
309 buffer in place of the input. |
6558 | 310 |
12067 | 311 The arguments @var{destination} and @var{display} control what to do |
6558 | 312 with the output from the subprocess, and whether to update the display |
313 as it comes in. For details, see the description of | |
12067 | 314 @code{call-process}, above. If @var{destination} is the integer 0, |
6558 | 315 @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
|
316 immediately, without waiting for the subprocess to finish (this only |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
317 works if asynchronous subprocess are supported). |
6558 | 318 |
319 The remaining arguments, @var{args}, are strings that specify command | |
320 line arguments for the program. | |
321 | |
322 The return value of @code{call-process-region} is just like that of | |
323 @code{call-process}: @code{nil} if you told it to return without | |
324 waiting; otherwise, a number or string which indicates how the | |
325 subprocess terminated. | |
326 | |
327 In the following example, we use @code{call-process-region} to run the | |
328 @code{cat} utility, with standard input being the first five characters | |
329 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its | |
330 standard input into its standard output. Since the argument | |
12067 | 331 @var{destination} is @code{t}, this output is inserted in the current |
6558 | 332 buffer. |
333 | |
334 @smallexample | |
335 @group | |
336 ---------- Buffer: foo ---------- | |
337 input@point{} | |
338 ---------- Buffer: foo ---------- | |
339 @end group | |
340 | |
341 @group | |
342 (call-process-region 1 6 "cat" nil t) | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
343 @result{} 0 |
6558 | 344 |
345 ---------- Buffer: foo ---------- | |
346 inputinput@point{} | |
347 ---------- Buffer: foo ---------- | |
348 @end group | |
349 @end smallexample | |
350 | |
351 The @code{shell-command-on-region} command uses | |
352 @code{call-process-region} like this: | |
353 | |
354 @smallexample | |
355 @group | |
356 (call-process-region | |
357 start end | |
358 shell-file-name ; @r{Name of program.} | |
359 nil ; @r{Do not delete region.} | |
360 buffer ; @r{Send output to @code{buffer}.} | |
361 nil ; @r{No redisplay during output.} | |
362 "-c" command) ; @r{Arguments for the shell.} | |
363 @end group | |
364 @end smallexample | |
365 @end defun | |
366 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
367 @defun shell-command-to-string command |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
368 @tindex shell-command-to-string |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
369 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
|
370 then returns the command's output as a string. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
371 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
372 |
6558 | 373 @node Asynchronous Processes |
374 @section Creating an Asynchronous Process | |
375 @cindex asynchronous subprocess | |
376 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
377 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
|
378 both continue running immediately. The process thereafter runs |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
379 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
|
380 using the functions described in the following sections. However, |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
381 communication is only partially asynchronous: Emacs sends data to the |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
382 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
|
383 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
|
384 delay. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
385 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
386 Here we describe how to create an asynchronous process. |
6558 | 387 |
388 @defun start-process name buffer-or-name program &rest args | |
389 This function creates a new asynchronous subprocess and starts the | |
390 program @var{program} running in it. It returns a process object that | |
391 stands for the new subprocess in Lisp. The argument @var{name} | |
392 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
|
393 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
|
394 etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to |
6558 | 395 associate with the process. |
396 | |
397 The remaining arguments, @var{args}, are strings that specify command | |
398 line arguments for the program. | |
399 | |
400 In the example below, the first process is started and runs (rather, | |
401 sleeps) for 100 seconds. Meanwhile, the second process is started, and | |
402 given the name @samp{my-process<1>} for the sake of uniqueness. It | |
403 inserts the directory listing at the end of the buffer @samp{foo}, | |
404 before the first process finishes. Then it finishes, and a message to | |
405 that effect is inserted in the buffer. Much later, the first process | |
406 finishes, and another message is inserted in the buffer for it. | |
407 | |
408 @smallexample | |
409 @group | |
410 (start-process "my-process" "foo" "sleep" "100") | |
411 @result{} #<process my-process> | |
412 @end group | |
413 | |
414 @group | |
415 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") | |
416 @result{} #<process my-process<1>> | |
417 | |
418 ---------- Buffer: foo ---------- | |
419 total 2 | |
420 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs | |
421 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon | |
422 | |
423 Process my-process<1> finished | |
424 | |
425 Process my-process finished | |
426 ---------- Buffer: foo ---------- | |
427 @end group | |
428 @end smallexample | |
429 @end defun | |
430 | |
431 @defun start-process-shell-command name buffer-or-name command &rest command-args | |
432 This function is like @code{start-process} except that it uses a shell | |
433 to execute the specified command. The argument @var{command} is a shell | |
434 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
|
435 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
|
436 use. |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
437 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
438 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
|
439 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
|
440 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
|
441 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
|
442 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
|
443 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
|
444 Arguments}. |
6558 | 445 @end defun |
446 | |
447 @defvar process-connection-type | |
448 @cindex pipes | |
449 @cindex @sc{pty}s | |
450 This variable controls the type of device used to communicate with | |
12098 | 451 asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are |
452 used, when available. Otherwise, pipes are used. | |
6558 | 453 |
454 @sc{pty}s are usually preferable for processes visible to the user, as | |
455 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
|
456 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
|
457 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
|
458 often better to use a pipe, because they are more efficient. In |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
459 addition, the total number of @sc{pty}s is limited on many systems and |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
460 it is good not to waste them. |
6558 | 461 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
462 The value of @code{process-connection-type} is used when |
6558 | 463 @code{start-process} is called. So you can specify how to communicate |
464 with one subprocess by binding the variable around the call to | |
465 @code{start-process}. | |
466 | |
467 @smallexample | |
468 @group | |
469 (let ((process-connection-type nil)) ; @r{Use a pipe.} | |
470 (start-process @dots{})) | |
471 @end group | |
472 @end smallexample | |
12067 | 473 |
474 To determine whether a given subprocess actually got a pipe or a | |
475 @sc{pty}, use the function @code{process-tty-name} (@pxref{Process | |
476 Information}). | |
6558 | 477 @end defvar |
478 | |
479 @node Deleting Processes | |
480 @section Deleting Processes | |
481 @cindex deleting processes | |
482 | |
483 @dfn{Deleting a process} disconnects Emacs immediately from the | |
484 subprocess, and removes it from the list of active processes. It sends | |
485 a signal to the subprocess to make the subprocess terminate, but this is | |
486 not guaranteed to happen immediately. The process object itself | |
15759
e74f36ff89e7
Explain how deletion of process doesn't affect process mark.
Richard M. Stallman <rms@gnu.org>
parents:
12125
diff
changeset
|
487 continues to exist as long as other Lisp objects point to it. The |
e74f36ff89e7
Explain how deletion of process doesn't affect process mark.
Richard M. Stallman <rms@gnu.org>
parents:
12125
diff
changeset
|
488 process mark continues to point to the same place as before (usually |
e74f36ff89e7
Explain how deletion of process doesn't affect process mark.
Richard M. Stallman <rms@gnu.org>
parents:
12125
diff
changeset
|
489 into a buffer where output from the process was being inserted). |
6558 | 490 |
491 You can delete a process explicitly at any time. Processes are | |
492 deleted automatically after they terminate, but not necessarily right | |
493 away. If you delete a terminated process explicitly before it is | |
494 deleted automatically, no harm results. | |
495 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
496 @defopt delete-exited-processes |
6558 | 497 This variable controls automatic deletion of processes that have |
498 terminated (due to calling @code{exit} or to a signal). If it is | |
499 @code{nil}, then they continue to exist until the user runs | |
500 @code{list-processes}. Otherwise, they are deleted immediately after | |
501 they exit. | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
502 @end defopt |
6558 | 503 |
504 @defun delete-process name | |
505 This function deletes the process associated with @var{name}, killing it | |
506 with a @code{SIGHUP} signal. The argument @var{name} may be a process, | |
507 the name of a process, a buffer, or the name of a buffer. | |
508 | |
509 @smallexample | |
510 @group | |
511 (delete-process "*shell*") | |
512 @result{} nil | |
513 @end group | |
514 @end smallexample | |
515 @end defun | |
516 | |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
517 @defun process-kill-without-query process &optional do-query |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
518 This function specifies whether Emacs should query the user if |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
519 @var{process} is still running when Emacs is exited. If @var{do-query} |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
520 is @code{nil}, the process will be deleted silently. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
521 Otherwise, Emacs will query about killing it. |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
522 |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
523 The value is @code{t} if the process was formerly set up to require |
22267
dfac7398266b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
524 query, @code{nil} otherwise. A newly-created process always requires |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
525 query. |
6558 | 526 |
527 @smallexample | |
528 @group | |
529 (process-kill-without-query (get-process "shell")) | |
530 @result{} t | |
531 @end group | |
532 @end smallexample | |
533 @end defun | |
534 | |
535 @node Process Information | |
536 @section Process Information | |
537 | |
538 Several functions return information about processes. | |
539 @code{list-processes} is provided for interactive use. | |
540 | |
541 @deffn Command list-processes | |
542 This command displays a listing of all living processes. In addition, | |
543 it finally deletes any process whose status was @samp{Exited} or | |
544 @samp{Signaled}. It returns @code{nil}. | |
545 @end deffn | |
546 | |
547 @defun process-list | |
548 This function returns a list of all processes that have not been deleted. | |
549 | |
550 @smallexample | |
551 @group | |
552 (process-list) | |
553 @result{} (#<process display-time> #<process shell>) | |
554 @end group | |
555 @end smallexample | |
556 @end defun | |
557 | |
558 @defun get-process name | |
559 This function returns the process named @var{name}, or @code{nil} if | |
560 there is none. An error is signaled if @var{name} is not a string. | |
561 | |
562 @smallexample | |
563 @group | |
564 (get-process "shell") | |
565 @result{} #<process shell> | |
566 @end group | |
567 @end smallexample | |
568 @end defun | |
569 | |
570 @defun process-command process | |
571 This function returns the command that was executed to start | |
572 @var{process}. This is a list of strings, the first string being the | |
573 program executed and the rest of the strings being the arguments that | |
574 were given to the program. | |
575 | |
576 @smallexample | |
577 @group | |
578 (process-command (get-process "shell")) | |
579 @result{} ("/bin/csh" "-i") | |
580 @end group | |
581 @end smallexample | |
582 @end defun | |
583 | |
584 @defun process-id process | |
585 This function returns the @sc{pid} of @var{process}. This is an | |
9009 | 586 integer that distinguishes the process @var{process} from all other |
6558 | 587 processes running on the same computer at the current time. The |
588 @sc{pid} of a process is chosen by the operating system kernel when the | |
589 process is started and remains constant as long as the process exists. | |
590 @end defun | |
591 | |
592 @defun process-name process | |
593 This function returns the name of @var{process}. | |
594 @end defun | |
595 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
596 @defun process-contact process |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
597 @tindex process-contact |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
598 This function returns @code{t} for an ordinary child process, and |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
599 @code{(@var{hostname} @var{service})} for a net connection |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
600 (@pxref{Network}). |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
601 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
602 |
6558 | 603 @defun process-status process-name |
604 This function returns the status of @var{process-name} as a symbol. | |
605 The argument @var{process-name} must be a process, a buffer, a | |
606 process name (string) or a buffer name (string). | |
607 | |
608 The possible values for an actual subprocess are: | |
609 | |
610 @table @code | |
611 @item run | |
612 for a process that is running. | |
613 @item stop | |
614 for a process that is stopped but continuable. | |
615 @item exit | |
616 for a process that has exited. | |
617 @item signal | |
618 for a process that has received a fatal signal. | |
619 @item open | |
620 for a network connection that is open. | |
621 @item closed | |
622 for a network connection that is closed. Once a connection | |
623 is closed, you cannot reopen it, though you might be able to open | |
624 a new connection to the same place. | |
625 @item nil | |
626 if @var{process-name} is not the name of an existing process. | |
627 @end table | |
628 | |
629 @smallexample | |
630 @group | |
631 (process-status "shell") | |
632 @result{} run | |
633 @end group | |
634 @group | |
635 (process-status (get-buffer "*shell*")) | |
636 @result{} run | |
637 @end group | |
638 @group | |
639 x | |
640 @result{} #<process xx<1>> | |
641 (process-status x) | |
642 @result{} exit | |
643 @end group | |
644 @end smallexample | |
645 | |
646 For a network connection, @code{process-status} returns one of the symbols | |
647 @code{open} or @code{closed}. The latter means that the other side | |
648 closed the connection, or Emacs did @code{delete-process}. | |
649 @end defun | |
650 | |
651 @defun process-exit-status process | |
652 This function returns the exit status of @var{process} or the signal | |
653 number that killed it. (Use the result of @code{process-status} to | |
654 determine which of those it is.) If @var{process} has not yet | |
655 terminated, the value is 0. | |
656 @end defun | |
657 | |
12067 | 658 @defun process-tty-name process |
659 This function returns the terminal name that @var{process} is using for | |
660 its communication with Emacs---or @code{nil} if it is using pipes | |
661 instead of a terminal (see @code{process-connection-type} in | |
662 @ref{Asynchronous Processes}). | |
663 @end defun | |
664 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
665 @defun process-coding-system process |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
666 @tindex process-coding-system |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
667 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
|
668 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
|
669 @var{process} (@pxref{Coding Systems}). The value has this form: |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
670 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
671 @example |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
672 (@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
|
673 @end example |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
674 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
675 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
676 @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
|
677 @tindex set-process-coding-system |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
678 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
|
679 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
|
680 decode subprocess output, and @var{encoding-system} to encode subprocess |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
681 input. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
682 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
683 |
6558 | 684 @node Input to Processes |
685 @section Sending Input to Processes | |
686 @cindex process input | |
687 | |
688 Asynchronous subprocesses receive input when it is sent to them by | |
689 Emacs, which is done with the functions in this section. You must | |
690 specify the process to send input to, and the input data to send. The | |
691 data appears on the ``standard input'' of the subprocess. | |
692 | |
693 Some operating systems have limited space for buffered input in a | |
694 @sc{pty}. On these systems, Emacs sends an @sc{eof} periodically amidst | |
695 the other characters, to force them through. For most programs, | |
696 these @sc{eof}s do no harm. | |
697 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
698 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
|
699 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
|
700 @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
|
701 (@pxref{Process Information}). Otherwise, the coding system comes from |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
702 @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
|
703 the defaulting mechanism (@pxref{Default Coding Systems}). |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
704 |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22267
diff
changeset
|
705 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
|
706 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
|
707 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
|
708 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
|
709 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
|
710 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
|
711 |
6558 | 712 @defun process-send-string process-name string |
713 This function sends @var{process-name} the contents of @var{string} as | |
714 standard input. The argument @var{process-name} must be a process or | |
715 the name of a process. If it is @code{nil}, the current buffer's | |
716 process is used. | |
717 | |
718 The function returns @code{nil}. | |
719 | |
720 @smallexample | |
721 @group | |
722 (process-send-string "shell<1>" "ls\n") | |
723 @result{} nil | |
724 @end group | |
725 | |
726 | |
727 @group | |
728 ---------- Buffer: *shell* ---------- | |
729 ... | |
730 introduction.texi syntax-tables.texi~ | |
731 introduction.texi~ text.texi | |
732 introduction.txt text.texi~ | |
733 ... | |
734 ---------- Buffer: *shell* ---------- | |
735 @end group | |
736 @end smallexample | |
737 @end defun | |
738 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
739 @defun process-send-region process-name start end |
6558 | 740 This function sends the text in the region defined by @var{start} and |
741 @var{end} as standard input to @var{process-name}, which is a process or | |
742 a process name. (If it is @code{nil}, the current buffer's process is | |
743 used.) | |
744 | |
745 An error is signaled unless both @var{start} and @var{end} are | |
746 integers or markers that indicate positions in the current buffer. (It | |
747 is unimportant which number is larger.) | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
748 @end defun |
6558 | 749 |
750 @defun process-send-eof &optional process-name | |
751 This function makes @var{process-name} see an end-of-file in its | |
752 input. The @sc{eof} comes after any text already sent to it. | |
753 | |
754 If @var{process-name} is not supplied, or if it is @code{nil}, then | |
755 this function sends the @sc{eof} to the current buffer's process. An | |
756 error is signaled if the current buffer has no process. | |
757 | |
758 The function returns @var{process-name}. | |
759 | |
760 @smallexample | |
761 @group | |
762 (process-send-eof "shell") | |
763 @result{} "shell" | |
764 @end group | |
765 @end smallexample | |
766 @end defun | |
767 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22267
diff
changeset
|
768 @defun process-running-child-p process |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22267
diff
changeset
|
769 @tindex process-running-child-p process |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22267
diff
changeset
|
770 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
|
771 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
|
772 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
|
773 that this is not so. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22267
diff
changeset
|
774 @end defun |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22267
diff
changeset
|
775 |
6558 | 776 @node Signals to Processes |
777 @section Sending Signals to Processes | |
778 @cindex process signals | |
779 @cindex sending signals | |
780 @cindex signals | |
781 | |
782 @dfn{Sending a signal} to a subprocess is a way of interrupting its | |
783 activities. There are several different signals, each with its own | |
784 meaning. The set of signals and their names is defined by the operating | |
785 system. For example, the signal @code{SIGINT} means that the user has | |
786 typed @kbd{C-c}, or that some analogous thing has happened. | |
787 | |
788 Each signal has a standard effect on the subprocess. Most signals | |
789 kill the subprocess, but some stop or resume execution instead. Most | |
790 signals can optionally be handled by programs; if the program handles | |
791 the signal, then we can say nothing in general about its effects. | |
792 | |
793 You can send signals explicitly by calling the functions in this | |
794 section. Emacs also sends signals automatically at certain times: | |
795 killing a buffer sends a @code{SIGHUP} signal to all its associated | |
796 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining | |
797 processes. (@code{SIGHUP} is a signal that usually indicates that the | |
798 user hung up the phone.) | |
799 | |
800 Each of the signal-sending functions takes two optional arguments: | |
801 @var{process-name} and @var{current-group}. | |
802 | |
803 The argument @var{process-name} must be either a process, the name of | |
804 one, or @code{nil}. If it is @code{nil}, the process defaults to the | |
805 process associated with the current buffer. An error is signaled if | |
806 @var{process-name} does not identify a process. | |
807 | |
808 The argument @var{current-group} is a flag that makes a difference | |
809 when you are running a job-control shell as an Emacs subprocess. If it | |
810 is non-@code{nil}, then the signal is sent to the current process-group | |
9009 | 811 of the terminal that Emacs uses to communicate with the subprocess. If |
6558 | 812 the process is a job-control shell, this means the shell's current |
813 subjob. If it is @code{nil}, the signal is sent to the process group of | |
814 the immediate subprocess of Emacs. If the subprocess is a job-control | |
815 shell, this is the shell itself. | |
816 | |
817 The flag @var{current-group} has no effect when a pipe is used to | |
818 communicate with the subprocess, because the operating system does not | |
819 support the distinction in the case of pipes. For the same reason, | |
820 job-control shells won't work when a pipe is used. See | |
821 @code{process-connection-type} in @ref{Asynchronous Processes}. | |
822 | |
823 @defun interrupt-process &optional process-name current-group | |
824 This function interrupts the process @var{process-name} by sending the | |
825 signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt | |
826 character'' (normally @kbd{C-c} on some systems, and @code{DEL} on | |
827 others) sends this signal. When the argument @var{current-group} is | |
828 non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' | |
829 on the terminal by which Emacs talks to the subprocess. | |
830 @end defun | |
831 | |
832 @defun kill-process &optional process-name current-group | |
833 This function kills the process @var{process-name} by sending the | |
834 signal @code{SIGKILL}. This signal kills the subprocess immediately, | |
835 and cannot be handled by the subprocess. | |
836 @end defun | |
837 | |
838 @defun quit-process &optional process-name current-group | |
839 This function sends the signal @code{SIGQUIT} to the process | |
840 @var{process-name}. This signal is the one sent by the ``quit | |
841 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside | |
842 Emacs. | |
843 @end defun | |
844 | |
845 @defun stop-process &optional process-name current-group | |
846 This function stops the process @var{process-name} by sending the | |
847 signal @code{SIGTSTP}. Use @code{continue-process} to resume its | |
848 execution. | |
849 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
850 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
|
851 (usually @kbd{C-z}) normally sends this signal. When |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
852 @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
|
853 ``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
|
854 subprocess. |
6558 | 855 @end defun |
856 | |
857 @defun continue-process &optional process-name current-group | |
858 This function resumes execution of the process @var{process} by sending | |
859 it the signal @code{SIGCONT}. This presumes that @var{process-name} was | |
860 stopped previously. | |
861 @end defun | |
862 | |
863 @c Emacs 19 feature | |
864 @defun signal-process pid signal | |
865 This function sends a signal to process @var{pid}, which need not be | |
866 a child of Emacs. The argument @var{signal} specifies which signal | |
867 to send; it should be an integer. | |
868 @end defun | |
869 | |
870 @node Output from Processes | |
871 @section Receiving Output from Processes | |
872 @cindex process output | |
873 @cindex output from processes | |
874 | |
875 There are two ways to receive the output that a subprocess writes to | |
876 its standard output stream. The output can be inserted in a buffer, | |
877 which is called the associated buffer of the process, or a function | |
9009 | 878 called the @dfn{filter function} can be called to act on the output. If |
879 the process has no buffer and no filter function, its output is | |
880 discarded. | |
6558 | 881 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
882 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
|
883 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
|
884 (@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
885 Output}). This minimizes the problem of timing errors that usually |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
886 plague parallel programming. For example, you can safely create a |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
887 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
|
888 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
|
889 primitive that waits. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
890 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
891 Subprocess output is normally decoded using a coding system before the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
892 buffer or filter function receives it, much like text read from a file. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
893 You can use @code{set-process-coding-system} to specify which coding |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
894 system to use (@pxref{Process Information}). Otherwise, the coding |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
895 system comes from @code{coding-system-for-read}, if that is |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
896 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
897 Coding Systems}). |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
898 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
899 @strong{Warning:} Coding systems such as @code{undecided} which |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
900 determine the coding system from the data do not work entirely reliably |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
901 with asynchronous subprocess output. This is because Emacs has to |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
902 process asynchronous subprocess output in batches, as it arrives. Emacs |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
903 must try to detect the proper coding system from one batch at a time, |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
904 and this does not always work. Therefore, if at all possible, use a |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
905 coding system which determines both the character code conversion and |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
906 the end of line conversion---that is, one like @code{latin-1-unix}, |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
907 rather than @code{undecided} or @code{latin-1}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
908 |
6558 | 909 @menu |
910 * Process Buffers:: If no filter, output is put in a buffer. | |
911 * Filter Functions:: Filter functions accept output from the process. | |
912 * Accepting Output:: Explicitly permitting subprocess output. | |
913 Waiting for subprocess output. | |
914 @end menu | |
915 | |
916 @node Process Buffers | |
917 @subsection Process Buffers | |
918 | |
919 A process can (and usually does) have an @dfn{associated buffer}, | |
920 which is an ordinary Emacs buffer that is used for two purposes: storing | |
921 the output from the process, and deciding when to kill the process. You | |
922 can also use the buffer to identify a process to operate on, since in | |
923 normal practice only one process is associated with any given buffer. | |
924 Many applications of processes also use the buffer for editing input to | |
925 be sent to the process, but this is not built into Emacs Lisp. | |
926 | |
927 Unless the process has a filter function (@pxref{Filter Functions}), | |
928 its output is inserted in the associated buffer. The position to insert | |
9009 | 929 the output is determined by the @code{process-mark}, which is then |
930 updated to point to the end of the text just inserted. Usually, but not | |
931 always, the @code{process-mark} is at the end of the buffer. | |
6558 | 932 |
933 @defun process-buffer process | |
934 This function returns the associated buffer of the process | |
935 @var{process}. | |
936 | |
937 @smallexample | |
938 @group | |
939 (process-buffer (get-process "shell")) | |
940 @result{} #<buffer *shell*> | |
941 @end group | |
942 @end smallexample | |
943 @end defun | |
944 | |
945 @defun process-mark process | |
946 This function returns the process marker for @var{process}, which is the | |
947 marker that says where to insert output from the process. | |
948 | |
949 If @var{process} does not have a buffer, @code{process-mark} returns a | |
950 marker that points nowhere. | |
951 | |
952 Insertion of process output in a buffer uses this marker to decide where | |
953 to insert, and updates it to point after the inserted text. That is why | |
954 successive batches of output are inserted consecutively. | |
955 | |
956 Filter functions normally should use this marker in the same fashion | |
957 as is done by direct insertion of output in the buffer. A good | |
958 example of a filter function that uses @code{process-mark} is found at | |
959 the end of the following section. | |
960 | |
961 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
|
962 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
|
963 from previous output. |
6558 | 964 @end defun |
965 | |
966 @defun set-process-buffer process buffer | |
967 This function sets the buffer associated with @var{process} to | |
968 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes | |
969 associated with no buffer. | |
970 @end defun | |
971 | |
972 @defun get-buffer-process buffer-or-name | |
973 This function returns the process associated with @var{buffer-or-name}. | |
974 If there are several processes associated with it, then one is chosen. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
975 (Currently, the one chosen is the one most recently created.) It is |
6558 | 976 usually a bad idea to have more than one process associated with the |
977 same buffer. | |
978 | |
979 @smallexample | |
980 @group | |
981 (get-buffer-process "*shell*") | |
982 @result{} #<process shell> | |
983 @end group | |
984 @end smallexample | |
985 | |
986 Killing the process's buffer deletes the process, which kills the | |
987 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). | |
988 @end defun | |
989 | |
990 @node Filter Functions | |
991 @subsection Process Filter Functions | |
992 @cindex filter function | |
993 @cindex process filter | |
994 | |
995 A process @dfn{filter function} is a function that receives the | |
996 standard output from the associated process. If a process has a filter, | |
9009 | 997 then @emph{all} output from that process is passed to the filter. The |
998 process buffer is used directly for output from the process only when | |
999 there is no filter. | |
6558 | 1000 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1001 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
|
1002 something, because process output arrives only at such times. Emacs |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1003 waits when reading terminal input, in @code{sit-for} and |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1004 @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
|
1005 (@pxref{Accepting Output}). |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1006 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1007 A filter function must accept two arguments: the associated process |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1008 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
|
1009 then free to do whatever it chooses with the output. |
6558 | 1010 |
1011 Quitting is normally inhibited within a filter function---otherwise, | |
1012 the effect of typing @kbd{C-g} at command level or to quit a user | |
1013 command would be unpredictable. If you want to permit quitting inside a | |
1014 filter function, bind @code{inhibit-quit} to @code{nil}. | |
1015 @xref{Quitting}. | |
1016 | |
12067 | 1017 If an error happens during execution of a filter function, it is |
1018 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
|
1019 program was running when the filter function was started. However, if |
12067 | 1020 @code{debug-on-error} is non-@code{nil}, the error-catching is turned |
1021 off. This makes it possible to use the Lisp debugger to debug the | |
1022 filter function. @xref{Debugger}. | |
1023 | |
6558 | 1024 Many filter functions sometimes or always insert the text in the |
1025 process's buffer, mimicking the actions of Emacs when there is no | |
1026 filter. Such filter functions need to use @code{set-buffer} in order to | |
1027 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
|
1028 semipermanently, these filter functions must save and restore the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1029 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
|
1030 cases update the value of point. Here is how to do these things: |
6558 | 1031 |
1032 @smallexample | |
1033 @group | |
1034 (defun ordinary-insertion-filter (proc string) | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1035 (with-current-buffer (process-buffer proc) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1036 (let ((moving (= (point) (process-mark proc)))) |
6558 | 1037 @end group |
1038 @group | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1039 (save-excursion |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1040 ;; @r{Insert the text, advancing the process marker.} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1041 (goto-char (process-mark proc)) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1042 (insert string) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1043 (set-marker (process-mark proc) (point))) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1044 (if moving (goto-char (process-mark proc)))))) |
6558 | 1045 @end group |
1046 @end smallexample | |
1047 | |
1048 @noindent | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1049 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
|
1050 @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
|
1051 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
|
1052 @code{goto-char}. |
6558 | 1053 |
1054 To make the filter force the process buffer to be visible whenever new | |
1055 text arrives, insert the following line just before the | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1056 @code{with-current-buffer} construct: |
6558 | 1057 |
1058 @smallexample | |
1059 (display-buffer (process-buffer proc)) | |
1060 @end smallexample | |
1061 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1062 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
|
1063 previously, eliminate the variable @code{moving} and call |
6558 | 1064 @code{goto-char} unconditionally. |
1065 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1066 In earlier Emacs versions, every filter function that did regular |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1067 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
|
1068 match data. Now Emacs does this automatically for filter functions; |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1069 they never need to do it explicitly. @xref{Match Data}. |
6558 | 1070 |
1071 A filter function that writes the output into the buffer of the | |
12098 | 1072 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
|
1073 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
|
1074 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1075 if the buffer is dead. |
6558 | 1076 |
1077 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
|
1078 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
|
1079 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
|
1080 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
|
1081 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
|
1082 or more batches of output. |
6558 | 1083 |
1084 @defun set-process-filter process filter | |
1085 This function gives @var{process} the filter function @var{filter}. If | |
1086 @var{filter} is @code{nil}, it gives the process no filter. | |
1087 @end defun | |
1088 | |
1089 @defun process-filter process | |
1090 This function returns the filter function of @var{process}, or @code{nil} | |
1091 if it has none. | |
1092 @end defun | |
1093 | |
1094 Here is an example of use of a filter function: | |
1095 | |
1096 @smallexample | |
1097 @group | |
1098 (defun keep-output (process output) | |
1099 (setq kept (cons output kept))) | |
1100 @result{} keep-output | |
1101 @end group | |
1102 @group | |
1103 (setq kept nil) | |
1104 @result{} nil | |
1105 @end group | |
1106 @group | |
1107 (set-process-filter (get-process "shell") 'keep-output) | |
1108 @result{} keep-output | |
1109 @end group | |
1110 @group | |
1111 (process-send-string "shell" "ls ~/other\n") | |
1112 @result{} nil | |
1113 kept | |
1114 @result{} ("lewis@@slug[8] % " | |
1115 @end group | |
1116 @group | |
1117 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ | |
1118 address.txt backup.psf kolstad.psf | |
1119 backup.bib~ david.mss resume-Dec-86.mss~ | |
1120 backup.err david.psf resume-Dec.psf | |
1121 backup.mss dland syllabus.mss | |
1122 " | |
1123 "#backups.mss# backup.mss~ kolstad.mss | |
1124 ") | |
1125 @end group | |
1126 @end smallexample | |
1127 | |
1128 @ignore @c The code in this example doesn't show the right way to do things. | |
1129 Here is another, more realistic example, which demonstrates how to use | |
1130 the process mark to do insertion in the same fashion as is done when | |
1131 there is no filter function: | |
1132 | |
1133 @smallexample | |
1134 @group | |
1135 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}} | |
1136 ;; @r{and make sure that buffer is shown in some window.} | |
1137 (defun my-process-filter (proc str) | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1138 (let ((cur (selected-window)) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1139 (pop-up-windows t)) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1140 (pop-to-buffer my-shell-buffer) |
6558 | 1141 @end group |
1142 @group | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1143 (goto-char (point-max)) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1144 (insert str) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1145 (set-marker (process-mark proc) (point-max)) |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1146 (select-window cur))) |
6558 | 1147 @end group |
1148 @end smallexample | |
1149 @end ignore | |
1150 | |
1151 @node Accepting Output | |
1152 @subsection Accepting Output from Processes | |
1153 | |
1154 Output from asynchronous subprocesses normally arrives only while | |
1155 Emacs is waiting for some sort of external event, such as elapsed time | |
1156 or terminal input. Occasionally it is useful in a Lisp program to | |
1157 explicitly permit output to arrive at a specific point, or even to wait | |
1158 until output arrives from a process. | |
1159 | |
1160 @defun accept-process-output &optional process seconds millisec | |
1161 This function allows Emacs to read pending output from processes. The | |
1162 output is inserted in the associated buffers or given to their filter | |
1163 functions. If @var{process} is non-@code{nil} then this function does | |
1164 not return until some output has been received from @var{process}. | |
1165 | |
1166 @c Emacs 19 feature | |
1167 The arguments @var{seconds} and @var{millisec} let you specify timeout | |
1168 periods. The former specifies a period measured in seconds and the | |
1169 latter specifies one measured in milliseconds. The two time periods | |
1170 thus specified are added together, and @code{accept-process-output} | |
1171 returns after that much time whether or not there has been any | |
1172 subprocess output. | |
1173 | |
12098 | 1174 The argument @var{seconds} need not be an integer. If it is a floating |
1175 point number, this function waits for a fractional number of seconds. | |
1176 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
|
1177 @var{seconds} is rounded down. |
12098 | 1178 |
6558 | 1179 Not all operating systems support waiting periods other than multiples |
1180 of a second; on those that do not, you get an error if you specify | |
1181 nonzero @var{millisec}. | |
1182 | |
1183 The function @code{accept-process-output} returns non-@code{nil} if it | |
1184 did get some output, or @code{nil} if the timeout expired before output | |
1185 arrived. | |
1186 @end defun | |
1187 | |
1188 @node Sentinels | |
1189 @section Sentinels: Detecting Process Status Changes | |
1190 @cindex process sentinel | |
1191 @cindex sentinel | |
1192 | |
1193 A @dfn{process sentinel} is a function that is called whenever the | |
1194 associated process changes status for any reason, including signals | |
1195 (whether sent by Emacs or caused by the process's own actions) that | |
1196 terminate, stop, or continue the process. The process sentinel is also | |
1197 called if the process exits. The sentinel receives two arguments: the | |
1198 process for which the event occurred, and a string describing the type | |
1199 of event. | |
1200 | |
1201 The string describing the event looks like one of the following: | |
1202 | |
1203 @itemize @bullet | |
1204 @item | |
1205 @code{"finished\n"}. | |
1206 | |
1207 @item | |
1208 @code{"exited abnormally with code @var{exitcode}\n"}. | |
1209 | |
1210 @item | |
1211 @code{"@var{name-of-signal}\n"}. | |
1212 | |
1213 @item | |
1214 @code{"@var{name-of-signal} (core dumped)\n"}. | |
1215 @end itemize | |
1216 | |
1217 A sentinel runs only while Emacs is waiting (e.g., for terminal input, | |
1218 or for time to elapse, or for process output). This avoids the timing | |
1219 errors that could result from running them at random places in the | |
1220 middle of other Lisp programs. A program can wait, so that sentinels | |
9009 | 1221 will run, by calling @code{sit-for} or @code{sleep-for} |
1222 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1223 Output}). Emacs also allows sentinels to run when the command loop is |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1224 reading input. |
6558 | 1225 |
1226 Quitting is normally inhibited within a sentinel---otherwise, the | |
1227 effect of typing @kbd{C-g} at command level or to quit a user command | |
1228 would be unpredictable. If you want to permit quitting inside a | |
1229 sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}. | |
1230 | |
1231 A sentinel that writes the output into the buffer of the process | |
12098 | 1232 should check whether the buffer is still alive. If it tries to insert |
6558 | 1233 into a dead buffer, it will get an error. If the buffer is dead, |
1234 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. | |
1235 | |
12067 | 1236 If an error happens during execution of a sentinel, it is caught |
1237 automatically, so that it doesn't stop the execution of whatever | |
1238 programs was running when the sentinel was started. However, if | |
1239 @code{debug-on-error} is non-@code{nil}, the error-catching is turned | |
1240 off. This makes it possible to use the Lisp debugger to debug the | |
1241 sentinel. @xref{Debugger}. | |
1242 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1243 In earlier Emacs versions, every sentinel that did regular expression |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1244 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
|
1245 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
|
1246 it explicitly. @xref{Match Data}. |
12098 | 1247 |
6558 | 1248 @defun set-process-sentinel process sentinel |
1249 This function associates @var{sentinel} with @var{process}. If | |
1250 @var{sentinel} is @code{nil}, then the process will have no sentinel. | |
1251 The default behavior when there is no sentinel is to insert a message in | |
1252 the process's buffer when the process status changes. | |
1253 | |
1254 @smallexample | |
1255 @group | |
1256 (defun msg-me (process event) | |
1257 (princ | |
1258 (format "Process: %s had the event `%s'" process event))) | |
1259 (set-process-sentinel (get-process "shell") 'msg-me) | |
1260 @result{} msg-me | |
1261 @end group | |
1262 @group | |
1263 (kill-process (get-process "shell")) | |
1264 @print{} Process: #<process shell> had the event `killed' | |
1265 @result{} #<process shell> | |
1266 @end group | |
1267 @end smallexample | |
1268 @end defun | |
1269 | |
1270 @defun process-sentinel process | |
1271 This function returns the sentinel of @var{process}, or @code{nil} if it | |
1272 has none. | |
1273 @end defun | |
1274 | |
1275 @defun waiting-for-user-input-p | |
1276 While a sentinel or filter function is running, this function returns | |
1277 non-@code{nil} if Emacs was waiting for keyboard input from the user at | |
1278 the time the sentinel or filter function was called, @code{nil} if it | |
1279 was not. | |
1280 @end defun | |
1281 | |
1282 @node Transaction Queues | |
1283 @section Transaction Queues | |
1284 @cindex transaction queue | |
1285 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1286 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
|
1287 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
|
1288 queue communicating with a specified process. Then you can call |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
17611
diff
changeset
|
1289 @code{tq-enqueue} to send a transaction. |
6558 | 1290 |
1291 @defun tq-create process | |
1292 This function creates and returns a transaction queue communicating with | |
1293 @var{process}. The argument @var{process} should be a subprocess | |
1294 capable of sending and receiving streams of bytes. It may be a child | |
9009 | 1295 process, or it may be a TCP connection to a server, possibly on another |
6558 | 1296 machine. |
1297 @end defun | |
1298 | |
1299 @defun tq-enqueue queue question regexp closure fn | |
1300 This function sends a transaction to queue @var{queue}. Specifying the | |
1301 queue has the effect of specifying the subprocess to talk to. | |
1302 | |
9009 | 1303 The argument @var{question} is the outgoing message that starts the |
6558 | 1304 transaction. The argument @var{fn} is the function to call when the |
1305 corresponding answer comes back; it is called with two arguments: | |
1306 @var{closure}, and the answer received. | |
1307 | |
1308 The argument @var{regexp} is a regular expression that should match the | |
1309 entire answer, but nothing less; that's how @code{tq-enqueue} determines | |
1310 where the answer ends. | |
1311 | |
1312 The return value of @code{tq-enqueue} itself is not meaningful. | |
1313 @end defun | |
1314 | |
1315 @defun tq-close queue | |
1316 Shut down transaction queue @var{queue}, waiting for all pending transactions | |
1317 to complete, and then terminate the connection or child process. | |
1318 @end defun | |
1319 | |
1320 Transaction queues are implemented by means of a filter function. | |
1321 @xref{Filter Functions}. | |
1322 | |
12098 | 1323 @node Network |
1324 @section Network Connections | |
1325 @cindex network connection | |
6558 | 1326 @cindex TCP |
1327 | |
12098 | 1328 Emacs Lisp programs can open TCP network connections to other processes on |
1329 the same machine or other machines. A network connection is handled by Lisp | |
6558 | 1330 much like a subprocess, and is represented by a process object. |
1331 However, the process you are communicating with is not a child of the | |
1332 Emacs process, so you can't kill it or send it signals. All you can do | |
1333 is send and receive data. @code{delete-process} closes the connection, | |
1334 but does not kill the process at the other end; that process must decide | |
1335 what to do about closure of the connection. | |
1336 | |
1337 You can distinguish process objects representing network connections | |
1338 from those representing subprocesses with the @code{process-status} | |
12098 | 1339 function. It always returns either @code{open} or @code{closed} for a |
1340 network connection, and it never returns either of those values for a | |
1341 real subprocess. @xref{Process Information}. | |
6558 | 1342 |
1343 @defun open-network-stream name buffer-or-name host service | |
1344 This function opens a TCP connection for a service to a host. It | |
1345 returns a process object to represent the connection. | |
1346 | |
1347 The @var{name} argument specifies the name for the process object. It | |
1348 is modified as necessary to make it unique. | |
1349 | |
1350 The @var{buffer-or-name} argument is the buffer to associate with the | |
1351 connection. Output from the connection is inserted in the buffer, | |
1352 unless you specify a filter function to handle the output. If | |
1353 @var{buffer-or-name} is @code{nil}, it means that the connection is not | |
1354 associated with any buffer. | |
1355 | |
1356 The arguments @var{host} and @var{service} specify where to connect to; | |
1357 @var{host} is the host name (a string), and @var{service} is the name of | |
1358 a defined network service (a string) or a port number (an integer). | |
1359 @end defun |