2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/processes
7 @node Processes, Display, Abbrevs, Top
10 @cindex parent process
14 In the terminology of operating systems, a @dfn{process} is a space in
15 which a program can execute. Emacs runs in a process. Emacs Lisp
16 programs can invoke other programs in processes of their own. These are
17 called @dfn{subprocesses} or @dfn{child processes} of the Emacs process,
18 which is their @dfn{parent process}.
20 A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous},
21 depending on how it is created. When you create a synchronous
22 subprocess, the Lisp program waits for the subprocess to terminate
23 before continuing execution. When you create an asynchronous
24 subprocess, it can run in parallel with the Lisp program. This kind of
25 subprocess is represented within Emacs by a Lisp object which is also
26 called a ``process''. Lisp programs can use this object to communicate
27 with the subprocess or to control it. For example, you can send
28 signals, obtain status information, receive output from the process, or
31 @defun processp object
32 This function returns @code{t} if @var{object} is a process,
37 * Subprocess Creation:: Functions that start subprocesses.
38 * Shell Arguments:: Quoting an argument to pass it to a shell.
39 * Synchronous Processes:: Details of using synchronous subprocesses.
40 * Asynchronous Processes:: Starting up an asynchronous subprocess.
41 * Deleting Processes:: Eliminating an asynchronous subprocess.
42 * Process Information:: Accessing run-status and other attributes.
43 * Input to Processes:: Sending input to an asynchronous subprocess.
44 * Signals to Processes:: Stopping, continuing or interrupting
45 an asynchronous subprocess.
46 * Output from Processes:: Collecting output from an asynchronous subprocess.
47 * Sentinels:: Sentinels run when process run-status changes.
48 * Query Before Exit:: Whether to query if exiting will kill a process.
49 * Transaction Queues:: Transaction-based communication with subprocesses.
50 * Network:: Opening network connections.
53 @node Subprocess Creation
54 @section Functions that Create Subprocesses
56 There are three functions that create a new subprocess in which to run
57 a program. One of them, @code{start-process}, creates an asynchronous
58 process and returns a process object (@pxref{Asynchronous Processes}).
59 The other two, @code{call-process} and @code{call-process-region},
60 create a synchronous process and do not return a process object
61 (@pxref{Synchronous Processes}).
63 Synchronous and asynchronous processes are explained in the following
64 sections. Since the three functions are all called in a similar
65 fashion, their common arguments are described here.
67 @cindex execute program
68 @cindex @code{PATH} environment variable
69 @cindex @code{HOME} environment variable
70 In all cases, the function's @var{program} argument specifies the
71 program to be run. An error is signaled if the file is not found or
72 cannot be executed. If the file name is relative, the variable
73 @code{exec-path} contains a list of directories to search. Emacs
74 initializes @code{exec-path} when it starts up, based on the value of
75 the environment variable @code{PATH}. The standard file name
76 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usual
77 in @code{exec-path}, but environment variable substitutions
78 (@samp{$HOME}, etc.) are not recognized; use
79 @code{substitute-in-file-name} to perform them (@pxref{File Name
82 Executing a program can also try adding suffixes to the specified
86 This variable is a list of suffixes (strings) to try adding to the
87 specified program file name. The list should include @code{""} if you
88 want the name to be tried exactly as specified. The default value is
92 Each of the subprocess-creating functions has a @var{buffer-or-name}
93 argument which specifies where the standard output from the program will
94 go. It should be a buffer or a buffer name; if it is a buffer name,
95 that will create the buffer if it does not already exist. It can also
96 be @code{nil}, which says to discard the output unless a filter function
97 handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
98 Normally, you should avoid having multiple processes send output to the
99 same buffer because their output would be intermixed randomly.
101 @cindex program arguments
102 All three of the subprocess-creating functions have a @code{&rest}
103 argument, @var{args}. The @var{args} must all be strings, and they are
104 supplied to @var{program} as separate command line arguments. Wildcard
105 characters and other shell constructs have no special meanings in these
106 strings, since the whole strings are passed directly to the specified
109 @strong{Please note:} The argument @var{program} contains only the
110 name of the program; it may not contain any command-line arguments. You
111 must use @var{args} to provide those.
113 The subprocess gets its current directory from the value of
114 @code{default-directory} (@pxref{File Name Expansion}).
116 @cindex environment variables, subprocesses
117 The subprocess inherits its environment from Emacs, but you can
118 specify overrides for it with @code{process-environment}. @xref{System
121 @defvar exec-directory
123 The value of this variable is a string, the name of a directory that
124 contains programs that come with GNU Emacs, programs intended for Emacs
125 to invoke. The program @code{movemail} is an example of such a program;
126 Rmail uses it to fetch new mail from an inbox.
130 The value of this variable is a list of directories to search for
131 programs to run in subprocesses. Each element is either the name of a
132 directory (i.e., a string), or @code{nil}, which stands for the default
133 directory (which is the value of @code{default-directory}).
134 @cindex program directories
136 The value of @code{exec-path} is used by @code{call-process} and
137 @code{start-process} when the @var{program} argument is not an absolute
141 @node Shell Arguments
142 @section Shell Arguments
144 Lisp programs sometimes need to run a shell and give it a command
145 that contains file names that were specified by the user. These
146 programs ought to be able to support any valid file name. But the shell
147 gives special treatment to certain characters, and if these characters
148 occur in the file name, they will confuse the shell. To handle these
149 characters, use the function @code{shell-quote-argument}:
151 @defun shell-quote-argument argument
152 This function returns a string which represents, in shell syntax,
153 an argument whose actual contents are @var{argument}. It should
154 work reliably to concatenate the return value into a shell command
155 and then pass it to a shell for execution.
157 Precisely what this function does depends on your operating system. The
158 function is designed to work with the syntax of your system's standard
159 shell; if you use an unusual shell, you will need to redefine this
163 ;; @r{This example shows the behavior on GNU and Unix systems.}
164 (shell-quote-argument "foo > bar")
165 @result{} "foo\\ \\>\\ bar"
167 ;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.}
168 (shell-quote-argument "foo > bar")
169 @result{} "\"foo > bar\""
172 Here's an example of using @code{shell-quote-argument} to construct
177 (shell-quote-argument oldfile)
179 (shell-quote-argument newfile))
183 @node Synchronous Processes
184 @section Creating a Synchronous Process
185 @cindex synchronous subprocess
187 After a @dfn{synchronous process} is created, Emacs waits for the
188 process to terminate before continuing. Starting Dired on GNU or
189 Unix@footnote{On other systems, Emacs uses a Lisp emulation of
190 @code{ls}; see @ref{Contents of Directories}.} is an example of this: it
191 runs @code{ls} in a synchronous process, then modifies the output
192 slightly. Because the process is synchronous, the entire directory
193 listing arrives in the buffer before Emacs tries to do anything with it.
195 While Emacs waits for the synchronous subprocess to terminate, the
196 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
197 the subprocess with a @code{SIGINT} signal; but it waits until the
198 subprocess actually terminates before quitting. If during that time the
199 user types another @kbd{C-g}, that kills the subprocess instantly with
200 @code{SIGKILL} and quits immediately (except on MS-DOS, where killing
201 other processes doesn't work). @xref{Quitting}.
203 The synchronous subprocess functions return an indication of how the
206 The output from a synchronous subprocess is generally decoded using a
207 coding system, much like text read from a file. The input sent to a
208 subprocess by @code{call-process-region} is encoded using a coding
209 system, much like text written into a file. @xref{Coding Systems}.
211 @defun call-process program &optional infile destination display &rest args
212 This function calls @var{program} in a separate process and waits for
215 The standard input for the process comes from file @var{infile} if
216 @var{infile} is not @code{nil}, and from the null device otherwise.
217 The argument @var{destination} says where to put the process output.
218 Here are the possibilities:
222 Insert the output in that buffer, before point. This includes both the
223 standard output stream and the standard error stream of the process.
226 Insert the output in a buffer with that name, before point.
229 Insert the output in the current buffer, before point.
235 Discard the output, and return @code{nil} immediately without waiting
236 for the subprocess to finish.
238 In this case, the process is not truly synchronous, since it can run in
239 parallel with Emacs; but you can think of it as synchronous in that
240 Emacs is essentially finished with the subprocess as soon as this
243 MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
246 @item @code{(@var{real-destination} @var{error-destination})}
247 Keep the standard output stream separate from the standard error stream;
248 deal with the ordinary output as specified by @var{real-destination},
249 and dispose of the error output according to @var{error-destination}.
250 If @var{error-destination} is @code{nil}, that means to discard the
251 error output, @code{t} means mix it with the ordinary output, and a
252 string specifies a file name to redirect error output into.
254 You can't directly specify a buffer to put the error output in; that is
255 too difficult to implement. But you can achieve this result by sending
256 the error output to a temporary file and then inserting the file into a
260 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
261 the buffer as output is inserted. (However, if the coding system chosen
262 for decoding output is @code{undecided}, meaning deduce the encoding
263 from the actual data, then redisplay sometimes cannot continue once
264 non-@sc{ascii} characters are encountered. There are fundamental
265 reasons why it is hard to fix this; see @ref{Output from Processes}.)
267 Otherwise the function @code{call-process} does no redisplay, and the
268 results become visible on the screen only when Emacs redisplays that
269 buffer in the normal course of events.
271 The remaining arguments, @var{args}, are strings that specify command
272 line arguments for the program.
274 The value returned by @code{call-process} (unless you told it not to
275 wait) indicates the reason for process termination. A number gives the
276 exit status of the subprocess; 0 means success, and any other value
277 means failure. If the process terminated with a signal,
278 @code{call-process} returns a string describing the signal.
280 In the examples below, the buffer @samp{foo} is current.
284 (call-process "pwd" nil t)
287 ---------- Buffer: foo ----------
288 /usr/user/lewis/manual
289 ---------- Buffer: foo ----------
293 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
296 ---------- Buffer: bar ----------
297 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
299 ---------- Buffer: bar ----------
303 Here is a good example of the use of @code{call-process}, which used to
304 be found in the definition of @code{insert-directory}:
308 (call-process insert-directory-program nil t nil @var{switches}
310 (concat (file-name-as-directory file) ".")
316 @defun call-process-region start end program &optional delete destination display &rest args
317 This function sends the text from @var{start} to @var{end} as
318 standard input to a process running @var{program}. It deletes the text
319 sent if @var{delete} is non-@code{nil}; this is useful when
320 @var{destination} is @code{t}, to insert the output in the current
321 buffer in place of the input.
323 The arguments @var{destination} and @var{display} control what to do
324 with the output from the subprocess, and whether to update the display
325 as it comes in. For details, see the description of
326 @code{call-process}, above. If @var{destination} is the integer 0,
327 @code{call-process-region} discards the output and returns @code{nil}
328 immediately, without waiting for the subprocess to finish (this only
329 works if asynchronous subprocesses are supported).
331 The remaining arguments, @var{args}, are strings that specify command
332 line arguments for the program.
334 The return value of @code{call-process-region} is just like that of
335 @code{call-process}: @code{nil} if you told it to return without
336 waiting; otherwise, a number or string which indicates how the
337 subprocess terminated.
339 In the following example, we use @code{call-process-region} to run the
340 @code{cat} utility, with standard input being the first five characters
341 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
342 standard input into its standard output. Since the argument
343 @var{destination} is @code{t}, this output is inserted in the current
348 ---------- Buffer: foo ----------
350 ---------- Buffer: foo ----------
354 (call-process-region 1 6 "cat" nil t)
357 ---------- Buffer: foo ----------
359 ---------- Buffer: foo ----------
363 The @code{shell-command-on-region} command uses
364 @code{call-process-region} like this:
370 shell-file-name ; @r{Name of program.}
371 nil ; @r{Do not delete region.}
372 buffer ; @r{Send output to @code{buffer}.}
373 nil ; @r{No redisplay during output.}
374 "-c" command) ; @r{Arguments for the shell.}
379 @defun shell-command-to-string command
380 This function executes @var{command} (a string) as a shell command,
381 then returns the command's output as a string.
384 @node Asynchronous Processes
385 @section Creating an Asynchronous Process
386 @cindex asynchronous subprocess
388 After an @dfn{asynchronous process} is created, Emacs and the subprocess
389 both continue running immediately. The process thereafter runs
390 in parallel with Emacs, and the two can communicate with each other
391 using the functions described in the following sections. However,
392 communication is only partially asynchronous: Emacs sends data to the
393 process only when certain functions are called, and Emacs accepts data
394 from the process only when Emacs is waiting for input or for a time
397 Here we describe how to create an asynchronous process.
399 @defun start-process name buffer-or-name program &rest args
400 This function creates a new asynchronous subprocess and starts the
401 program @var{program} running in it. It returns a process object that
402 stands for the new subprocess in Lisp. The argument @var{name}
403 specifies the name for the process object; if a process with this name
404 already exists, then @var{name} is modified (by appending @samp{<1>},
405 etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to
406 associate with the process.
408 The remaining arguments, @var{args}, are strings that specify command
409 line arguments for the program.
411 In the example below, the first process is started and runs (rather,
412 sleeps) for 100 seconds. Meanwhile, the second process is started, and
413 given the name @samp{my-process<1>} for the sake of uniqueness. It
414 inserts the directory listing at the end of the buffer @samp{foo},
415 before the first process finishes. Then it finishes, and a message to
416 that effect is inserted in the buffer. Much later, the first process
417 finishes, and another message is inserted in the buffer for it.
421 (start-process "my-process" "foo" "sleep" "100")
422 @result{} #<process my-process>
426 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
427 @result{} #<process my-process<1>>
429 ---------- Buffer: foo ----------
431 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
432 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
434 Process my-process<1> finished
436 Process my-process finished
437 ---------- Buffer: foo ----------
442 @defun start-process-shell-command name buffer-or-name command &rest command-args
443 This function is like @code{start-process} except that it uses a shell
444 to execute the specified command. The argument @var{command} is a shell
445 command name, and @var{command-args} are the arguments for the shell
446 command. The variable @code{shell-file-name} specifies which shell to
449 The point of running a program through the shell, rather than directly
450 with @code{start-process}, is so that you can employ shell features such
451 as wildcards in the arguments. It follows that if you include an
452 arbitrary user-specified arguments in the command, you should quote it
453 with @code{shell-quote-argument} first, so that any special shell
454 characters do @emph{not} have their special shell meanings. @xref{Shell
458 @defvar process-connection-type
461 This variable controls the type of device used to communicate with
462 asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are
463 used, when available. Otherwise, pipes are used.
465 @sc{pty}s are usually preferable for processes visible to the user, as
466 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
467 etc.) to work between the process and its children, whereas pipes do
468 not. For subprocesses used for internal purposes by programs, it is
469 often better to use a pipe, because they are more efficient. In
470 addition, the total number of @sc{pty}s is limited on many systems and
471 it is good not to waste them.
473 The value of @code{process-connection-type} takes effect when
474 @code{start-process} is called. So you can specify how to communicate
475 with one subprocess by binding the variable around the call to
476 @code{start-process}.
480 (let ((process-connection-type nil)) ; @r{Use a pipe.}
481 (start-process @dots{}))
485 To determine whether a given subprocess actually got a pipe or a
486 @sc{pty}, use the function @code{process-tty-name} (@pxref{Process
490 @node Deleting Processes
491 @section Deleting Processes
492 @cindex deleting processes
494 @dfn{Deleting a process} disconnects Emacs immediately from the
495 subprocess. Processes are deleted automatically after they terminate,
496 but not necessarily right away. You can delete a process explicitly
497 at any time. If you delete a terminated process explicitly before it
498 is deleted automatically, no harm results. Deletion of a running
499 process sends a signal to terminate it (and its child processes if
500 any), and calls the process sentinel if it has one.
502 @code{get-buffer-process} and @code{process-list} do not remember a
503 deleted process, but the process object itself continues to exist as
504 long as other Lisp objects point to it. All the Lisp primitives that
505 work on process objects accept deleted processes, but those that do
506 I/O or send signals will report an error. The process mark continues
507 to point to the same place as before, usually into a buffer where
508 output from the process was being inserted.
510 @defopt delete-exited-processes
511 This variable controls automatic deletion of processes that have
512 terminated (due to calling @code{exit} or to a signal). If it is
513 @code{nil}, then they continue to exist until the user runs
514 @code{list-processes}. Otherwise, they are deleted immediately after
518 @defun delete-process name
519 This function deletes the process associated with @var{name}, killing
520 it with a @code{SIGKILL} signal. The argument @var{name} may be a
521 process, the name of a process, a buffer, or the name of a buffer.
522 Calling @code{delete-process} on a running process terminates it,
523 updates the process status, and runs the sentinel (if any) immediately.
524 If the process has already terminated, calling @code{delete-process}
525 has no effect on its status, or on the running of its sentinel (which
526 will happen sooner or later).
530 (delete-process "*shell*")
536 @node Process Information
537 @section Process Information
539 Several functions return information about processes.
540 @code{list-processes} is provided for interactive use.
542 @deffn Command list-processes
543 This command displays a listing of all living processes. In addition,
544 it finally deletes any process whose status was @samp{Exited} or
545 @samp{Signaled}. It returns @code{nil}.
549 This function returns a list of all processes that have not been deleted.
554 @result{} (#<process display-time> #<process shell>)
559 @defun get-process name
560 This function returns the process named @var{name}, or @code{nil} if
561 there is none. An error is signaled if @var{name} is not a string.
565 (get-process "shell")
566 @result{} #<process shell>
571 @defun process-command process
572 This function returns the command that was executed to start
573 @var{process}. This is a list of strings, the first string being the
574 program executed and the rest of the strings being the arguments that
575 were given to the program.
579 (process-command (get-process "shell"))
580 @result{} ("/bin/csh" "-i")
585 @defun process-id process
586 This function returns the @sc{pid} of @var{process}. This is an
587 integer that distinguishes the process @var{process} from all other
588 processes running on the same computer at the current time. The
589 @sc{pid} of a process is chosen by the operating system kernel when the
590 process is started and remains constant as long as the process exists.
593 @defun process-name process
594 This function returns the name of @var{process}.
597 @defun process-contact process
598 This function returns @code{t} for an ordinary child process, and
599 @code{(@var{hostname} @var{service})} for a net connection
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).
608 The possible values for an actual subprocess are:
612 for a process that is running.
614 for a process that is stopped but continuable.
616 for a process that has exited.
618 for a process that has received a fatal signal.
620 for a network connection that is open.
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.
626 if @var{process-name} is not the name of an existing process.
631 (process-status "shell")
635 (process-status (get-buffer "*shell*"))
640 @result{} #<process xx<1>>
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}.
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.
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}).
665 @defun process-coding-system process
666 This function returns a cons cell describing the coding systems in use
667 for decoding output from @var{process} and for encoding input to
668 @var{process} (@pxref{Coding Systems}). The value has this form:
671 (@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
675 @defun set-process-coding-system process decoding-system encoding-system
676 This function specifies the coding systems to use for subsequent output
677 from and input to @var{process}. It will use @var{decoding-system} to
678 decode subprocess output, and @var{encoding-system} to encode subprocess
682 @node Input to Processes
683 @section Sending Input to Processes
684 @cindex process input
686 Asynchronous subprocesses receive input when it is sent to them by
687 Emacs, which is done with the functions in this section. You must
688 specify the process to send input to, and the input data to send. The
689 data appears on the ``standard input'' of the subprocess.
691 Some operating systems have limited space for buffered input in a
692 @sc{pty}. On these systems, Emacs sends an @sc{eof} periodically amidst
693 the other characters, to force them through. For most programs,
694 these @sc{eof}s do no harm.
696 Subprocess input is normally encoded using a coding system before the
697 subprocess receives it, much like text written into a file. You can use
698 @code{set-process-coding-system} to specify which coding system to use
699 (@pxref{Process Information}). Otherwise, the coding system comes from
700 @code{coding-system-for-write}, if that is non-@code{nil}; or else from
701 the defaulting mechanism (@pxref{Default Coding Systems}).
703 Sometimes the system is unable to accept input for that process,
704 because the input buffer is full. When this happens, the send functions
705 wait a short while, accepting output from subprocesses, and then try
706 again. This gives the subprocess a chance to read more of its pending
707 input and make space in the buffer. It also allows filters, sentinels
708 and timers to run---so take account of that in writing your code.
710 @defun process-send-string process-name string
711 This function sends @var{process-name} the contents of @var{string} as
712 standard input. The argument @var{process-name} must be a process or
713 the name of a process. If it is @code{nil}, the current buffer's
716 The function returns @code{nil}.
720 (process-send-string "shell<1>" "ls\n")
726 ---------- Buffer: *shell* ----------
728 introduction.texi syntax-tables.texi~
729 introduction.texi~ text.texi
730 introduction.txt text.texi~
732 ---------- Buffer: *shell* ----------
737 @defun process-send-region process-name start end
738 This function sends the text in the region defined by @var{start} and
739 @var{end} as standard input to @var{process-name}, which is a process or
740 a process name. (If it is @code{nil}, the current buffer's process is
743 An error is signaled unless both @var{start} and @var{end} are
744 integers or markers that indicate positions in the current buffer. (It
745 is unimportant which number is larger.)
748 @defun process-send-eof &optional process-name
749 This function makes @var{process-name} see an end-of-file in its
750 input. The @sc{eof} comes after any text already sent to it.
752 If @var{process-name} is not supplied, or if it is @code{nil}, then
753 this function sends the @sc{eof} to the current buffer's process. An
754 error is signaled if the current buffer has no process.
756 The function returns @var{process-name}.
760 (process-send-eof "shell")
766 @defun process-running-child-p process
767 @tindex process-running-child-p process
768 This function will tell you whether a subprocess has given control of
769 its terminal to its own child process. The value is @code{t} if this is
770 true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
774 @node Signals to Processes
775 @section Sending Signals to Processes
776 @cindex process signals
777 @cindex sending signals
780 @dfn{Sending a signal} to a subprocess is a way of interrupting its
781 activities. There are several different signals, each with its own
782 meaning. The set of signals and their names is defined by the operating
783 system. For example, the signal @code{SIGINT} means that the user has
784 typed @kbd{C-c}, or that some analogous thing has happened.
786 Each signal has a standard effect on the subprocess. Most signals
787 kill the subprocess, but some stop or resume execution instead. Most
788 signals can optionally be handled by programs; if the program handles
789 the signal, then we can say nothing in general about its effects.
791 You can send signals explicitly by calling the functions in this
792 section. Emacs also sends signals automatically at certain times:
793 killing a buffer sends a @code{SIGHUP} signal to all its associated
794 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
795 processes. (@code{SIGHUP} is a signal that usually indicates that the
796 user hung up the phone.)
798 Each of the signal-sending functions takes two optional arguments:
799 @var{process-name} and @var{current-group}.
801 The argument @var{process-name} must be either a process, the name of
802 one, or @code{nil}. If it is @code{nil}, the process defaults to the
803 process associated with the current buffer. An error is signaled if
804 @var{process-name} does not identify a process.
806 The argument @var{current-group} is a flag that makes a difference
807 when you are running a job-control shell as an Emacs subprocess. If it
808 is non-@code{nil}, then the signal is sent to the current process-group
809 of the terminal that Emacs uses to communicate with the subprocess. If
810 the process is a job-control shell, this means the shell's current
811 subjob. If it is @code{nil}, the signal is sent to the process group of
812 the immediate subprocess of Emacs. If the subprocess is a job-control
813 shell, this is the shell itself.
815 The flag @var{current-group} has no effect when a pipe is used to
816 communicate with the subprocess, because the operating system does not
817 support the distinction in the case of pipes. For the same reason,
818 job-control shells won't work when a pipe is used. See
819 @code{process-connection-type} in @ref{Asynchronous Processes}.
821 @defun interrupt-process &optional process-name current-group
822 This function interrupts the process @var{process-name} by sending the
823 signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt
824 character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
825 others) sends this signal. When the argument @var{current-group} is
826 non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
827 on the terminal by which Emacs talks to the subprocess.
830 @defun kill-process &optional process-name current-group
831 This function kills the process @var{process-name} by sending the
832 signal @code{SIGKILL}. This signal kills the subprocess immediately,
833 and cannot be handled by the subprocess.
836 @defun quit-process &optional process-name current-group
837 This function sends the signal @code{SIGQUIT} to the process
838 @var{process-name}. This signal is the one sent by the ``quit
839 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
843 @defun stop-process &optional process-name current-group
844 This function stops the process @var{process-name} by sending the
845 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
848 Outside of Emacs, on systems with job control, the ``stop character''
849 (usually @kbd{C-z}) normally sends this signal. When
850 @var{current-group} is non-@code{nil}, you can think of this function as
851 ``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
855 @defun continue-process &optional process-name current-group
856 This function resumes execution of the process @var{process} by sending
857 it the signal @code{SIGCONT}. This presumes that @var{process-name} was
862 @defun signal-process pid signal
863 This function sends a signal to process @var{pid}, which need not be
864 a child of Emacs. The argument @var{signal} specifies which signal
865 to send; it should be an integer.
868 @node Output from Processes
869 @section Receiving Output from Processes
870 @cindex process output
871 @cindex output from processes
873 There are two ways to receive the output that a subprocess writes to
874 its standard output stream. The output can be inserted in a buffer,
875 which is called the associated buffer of the process, or a function
876 called the @dfn{filter function} can be called to act on the output. If
877 the process has no buffer and no filter function, its output is
880 When a subprocess terminates, Emacs reads any pending output,
881 then stops reading output from that subprocess. Therefore, if the
882 subprocess has children that are still live and still producing
883 output, Emacs won't receive that output.
885 Output from a subprocess can arrive only while Emacs is waiting: when
886 reading terminal input, in @code{sit-for} and @code{sleep-for}
887 (@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
888 Output}). This minimizes the problem of timing errors that usually
889 plague parallel programming. For example, you can safely create a
890 process and only then specify its buffer or filter function; no output
891 can arrive before you finish, if the code in between does not call any
892 primitive that waits.
894 It is impossible to separate the standard output and standard error
895 streams of the subprocess, because Emacs normally spawns the subprocess
896 inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If
897 you want to keep the output to those streams separate, you should
898 redirect one of them to a file--for example, by using an appropriate
901 Subprocess output is normally decoded using a coding system before the
902 buffer or filter function receives it, much like text read from a file.
903 You can use @code{set-process-coding-system} to specify which coding
904 system to use (@pxref{Process Information}). Otherwise, the coding
905 system comes from @code{coding-system-for-read}, if that is
906 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
909 @strong{Warning:} Coding systems such as @code{undecided} which
910 determine the coding system from the data do not work entirely reliably
911 with asynchronous subprocess output. This is because Emacs has to
912 process asynchronous subprocess output in batches, as it arrives. Emacs
913 must try to detect the proper coding system from one batch at a time,
914 and this does not always work. Therefore, if at all possible, use a
915 coding system which determines both the character code conversion and
916 the end of line conversion---that is, one like @code{latin-1-unix},
917 rather than @code{undecided} or @code{latin-1}.
920 * Process Buffers:: If no filter, output is put in a buffer.
921 * Filter Functions:: Filter functions accept output from the process.
922 * Accepting Output:: Explicitly permitting subprocess output.
923 Waiting for subprocess output.
926 @node Process Buffers
927 @subsection Process Buffers
929 A process can (and usually does) have an @dfn{associated buffer},
930 which is an ordinary Emacs buffer that is used for two purposes: storing
931 the output from the process, and deciding when to kill the process. You
932 can also use the buffer to identify a process to operate on, since in
933 normal practice only one process is associated with any given buffer.
934 Many applications of processes also use the buffer for editing input to
935 be sent to the process, but this is not built into Emacs Lisp.
937 Unless the process has a filter function (@pxref{Filter Functions}),
938 its output is inserted in the associated buffer. The position to insert
939 the output is determined by the @code{process-mark}, which is then
940 updated to point to the end of the text just inserted. Usually, but not
941 always, the @code{process-mark} is at the end of the buffer.
943 @defun process-buffer process
944 This function returns the associated buffer of the process
949 (process-buffer (get-process "shell"))
950 @result{} #<buffer *shell*>
955 @defun process-mark process
956 This function returns the process marker for @var{process}, which is the
957 marker that says where to insert output from the process.
959 If @var{process} does not have a buffer, @code{process-mark} returns a
960 marker that points nowhere.
962 Insertion of process output in a buffer uses this marker to decide where
963 to insert, and updates it to point after the inserted text. That is why
964 successive batches of output are inserted consecutively.
966 Filter functions normally should use this marker in the same fashion
967 as is done by direct insertion of output in the buffer. A good
968 example of a filter function that uses @code{process-mark} is found at
969 the end of the following section.
971 When the user is expected to enter input in the process buffer for
972 transmission to the process, the process marker separates the new input
973 from previous output.
976 @defun set-process-buffer process buffer
977 This function sets the buffer associated with @var{process} to
978 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
979 associated with no buffer.
982 @defun get-buffer-process buffer-or-name
983 This function returns a nondeleted process associated with the buffer
984 specified by @var{buffer-or-name}. If there are several processes
985 associated with it, this function chooses one (currently, the one most
986 recently created, but don't count on that). Deletion of a process
987 (see @code{delete-process}) makes it ineligible for this function to
990 It is usually a bad idea to have more than one process associated with
995 (get-buffer-process "*shell*")
996 @result{} #<process shell>
1000 Killing the process's buffer deletes the process, which kills the
1001 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
1004 @node Filter Functions
1005 @subsection Process Filter Functions
1006 @cindex filter function
1007 @cindex process filter
1009 A process @dfn{filter function} is a function that receives the
1010 standard output from the associated process. If a process has a filter,
1011 then @emph{all} output from that process is passed to the filter. The
1012 process buffer is used directly for output from the process only when
1015 The filter function can only be called when Emacs is waiting for
1016 something, because process output arrives only at such times. Emacs
1017 waits when reading terminal input, in @code{sit-for} and
1018 @code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
1019 (@pxref{Accepting Output}).
1021 A filter function must accept two arguments: the associated process
1022 and a string, which is output just received from it. The function is
1023 then free to do whatever it chooses with the output.
1025 Quitting is normally inhibited within a filter function---otherwise,
1026 the effect of typing @kbd{C-g} at command level or to quit a user
1027 command would be unpredictable. If you want to permit quitting inside a
1028 filter function, bind @code{inhibit-quit} to @code{nil}.
1031 If an error happens during execution of a filter function, it is
1032 caught automatically, so that it doesn't stop the execution of whatever
1033 program was running when the filter function was started. However, if
1034 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1035 off. This makes it possible to use the Lisp debugger to debug the
1036 filter function. @xref{Debugger}.
1038 Many filter functions sometimes or always insert the text in the
1039 process's buffer, mimicking the actions of Emacs when there is no
1040 filter. Such filter functions need to use @code{set-buffer} in order to
1041 be sure to insert in that buffer. To avoid setting the current buffer
1042 semipermanently, these filter functions must save and restore the
1043 current buffer. They should also update the process marker, and in some
1044 cases update the value of point. Here is how to do these things:
1048 (defun ordinary-insertion-filter (proc string)
1049 (with-current-buffer (process-buffer proc)
1050 (let ((moving (= (point) (process-mark proc))))
1054 ;; @r{Insert the text, advancing the process marker.}
1055 (goto-char (process-mark proc))
1057 (set-marker (process-mark proc) (point)))
1058 (if moving (goto-char (process-mark proc))))))
1063 The reason to use @code{with-current-buffer}, rather than using
1064 @code{save-excursion} to save and restore the current buffer, is so as
1065 to preserve the change in point made by the second call to
1068 To make the filter force the process buffer to be visible whenever new
1069 text arrives, insert the following line just before the
1070 @code{with-current-buffer} construct:
1073 (display-buffer (process-buffer proc))
1076 To force point to the end of the new output, no matter where it was
1077 previously, eliminate the variable @code{moving} and call
1078 @code{goto-char} unconditionally.
1080 In earlier Emacs versions, every filter function that did regular
1081 expression searching or matching had to explicitly save and restore the
1082 match data. Now Emacs does this automatically for filter functions;
1083 they never need to do it explicitly. @xref{Match Data}.
1085 A filter function that writes the output into the buffer of the
1086 process should check whether the buffer is still alive. If it tries to
1087 insert into a dead buffer, it will get an error. The expression
1088 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
1089 if the buffer is dead.
1091 The output to the function may come in chunks of any size. A program
1092 that produces the same output twice in a row may send it as one batch of
1093 200 characters one time, and five batches of 40 characters the next. If
1094 the filter looks for certain text strings in the subprocess output, make
1095 sure to handle the case where one of these strings is split across two
1096 or more batches of output.
1098 @defun set-process-filter process filter
1099 This function gives @var{process} the filter function @var{filter}. If
1100 @var{filter} is @code{nil}, it gives the process no filter.
1103 @defun process-filter process
1104 This function returns the filter function of @var{process}, or @code{nil}
1108 Here is an example of use of a filter function:
1112 (defun keep-output (process output)
1113 (setq kept (cons output kept)))
1114 @result{} keep-output
1121 (set-process-filter (get-process "shell") 'keep-output)
1122 @result{} keep-output
1125 (process-send-string "shell" "ls ~/other\n")
1128 @result{} ("lewis@@slug[8] % "
1131 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
1132 address.txt backup.psf kolstad.psf
1133 backup.bib~ david.mss resume-Dec-86.mss~
1134 backup.err david.psf resume-Dec.psf
1135 backup.mss dland syllabus.mss
1137 "#backups.mss# backup.mss~ kolstad.mss
1142 @ignore @c The code in this example doesn't show the right way to do things.
1143 Here is another, more realistic example, which demonstrates how to use
1144 the process mark to do insertion in the same fashion as is done when
1145 there is no filter function:
1149 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
1150 ;; @r{and make sure that buffer is shown in some window.}
1151 (defun my-process-filter (proc str)
1152 (let ((cur (selected-window))
1154 (pop-to-buffer my-shell-buffer)
1157 (goto-char (point-max))
1159 (set-marker (process-mark proc) (point-max))
1160 (select-window cur)))
1165 @node Accepting Output
1166 @subsection Accepting Output from Processes
1168 Output from asynchronous subprocesses normally arrives only while
1169 Emacs is waiting for some sort of external event, such as elapsed time
1170 or terminal input. Occasionally it is useful in a Lisp program to
1171 explicitly permit output to arrive at a specific point, or even to wait
1172 until output arrives from a process.
1174 @defun accept-process-output &optional process seconds millisec
1175 This function allows Emacs to read pending output from processes. The
1176 output is inserted in the associated buffers or given to their filter
1177 functions. If @var{process} is non-@code{nil} then this function does
1178 not return until some output has been received from @var{process}.
1181 The arguments @var{seconds} and @var{millisec} let you specify timeout
1182 periods. The former specifies a period measured in seconds and the
1183 latter specifies one measured in milliseconds. The two time periods
1184 thus specified are added together, and @code{accept-process-output}
1185 returns after that much time whether or not there has been any
1188 The argument @var{seconds} need not be an integer. If it is a floating
1189 point number, this function waits for a fractional number of seconds.
1190 Some systems support only a whole number of seconds; on these systems,
1191 @var{seconds} is rounded down.
1193 Not all operating systems support waiting periods other than multiples
1194 of a second; on those that do not, you get an error if you specify
1195 nonzero @var{millisec}.
1197 The function @code{accept-process-output} returns non-@code{nil} if it
1198 did get some output, or @code{nil} if the timeout expired before output
1203 @section Sentinels: Detecting Process Status Changes
1204 @cindex process sentinel
1207 A @dfn{process sentinel} is a function that is called whenever the
1208 associated process changes status for any reason, including signals
1209 (whether sent by Emacs or caused by the process's own actions) that
1210 terminate, stop, or continue the process. The process sentinel is
1211 also called if the process exits. The sentinel receives two
1212 arguments: the process for which the event occurred, and a string
1213 describing the type of event.
1215 The string describing the event looks like one of the following:
1219 @code{"finished\n"}.
1222 @code{"exited abnormally with code @var{exitcode}\n"}.
1225 @code{"@var{name-of-signal}\n"}.
1228 @code{"@var{name-of-signal} (core dumped)\n"}.
1231 A sentinel runs only while Emacs is waiting (e.g., for terminal
1232 input, or for time to elapse, or for process output). This avoids the
1233 timing errors that could result from running them at random places in
1234 the middle of other Lisp programs. A program can wait, so that
1235 sentinels will run, by calling @code{sit-for} or @code{sleep-for}
1236 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
1237 Output}). Emacs also allows sentinels to run when the command loop is
1238 reading input. @code{delete-process} calls the sentinel when it
1239 terminates a running process.
1241 Emacs does not keep a queue of multiple reasons to call the sentinel
1242 of one process; it records just the current status and the fact that
1243 there has been a change. Therefore two changes in status, coming in
1244 quick succession, can call the sentinel just once. However, process
1245 termination will always run the sentinel exactly once. This is
1246 because the process status can't change again after termination.
1248 Quitting is normally inhibited within a sentinel---otherwise, the
1249 effect of typing @kbd{C-g} at command level or to quit a user command
1250 would be unpredictable. If you want to permit quitting inside a
1251 sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}.
1253 A sentinel that writes the output into the buffer of the process
1254 should check whether the buffer is still alive. If it tries to insert
1255 into a dead buffer, it will get an error. If the buffer is dead,
1256 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
1258 If an error happens during execution of a sentinel, it is caught
1259 automatically, so that it doesn't stop the execution of whatever
1260 programs was running when the sentinel was started. However, if
1261 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1262 off. This makes it possible to use the Lisp debugger to debug the
1263 sentinel. @xref{Debugger}.
1265 While a sentinel is running, the process sentinel is temporarily
1266 set to @code{nil} so that the sentinel won't run recursively.
1267 For this reason it is not possible for a sentinel to specify
1270 In earlier Emacs versions, every sentinel that did regular expression
1271 searching or matching had to explicitly save and restore the match data.
1272 Now Emacs does this automatically for sentinels; they never need to do
1273 it explicitly. @xref{Match Data}.
1275 @defun set-process-sentinel process sentinel
1276 This function associates @var{sentinel} with @var{process}. If
1277 @var{sentinel} is @code{nil}, then the process will have no sentinel.
1278 The default behavior when there is no sentinel is to insert a message in
1279 the process's buffer when the process status changes.
1281 Changes in process sentinel take effect immediately---if the sentinel
1282 is slated to be run but has not been called yet, and you specify a new
1283 sentinel, the eventual call to the sentinel will use the new one.
1287 (defun msg-me (process event)
1289 (format "Process: %s had the event `%s'" process event)))
1290 (set-process-sentinel (get-process "shell") 'msg-me)
1294 (kill-process (get-process "shell"))
1295 @print{} Process: #<process shell> had the event `killed'
1296 @result{} #<process shell>
1301 @defun process-sentinel process
1302 This function returns the sentinel of @var{process}, or @code{nil} if it
1306 @defun waiting-for-user-input-p
1307 While a sentinel or filter function is running, this function returns
1308 non-@code{nil} if Emacs was waiting for keyboard input from the user at
1309 the time the sentinel or filter function was called, @code{nil} if it
1313 @node Query Before Exit
1314 @section Querying Before Exit
1316 When Emacs exits, it terminates all its subprocesses by sending them
1317 the @code{SIGHUP} signal. Because some subprocesses are doing
1318 valuable work, Emacs normally asks the user to confirm that it is ok
1319 to terminate them. Each process has a query flag which, if
1320 non-@code{nil}, says that Emacs should ask for confirmation before
1321 exiting and thus killing that process. The default for the query flag
1322 is @code{t}, meaning @emph{do} query.
1324 @tindex process-query-on-exit-flag
1325 @defun process-query-on-exit-flag process
1326 This returns the query flag of @var{process}.
1329 @tindex set-process-query-on-exit-flag
1330 @defun set-process-query-on-exit-flag process flag
1331 This function sets the query flag of @var{process} to @var{flag}. It
1336 ;; @r{Don't query about the shell process}
1337 (set-process-query-on-exit-flag (get-process "shell") nil)
1343 @defun process-kill-without-query process &optional do-query
1344 This function clears the query flag of @var{process}, so that
1345 Emacs will not query the user on account of that process.
1347 Actually, the function does more than that: it returns the old value of
1348 the process's query flag, and sets the query flag to @var{do-query}.
1349 Please don't use this function to do those things any more---please
1350 use the newer, cleaner functions @code{process-query-on-exit-flag} and
1351 @code{set-process-query-on-exit-flag} in all but the simplest cases.
1352 The only way you should use @code{process-kill-without-query} nowadays
1357 ;; @r{Don't query about the shell process}
1358 (process-kill-without-query (get-process "shell"))
1363 @node Transaction Queues
1364 @section Transaction Queues
1365 @cindex transaction queue
1367 You can use a @dfn{transaction queue} to communicate with a subprocess
1368 using transactions. First use @code{tq-create} to create a transaction
1369 queue communicating with a specified process. Then you can call
1370 @code{tq-enqueue} to send a transaction.
1372 @defun tq-create process
1373 This function creates and returns a transaction queue communicating with
1374 @var{process}. The argument @var{process} should be a subprocess
1375 capable of sending and receiving streams of bytes. It may be a child
1376 process, or it may be a TCP connection to a server, possibly on another
1380 @defun tq-enqueue queue question regexp closure fn
1381 This function sends a transaction to queue @var{queue}. Specifying the
1382 queue has the effect of specifying the subprocess to talk to.
1384 The argument @var{question} is the outgoing message that starts the
1385 transaction. The argument @var{fn} is the function to call when the
1386 corresponding answer comes back; it is called with two arguments:
1387 @var{closure}, and the answer received.
1389 The argument @var{regexp} is a regular expression that should match
1390 text at the end of the entire answer, but nothing before; that's how
1391 @code{tq-enqueue} determines where the answer ends.
1393 The return value of @code{tq-enqueue} itself is not meaningful.
1396 @defun tq-close queue
1397 Shut down transaction queue @var{queue}, waiting for all pending transactions
1398 to complete, and then terminate the connection or child process.
1401 Transaction queues are implemented by means of a filter function.
1402 @xref{Filter Functions}.
1405 @section Network Connections
1406 @cindex network connection
1409 Emacs Lisp programs can open TCP network connections to other processes on
1410 the same machine or other machines. A network connection is handled by Lisp
1411 much like a subprocess, and is represented by a process object.
1412 However, the process you are communicating with is not a child of the
1413 Emacs process, so you can't kill it or send it signals. All you can do
1414 is send and receive data. @code{delete-process} closes the connection,
1415 but does not kill the process at the other end; that process must decide
1416 what to do about closure of the connection.
1418 You can distinguish process objects representing network connections
1419 from those representing subprocesses with the @code{process-status}
1420 function. It always returns either @code{open} or @code{closed} for a
1421 network connection, and it never returns either of those values for a
1422 real subprocess. @xref{Process Information}.
1424 @defun open-network-stream name buffer-or-name host service
1425 This function opens a TCP connection for a service to a host. It
1426 returns a process object to represent the connection.
1428 The @var{name} argument specifies the name for the process object. It
1429 is modified as necessary to make it unique.
1431 The @var{buffer-or-name} argument is the buffer to associate with the
1432 connection. Output from the connection is inserted in the buffer,
1433 unless you specify a filter function to handle the output. If
1434 @var{buffer-or-name} is @code{nil}, it means that the connection is not
1435 associated with any buffer.
1437 The arguments @var{host} and @var{service} specify where to connect to;
1438 @var{host} is the host name (a string), and @var{service} is the name of
1439 a defined network service (a string) or a port number (an integer).