*** empty log message ***
[emacs.git] / lispref / processes.texi
blob0b5786f2cd811b892eae25d12e9566182279b858
1 @c -*-texinfo-*-
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
8 @chapter Processes
9 @cindex child process
10 @cindex parent process
11 @cindex subprocess
12 @cindex 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
29 send input to it.
31 @defun processp object
32 This function returns @code{t} if @var{object} is a process,
33 @code{nil} otherwise.
34 @end defun
36 @menu
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 * Query Before Exit::        Whether to query if exiting will kill a process.
47 * Output from Processes::    Collecting output from an asynchronous subprocess.
48 * Sentinels::                Sentinels run when process run-status changes.
49 * Transaction Queues::       Transaction-based communication with subprocesses.
50 * Network::                  Opening network connections.
51 @end menu
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
80 Expansion}).
82   Each of the subprocess-creating functions has a @var{buffer-or-name}
83 argument which specifies where the standard output from the program will
84 go.  It should be a buffer or a buffer name; if it is a buffer name,
85 that will create the buffer if it does not already exist.  It can also
86 be @code{nil}, which says to discard the output unless a filter function
87 handles it.  (@xref{Filter Functions}, and @ref{Read and Print}.)
88 Normally, you should avoid having multiple processes send output to the
89 same buffer because their output would be intermixed randomly.
91 @cindex program arguments
92   All three of the subprocess-creating functions have a @code{&rest}
93 argument, @var{args}.  The @var{args} must all be strings, and they are
94 supplied to @var{program} as separate command line arguments.  Wildcard
95 characters and other shell constructs have no special meanings in these
96 strings, since the whole strings are passed directly to the specified
97 program.
99   @strong{Please note:} The argument @var{program} contains only the
100 name of the program; it may not contain any command-line arguments.  You
101 must use @var{args} to provide those.
103   The subprocess gets its current directory from the value of
104 @code{default-directory} (@pxref{File Name Expansion}).
106 @cindex environment variables, subprocesses
107   The subprocess inherits its environment from Emacs, but you can
108 specify overrides for it with @code{process-environment}.  @xref{System
109 Environment}.
111 @defvar exec-directory 
112 @pindex movemail
113 The value of this variable is a string, the name of a directory that
114 contains programs that come with GNU Emacs, programs intended for Emacs
115 to invoke.  The program @code{movemail} is an example of such a program;
116 Rmail uses it to fetch new mail from an inbox.
117 @end defvar
119 @defopt exec-path
120 The value of this variable is a list of directories to search for
121 programs to run in subprocesses.  Each element is either the name of a
122 directory (i.e., a string), or @code{nil}, which stands for the default
123 directory (which is the value of @code{default-directory}).
124 @cindex program directories
126 The value of @code{exec-path} is used by @code{call-process} and
127 @code{start-process} when the @var{program} argument is not an absolute
128 file name.
129 @end defopt
131 @node Shell Arguments
132 @section Shell Arguments
134   Lisp programs sometimes need to run a shell and give it a command
135 that contains file names that were specified by the user.  These
136 programs ought to be able to support any valid file name.  But the shell
137 gives special treatment to certain characters, and if these characters
138 occur in the file name, they will confuse the shell.  To handle these
139 characters, use the function @code{shell-quote-argument}:
141 @defun shell-quote-argument argument
142 This function returns a string which represents, in shell syntax,
143 an argument whose actual contents are @var{argument}.  It should
144 work reliably to concatenate the return value into a shell command
145 and then pass it to a shell for execution.
147 Precisely what this function does depends on your operating system.  The
148 function is designed to work with the syntax of your system's standard
149 shell; if you use an unusual shell, you will need to redefine this
150 function.
152 @example
153 ;; @r{This example shows the behavior on GNU and Unix systems.}
154 (shell-quote-argument "foo > bar")
155      @result{} "foo\\ \\>\\ bar"
157 ;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.}
158 (shell-quote-argument "foo > bar")
159      @result{} "\"foo > bar\""
160 @end example
162 Here's an example of using @code{shell-quote-argument} to construct
163 a shell command:
165 @example
166 (concat "diff -c "
167         (shell-quote-argument oldfile)
168         " "
169         (shell-quote-argument newfile))
170 @end example
171 @end defun
173 @node Synchronous Processes
174 @section Creating a Synchronous Process
175 @cindex synchronous subprocess
177   After a @dfn{synchronous process} is created, Emacs waits for the
178 process to terminate before continuing.  Starting Dired on GNU or
179 Unix@footnote{On other systems, Emacs uses a Lisp emulation of
180 @code{ls}; see @ref{Contents of Directories}.} is an example of this: it
181 runs @code{ls} in a synchronous process, then modifies the output
182 slightly.  Because the process is synchronous, the entire directory
183 listing arrives in the buffer before Emacs tries to do anything with it.
185   While Emacs waits for the synchronous subprocess to terminate, the
186 user can quit by typing @kbd{C-g}.  The first @kbd{C-g} tries to kill
187 the subprocess with a @code{SIGINT} signal; but it waits until the
188 subprocess actually terminates before quitting.  If during that time the
189 user types another @kbd{C-g}, that kills the subprocess instantly with
190 @code{SIGKILL} and quits immediately (except on MS-DOS, where killing
191 other processes doesn't work).  @xref{Quitting}.
193   The synchronous subprocess functions return an indication of how the
194 process terminated.
196   The output from a synchronous subprocess is generally decoded using a
197 coding system, much like text read from a file.  The input sent to a
198 subprocess by @code{call-process-region} is encoded using a coding
199 system, much like text written into a file.  @xref{Coding Systems}.
201 @defun call-process program &optional infile destination display &rest args
202 This function calls @var{program} in a separate process and waits for
203 it to finish.
205 The standard input for the process comes from file @var{infile} if
206 @var{infile} is not @code{nil}, and from the null device otherwise.
207 The argument @var{destination} says where to put the process output.
208 Here are the possibilities:
210 @table @asis
211 @item a buffer
212 Insert the output in that buffer, before point.  This includes both the
213 standard output stream and the standard error stream of the process.
215 @item a string
216 Insert the output in a buffer with that name, before point.
218 @item @code{t}
219 Insert the output in the current buffer, before point.
221 @item @code{nil}
222 Discard the output.
224 @item 0
225 Discard the output, and return @code{nil} immediately without waiting
226 for the subprocess to finish.
228 In this case, the process is not truly synchronous, since it can run in
229 parallel with Emacs; but you can think of it as synchronous in that
230 Emacs is essentially finished with the subprocess as soon as this
231 function returns.
233 MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
234 work there.
236 @item @code{(@var{real-destination} @var{error-destination})}
237 Keep the standard output stream separate from the standard error stream;
238 deal with the ordinary output as specified by @var{real-destination},
239 and dispose of the error output according to @var{error-destination}.
240 If @var{error-destination} is @code{nil}, that means to discard the
241 error output, @code{t} means mix it with the ordinary output, and a
242 string specifies a file name to redirect error output into.
244 You can't directly specify a buffer to put the error output in; that is
245 too difficult to implement.  But you can achieve this result by sending
246 the error output to a temporary file and then inserting the file into a
247 buffer.
248 @end table
250 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
251 the buffer as output is inserted.  (However, if the coding system chosen
252 for decoding output is @code{undecided}, meaning deduce the encoding
253 from the actual data, then redisplay sometimes cannot continue once
254 non-@sc{ascii} characters are encountered.  There are fundamental
255 reasons why it is hard to fix this; see @ref{Output from Processes}.)
257 Otherwise the function @code{call-process} does no redisplay, and the
258 results become visible on the screen only when Emacs redisplays that
259 buffer in the normal course of events.
261 The remaining arguments, @var{args}, are strings that specify command
262 line arguments for the program.
264 The value returned by @code{call-process} (unless you told it not to
265 wait) indicates the reason for process termination.  A number gives the
266 exit status of the subprocess; 0 means success, and any other value
267 means failure.  If the process terminated with a signal,
268 @code{call-process} returns a string describing the signal.
270 In the examples below, the buffer @samp{foo} is current.
272 @smallexample
273 @group
274 (call-process "pwd" nil t)
275      @result{} 0
277 ---------- Buffer: foo ----------
278 /usr/user/lewis/manual
279 ---------- Buffer: foo ----------
280 @end group
282 @group
283 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
284      @result{} 0
286 ---------- Buffer: bar ----------
287 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
289 ---------- Buffer: bar ----------
290 @end group
291 @end smallexample
293 Here is a good example of the use of @code{call-process}, which used to
294 be found in the definition of @code{insert-directory}:
296 @smallexample
297 @group
298 (call-process insert-directory-program nil t nil @var{switches}
299               (if full-directory-p
300                   (concat (file-name-as-directory file) ".")
301                 file))
302 @end group
303 @end smallexample
304 @end defun
306 @defun call-process-region start end program &optional delete destination display &rest args
307 This function sends the text from @var{start} to @var{end} as
308 standard input to a process running @var{program}.  It deletes the text
309 sent if @var{delete} is non-@code{nil}; this is useful when
310 @var{destination} is @code{t}, to insert the output in the current
311 buffer in place of the input.
313 The arguments @var{destination} and @var{display} control what to do
314 with the output from the subprocess, and whether to update the display
315 as it comes in.  For details, see the description of
316 @code{call-process}, above.  If @var{destination} is the integer 0,
317 @code{call-process-region} discards the output and returns @code{nil}
318 immediately, without waiting for the subprocess to finish (this only
319 works if asynchronous subprocesses are supported).
321 The remaining arguments, @var{args}, are strings that specify command
322 line arguments for the program.
324 The return value of @code{call-process-region} is just like that of
325 @code{call-process}: @code{nil} if you told it to return without
326 waiting; otherwise, a number or string which indicates how the
327 subprocess terminated.
329 In the following example, we use @code{call-process-region} to run the
330 @code{cat} utility, with standard input being the first five characters
331 in buffer @samp{foo} (the word @samp{input}).  @code{cat} copies its
332 standard input into its standard output.  Since the argument
333 @var{destination} is @code{t}, this output is inserted in the current
334 buffer.
336 @smallexample
337 @group
338 ---------- Buffer: foo ----------
339 input@point{}
340 ---------- Buffer: foo ----------
341 @end group
343 @group
344 (call-process-region 1 6 "cat" nil t)
345      @result{} 0
347 ---------- Buffer: foo ----------
348 inputinput@point{}
349 ---------- Buffer: foo ----------
350 @end group
351 @end smallexample
353   The @code{shell-command-on-region} command uses
354 @code{call-process-region} like this:
356 @smallexample
357 @group
358 (call-process-region 
359  start end         
360  shell-file-name      ; @r{Name of program.}
361  nil                  ; @r{Do not delete region.}
362  buffer               ; @r{Send output to @code{buffer}.}
363  nil                  ; @r{No redisplay during output.}
364  "-c" command)        ; @r{Arguments for the shell.}
365 @end group
366 @end smallexample
367 @end defun
369 @defun shell-command-to-string command
370 This function executes @var{command} (a string) as a shell command,
371 then returns the command's output as a string.
372 @end defun
374 @node Asynchronous Processes
375 @section Creating an Asynchronous Process
376 @cindex asynchronous subprocess
378   After an @dfn{asynchronous process} is created, Emacs and the subprocess
379 both continue running immediately.  The process thereafter runs
380 in parallel with Emacs, and the two can communicate with each other
381 using the functions described in the following sections.  However,
382 communication is only partially asynchronous: Emacs sends data to the
383 process only when certain functions are called, and Emacs accepts data
384 from the process only when Emacs is waiting for input or for a time
385 delay.
387   Here we describe how to create an asynchronous process.
389 @defun start-process name buffer-or-name program &rest args
390 This function creates a new asynchronous subprocess and starts the
391 program @var{program} running in it.  It returns a process object that
392 stands for the new subprocess in Lisp.  The argument @var{name}
393 specifies the name for the process object; if a process with this name
394 already exists, then @var{name} is modified (by appending @samp{<1>},
395 etc.) to be unique.  The buffer @var{buffer-or-name} is the buffer to
396 associate with the process.
398 The remaining arguments, @var{args}, are strings that specify command
399 line arguments for the program.
401 In the example below, the first process is started and runs (rather,
402 sleeps) for 100 seconds.  Meanwhile, the second process is started, and
403 given the name @samp{my-process<1>} for the sake of uniqueness.  It
404 inserts the directory listing at the end of the buffer @samp{foo},
405 before the first process finishes.  Then it finishes, and a message to
406 that effect is inserted in the buffer.  Much later, the first process
407 finishes, and another message is inserted in the buffer for it.
409 @smallexample
410 @group
411 (start-process "my-process" "foo" "sleep" "100")
412      @result{} #<process my-process>
413 @end group
415 @group
416 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
417      @result{} #<process my-process<1>>
419 ---------- Buffer: foo ----------
420 total 2
421 lrwxrwxrwx  1 lewis     14 Jul 22 10:12 gnuemacs --> /emacs
422 -rwxrwxrwx  1 lewis     19 Jul 30 21:02 lemon
424 Process my-process<1> finished
426 Process my-process finished
427 ---------- Buffer: foo ----------
428 @end group
429 @end smallexample
430 @end defun
432 @defun start-process-shell-command name buffer-or-name command &rest command-args
433 This function is like @code{start-process} except that it uses a shell
434 to execute the specified command.  The argument @var{command} is a shell
435 command name, and @var{command-args} are the arguments for the shell
436 command.  The variable @code{shell-file-name} specifies which shell to
437 use.
439 The point of running a program through the shell, rather than directly
440 with @code{start-process}, is so that you can employ shell features such
441 as wildcards in the arguments.  It follows that if you include an
442 arbitrary user-specified arguments in the command, you should quote it
443 with @code{shell-quote-argument} first, so that any special shell
444 characters do @emph{not} have their special shell meanings.  @xref{Shell
445 Arguments}.
446 @end defun
448 @defvar process-connection-type
449 @cindex pipes
450 @cindex @sc{pty}s
451 This variable controls the type of device used to communicate with
452 asynchronous subprocesses.  If it is non-@code{nil}, then @sc{pty}s are
453 used, when available.  Otherwise, pipes are used.
455 @sc{pty}s are usually preferable for processes visible to the user, as
456 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
457 etc.) to work between the process and its children, whereas pipes do
458 not.  For subprocesses used for internal purposes by programs, it is
459 often better to use a pipe, because they are more efficient.  In
460 addition, the total number of @sc{pty}s is limited on many systems and
461 it is good not to waste them.
463 The value of @code{process-connection-type} is used when
464 @code{start-process} is called.  So you can specify how to communicate
465 with one subprocess by binding the variable around the call to
466 @code{start-process}.
468 @smallexample
469 @group
470 (let ((process-connection-type nil))  ; @r{Use a pipe.}
471   (start-process @dots{}))
472 @end group
473 @end smallexample
475 To determine whether a given subprocess actually got a pipe or a
476 @sc{pty}, use the function @code{process-tty-name} (@pxref{Process
477 Information}).
478 @end defvar
480 @node Deleting Processes
481 @section Deleting Processes
482 @cindex deleting processes
484   @dfn{Deleting a process} disconnects Emacs immediately from the
485 subprocess.  Processes are deleted automatically after they terminate,
486 but not necessarily right away.  You can delete a process explicitly
487 at any time.  If you delete a terminated process explicitly before it
488 is deleted automatically, no harm results.  Deletion of a running
489 process sends a signal to terminate it and calls the process sentinel
490 if it has one.
492   @code{get-buffer-process} and @code{process-list} do not remember a
493 deleted process, but the process object itself continues to exist as
494 long as other Lisp objects point to it.  All the Lisp primitives that
495 work on process objects accept deleted processes, but those that do
496 I/O or send signals will report an error.  The process mark continues
497 to point to the same place as before, usually into a buffer where
498 output from the process was being inserted.
500 @defopt delete-exited-processes
501 This variable controls automatic deletion of processes that have
502 terminated (due to calling @code{exit} or to a signal).  If it is
503 @code{nil}, then they continue to exist until the user runs
504 @code{list-processes}.  Otherwise, they are deleted immediately after
505 they exit.
506 @end defopt
508 @defun delete-process name
509 This function deletes the process associated with @var{name}, killing
510 it with a @code{SIGKILL} signal.  The argument @var{name} may be a
511 process, the name of a process, a buffer, or the name of a buffer.
512 Calling @code{delete-process} on a running process terminates it,
513 updates the process status, and runs the sentinel (if any) immediately.
514 If the process has already terminated, calling @code{delete-process}
515 has no effect on its status, or on the running of its sentinel (which
516 will happen sooner or later).
518 @smallexample
519 @group
520 (delete-process "*shell*")
521      @result{} nil
522 @end group
523 @end smallexample
524 @end defun
526 @node Process Information
527 @section Process Information
529   Several functions return information about processes.
530 @code{list-processes} is provided for interactive use.
532 @deffn Command list-processes
533 This command displays a listing of all living processes.  In addition,
534 it finally deletes any process whose status was @samp{Exited} or
535 @samp{Signaled}.  It returns @code{nil}.
536 @end deffn
538 @defun process-list
539 This function returns a list of all processes that have not been deleted.
541 @smallexample
542 @group
543 (process-list)
544      @result{} (#<process display-time> #<process shell>)
545 @end group
546 @end smallexample
547 @end defun
549 @defun get-process name
550 This function returns the process named @var{name}, or @code{nil} if
551 there is none.  An error is signaled if @var{name} is not a string.
553 @smallexample
554 @group
555 (get-process "shell")
556      @result{} #<process shell>
557 @end group
558 @end smallexample
559 @end defun
561 @defun process-command process
562 This function returns the command that was executed to start
563 @var{process}.  This is a list of strings, the first string being the
564 program executed and the rest of the strings being the arguments that
565 were given to the program.
567 @smallexample
568 @group
569 (process-command (get-process "shell"))
570      @result{} ("/bin/csh" "-i")
571 @end group
572 @end smallexample
573 @end defun
575 @defun process-id process
576 This function returns the @sc{pid} of @var{process}.  This is an
577 integer that distinguishes the process @var{process} from all other
578 processes running on the same computer at the current time.  The
579 @sc{pid} of a process is chosen by the operating system kernel when the
580 process is started and remains constant as long as the process exists.
581 @end defun
583 @defun process-name process
584 This function returns the name of @var{process}.
585 @end defun
587 @defun process-contact process
588 This function returns @code{t} for an ordinary child process, and
589 @code{(@var{hostname} @var{service})} for a net connection
590 (@pxref{Network}).
591 @end defun
593 @defun process-status process-name
594 This function returns the status of @var{process-name} as a symbol.
595 The argument @var{process-name} must be a process, a buffer, a
596 process name (string) or a buffer name (string).
598 The possible values for an actual subprocess are:
600 @table @code
601 @item run
602 for a process that is running.
603 @item stop
604 for a process that is stopped but continuable.
605 @item exit
606 for a process that has exited.
607 @item signal
608 for a process that has received a fatal signal.
609 @item open
610 for a network connection that is open.
611 @item closed
612 for a network connection that is closed.  Once a connection
613 is closed, you cannot reopen it, though you might be able to open
614 a new connection to the same place.
615 @item nil
616 if @var{process-name} is not the name of an existing process.
617 @end table
619 @smallexample
620 @group
621 (process-status "shell")
622      @result{} run
623 @end group
624 @group
625 (process-status (get-buffer "*shell*"))
626      @result{} run
627 @end group
628 @group
630      @result{} #<process xx<1>>
631 (process-status x)
632      @result{} exit
633 @end group
634 @end smallexample
636 For a network connection, @code{process-status} returns one of the symbols
637 @code{open} or @code{closed}.  The latter means that the other side
638 closed the connection, or Emacs did @code{delete-process}.
639 @end defun
641 @defun process-exit-status process
642 This function returns the exit status of @var{process} or the signal
643 number that killed it.  (Use the result of @code{process-status} to
644 determine which of those it is.)  If @var{process} has not yet
645 terminated, the value is 0.
646 @end defun
648 @defun process-tty-name process
649 This function returns the terminal name that @var{process} is using for
650 its communication with Emacs---or @code{nil} if it is using pipes
651 instead of a terminal (see @code{process-connection-type} in
652 @ref{Asynchronous Processes}).
653 @end defun
655 @defun process-coding-system process
656 This function returns a cons cell describing the coding systems in use
657 for decoding output from @var{process} and for encoding input to
658 @var{process} (@pxref{Coding Systems}).  The value has this form:
660 @example
661 (@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
662 @end example
663 @end defun
665 @defun set-process-coding-system process decoding-system encoding-system
666 This function specifies the coding systems to use for subsequent output
667 from and input to @var{process}.  It will use @var{decoding-system} to
668 decode subprocess output, and @var{encoding-system} to encode subprocess
669 input.
670 @end defun
672 @node Input to Processes
673 @section Sending Input to Processes
674 @cindex process input
676   Asynchronous subprocesses receive input when it is sent to them by
677 Emacs, which is done with the functions in this section.  You must
678 specify the process to send input to, and the input data to send.  The
679 data appears on the ``standard input'' of the subprocess.
681   Some operating systems have limited space for buffered input in a
682 @sc{pty}.  On these systems, Emacs sends an @sc{eof} periodically amidst
683 the other characters, to force them through.  For most programs,
684 these @sc{eof}s do no harm.
686   Subprocess input is normally encoded using a coding system before the
687 subprocess receives it, much like text written into a file.  You can use
688 @code{set-process-coding-system} to specify which coding system to use
689 (@pxref{Process Information}).  Otherwise, the coding system comes from
690 @code{coding-system-for-write}, if that is non-@code{nil}; or else from
691 the defaulting mechanism (@pxref{Default Coding Systems}).
693   Sometimes the system is unable to accept input for that process,
694 because the input buffer is full.  When this happens, the send functions
695 wait a short while, accepting output from subprocesses, and then try
696 again.  This gives the subprocess a chance to read more of its pending
697 input and make space in the buffer.  It also allows filters, sentinels
698 and timers to run---so take account of that in writing your code.
700 @defun process-send-string process-name string
701 This function sends @var{process-name} the contents of @var{string} as
702 standard input.  The argument @var{process-name} must be a process or
703 the name of a process.  If it is @code{nil}, the current buffer's
704 process is used.
706   The function returns @code{nil}.
708 @smallexample
709 @group
710 (process-send-string "shell<1>" "ls\n")
711      @result{} nil
712 @end group
715 @group
716 ---------- Buffer: *shell* ----------
718 introduction.texi               syntax-tables.texi~
719 introduction.texi~              text.texi
720 introduction.txt                text.texi~
722 ---------- Buffer: *shell* ----------
723 @end group
724 @end smallexample
725 @end defun
727 @defun process-send-region process-name start end
728 This function sends the text in the region defined by @var{start} and
729 @var{end} as standard input to @var{process-name}, which is a process or
730 a process name.  (If it is @code{nil}, the current buffer's process is
731 used.)
733 An error is signaled unless both @var{start} and @var{end} are
734 integers or markers that indicate positions in the current buffer.  (It
735 is unimportant which number is larger.)
736 @end defun
738 @defun process-send-eof &optional process-name
739   This function makes @var{process-name} see an end-of-file in its
740 input.  The @sc{eof} comes after any text already sent to it.
742   If @var{process-name} is not supplied, or if it is @code{nil}, then
743 this function sends the @sc{eof} to the current buffer's process.  An
744 error is signaled if the current buffer has no process.
746   The function returns @var{process-name}.
748 @smallexample
749 @group
750 (process-send-eof "shell")
751      @result{} "shell"
752 @end group
753 @end smallexample
754 @end defun
756 @defun process-running-child-p process
757 @tindex process-running-child-p process
758 This function will tell you whether a subprocess has given control of
759 its terminal to its own child process.  The value is @code{t} if this is
760 true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
761 that this is not so.
762 @end defun
764 @node Signals to Processes
765 @section Sending Signals to Processes
766 @cindex process signals
767 @cindex sending signals
768 @cindex signals
770   @dfn{Sending a signal} to a subprocess is a way of interrupting its
771 activities.  There are several different signals, each with its own
772 meaning.  The set of signals and their names is defined by the operating
773 system.  For example, the signal @code{SIGINT} means that the user has
774 typed @kbd{C-c}, or that some analogous thing has happened.
776   Each signal has a standard effect on the subprocess.  Most signals
777 kill the subprocess, but some stop or resume execution instead.  Most
778 signals can optionally be handled by programs; if the program handles
779 the signal, then we can say nothing in general about its effects.
781   You can send signals explicitly by calling the functions in this
782 section.  Emacs also sends signals automatically at certain times:
783 killing a buffer sends a @code{SIGHUP} signal to all its associated
784 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
785 processes.  (@code{SIGHUP} is a signal that usually indicates that the
786 user hung up the phone.)
788   Each of the signal-sending functions takes two optional arguments:
789 @var{process-name} and @var{current-group}.
791   The argument @var{process-name} must be either a process, the name of
792 one, or @code{nil}.  If it is @code{nil}, the process defaults to the
793 process associated with the current buffer.  An error is signaled if
794 @var{process-name} does not identify a process.
796   The argument @var{current-group} is a flag that makes a difference
797 when you are running a job-control shell as an Emacs subprocess.  If it
798 is non-@code{nil}, then the signal is sent to the current process-group
799 of the terminal that Emacs uses to communicate with the subprocess.  If
800 the process is a job-control shell, this means the shell's current
801 subjob.  If it is @code{nil}, the signal is sent to the process group of
802 the immediate subprocess of Emacs.  If the subprocess is a job-control
803 shell, this is the shell itself.
805   The flag @var{current-group} has no effect when a pipe is used to
806 communicate with the subprocess, because the operating system does not
807 support the distinction in the case of pipes.  For the same reason,
808 job-control shells won't work when a pipe is used.  See
809 @code{process-connection-type} in @ref{Asynchronous Processes}.
811 @defun interrupt-process &optional process-name current-group
812 This function interrupts the process @var{process-name} by sending the
813 signal @code{SIGINT}.  Outside of Emacs, typing the ``interrupt
814 character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
815 others) sends this signal.  When the argument @var{current-group} is
816 non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
817 on the terminal by which Emacs talks to the subprocess.
818 @end defun
820 @defun kill-process &optional process-name current-group
821 This function kills the process @var{process-name} by sending the
822 signal @code{SIGKILL}.  This signal kills the subprocess immediately,
823 and cannot be handled by the subprocess.
824 @end defun
826 @defun quit-process &optional process-name current-group
827 This function sends the signal @code{SIGQUIT} to the process
828 @var{process-name}.  This signal is the one sent by the ``quit
829 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
830 Emacs.
831 @end defun
833 @defun stop-process &optional process-name current-group
834 This function stops the process @var{process-name} by sending the
835 signal @code{SIGTSTP}.  Use @code{continue-process} to resume its
836 execution.
838 Outside of Emacs, on systems with job control, the ``stop character''
839 (usually @kbd{C-z}) normally sends this signal.  When
840 @var{current-group} is non-@code{nil}, you can think of this function as
841 ``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
842 subprocess.
843 @end defun
845 @defun continue-process &optional process-name current-group
846 This function resumes execution of the process @var{process} by sending
847 it the signal @code{SIGCONT}.  This presumes that @var{process-name} was
848 stopped previously.
849 @end defun
851 @c Emacs 19 feature
852 @defun signal-process pid signal
853 This function sends a signal to process @var{pid}, which need not be
854 a child of Emacs.  The argument @var{signal} specifies which signal
855 to send; it should be an integer.
856 @end defun
858 @node Query Before Exit
859 @section Querying Before Exit 
861   When Emacs exits, it terminates all its subprocesses by sending them
862 the @code{SIGHUP} signal.  Because some subprocesses are doing
863 valuable work, Emacs normally asks the user to confirm that it is ok
864 to terminate them.  Each process has a query flag which, if
865 non-@code{nil}, says that Emacs should ask for confirmation before
866 exiting and thus killing that process.  The default for the query flag
867 is @code{t}, meaning @emph{do} query.
869 @tindex process-query-on-exit-flag
870 @defun process-query-on-exit-flag process
871 This returns the query flag of @var{process}.
872 @end defun
874 @tindex set-process-query-on-exit-flag
875 @defun set-process-query-on-exit-flag process flag
876 This function sets the query flag of @var{process} to @var{flag}.  It
877 returns @var{flag}.
879 @smallexample
880 @group
881 ;; @r{Don't query about the shell process}
882 (set-process-query-on-exit-flag (get-process "shell") nil)
883      @result{} t
884 @end group
885 @end smallexample
886 @end defun
888 @defun process-kill-without-query process &optional do-query
889 This function clears the query flag of @var{process}, so that
890 Emacs will not query the user on account of that process.
892 Actually, the function does more than that: it returns the old value of
893 the process's query flag, and sets the query flag to @var{do-query}.
894 Please don't use this function to do those things any more---please
895 use the newer, cleaner functions @code{process-query-on-exit-flag} and
896 @code{set-process-query-on-exit-flag} in all but the simplest cases.
897 The only way you should use @code{process-kill-without-query} nowadays
898 is like this:
900 @smallexample
901 @group
902 ;; @r{Don't query about the shell process}
903 (process-kill-without-query (get-process "shell"))
904 @end group
905 @end smallexample
906 @end defun
908 @node Output from Processes
909 @section Receiving Output from Processes
910 @cindex process output
911 @cindex output from processes
913   There are two ways to receive the output that a subprocess writes to
914 its standard output stream.  The output can be inserted in a buffer,
915 which is called the associated buffer of the process, or a function
916 called the @dfn{filter function} can be called to act on the output.  If
917 the process has no buffer and no filter function, its output is
918 discarded.
920   Output from a subprocess can arrive only while Emacs is waiting: when
921 reading terminal input, in @code{sit-for} and @code{sleep-for}
922 (@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
923 Output}).  This minimizes the problem of timing errors that usually
924 plague parallel programming.  For example, you can safely create a
925 process and only then specify its buffer or filter function; no output
926 can arrive before you finish, if the code in between does not call any
927 primitive that waits.
929   It is impossible to separate the standard output and standard error
930 streams of the subprocess, because Emacs normally spawns the subprocess
931 inside a pseudo-TTY, and a pseudo-TTY has only one output channel.  If
932 you want to keep the output to those streams separate, you should
933 redirect one of them to a file--for example, by using an appropriate
934 shell command.
936   Subprocess output is normally decoded using a coding system before the
937 buffer or filter function receives it, much like text read from a file.
938 You can use @code{set-process-coding-system} to specify which coding
939 system to use (@pxref{Process Information}).  Otherwise, the coding
940 system comes from @code{coding-system-for-read}, if that is
941 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
942 Coding Systems}).
944   @strong{Warning:} Coding systems such as @code{undecided} which
945 determine the coding system from the data do not work entirely reliably
946 with asynchronous subprocess output.  This is because Emacs has to
947 process asynchronous subprocess output in batches, as it arrives.  Emacs
948 must try to detect the proper coding system from one batch at a time,
949 and this does not always work.  Therefore, if at all possible, use a
950 coding system which determines both the character code conversion and
951 the end of line conversion---that is, one like @code{latin-1-unix},
952 rather than @code{undecided} or @code{latin-1}.
954 @menu
955 * Process Buffers::       If no filter, output is put in a buffer.
956 * Filter Functions::      Filter functions accept output from the process.
957 * Accepting Output::      Explicitly permitting subprocess output.
958                             Waiting for subprocess output.
959 @end menu
961 @node Process Buffers
962 @subsection Process Buffers
964   A process can (and usually does) have an @dfn{associated buffer},
965 which is an ordinary Emacs buffer that is used for two purposes: storing
966 the output from the process, and deciding when to kill the process.  You
967 can also use the buffer to identify a process to operate on, since in
968 normal practice only one process is associated with any given buffer.
969 Many applications of processes also use the buffer for editing input to
970 be sent to the process, but this is not built into Emacs Lisp.
972   Unless the process has a filter function (@pxref{Filter Functions}),
973 its output is inserted in the associated buffer.  The position to insert
974 the output is determined by the @code{process-mark}, which is then
975 updated to point to the end of the text just inserted.  Usually, but not
976 always, the @code{process-mark} is at the end of the buffer.
978 @defun process-buffer process
979 This function returns the associated buffer of the process
980 @var{process}.
982 @smallexample
983 @group
984 (process-buffer (get-process "shell"))
985      @result{} #<buffer *shell*>
986 @end group
987 @end smallexample
988 @end defun
990 @defun process-mark process
991 This function returns the process marker for @var{process}, which is the
992 marker that says where to insert output from the process.
994 If @var{process} does not have a buffer, @code{process-mark} returns a
995 marker that points nowhere.
997 Insertion of process output in a buffer uses this marker to decide where
998 to insert, and updates it to point after the inserted text.  That is why
999 successive batches of output are inserted consecutively.
1001 Filter functions normally should use this marker in the same fashion
1002 as is done by direct insertion of output in the buffer.  A good
1003 example of a filter function that uses @code{process-mark} is found at
1004 the end of the following section.
1006 When the user is expected to enter input in the process buffer for
1007 transmission to the process, the process marker separates the new input
1008 from previous output.
1009 @end defun
1011 @defun set-process-buffer process buffer
1012 This function sets the buffer associated with @var{process} to
1013 @var{buffer}.  If @var{buffer} is @code{nil}, the process becomes
1014 associated with no buffer.
1015 @end defun
1017 @defun get-buffer-process buffer-or-name
1018 This function returns a nondeleted process associated with the buffer
1019 specified by @var{buffer-or-name}.  If there are several processes
1020 associated with it, this function chooses one (currently, the one most
1021 recently created, but don't count on that).  Deletion of a process
1022 (see @code{delete-process}) makes it ineligible for this function to
1023 return.
1025 It is usually a bad idea to have more than one process associated with
1026 the same buffer.
1028 @smallexample
1029 @group
1030 (get-buffer-process "*shell*")
1031      @result{} #<process shell>
1032 @end group
1033 @end smallexample
1035 Killing the process's buffer deletes the process, which kills the
1036 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
1037 @end defun
1039 @node Filter Functions
1040 @subsection Process Filter Functions
1041 @cindex filter function
1042 @cindex process filter
1044   A process @dfn{filter function} is a function that receives the
1045 standard output from the associated process.  If a process has a filter,
1046 then @emph{all} output from that process is passed to the filter.  The
1047 process buffer is used directly for output from the process only when
1048 there is no filter.
1050   The filter function can only be called when Emacs is waiting for
1051 something, because process output arrives only at such times.  Emacs
1052 waits when reading terminal input, in @code{sit-for} and
1053 @code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
1054 (@pxref{Accepting Output}).
1056   A filter function must accept two arguments: the associated process
1057 and a string, which is output just received from it.  The function is
1058 then free to do whatever it chooses with the output.
1060   Quitting is normally inhibited within a filter function---otherwise,
1061 the effect of typing @kbd{C-g} at command level or to quit a user
1062 command would be unpredictable.  If you want to permit quitting inside a
1063 filter function, bind @code{inhibit-quit} to @code{nil}.
1064 @xref{Quitting}.
1066   If an error happens during execution of a filter function, it is
1067 caught automatically, so that it doesn't stop the execution of whatever
1068 program was running when the filter function was started.  However, if
1069 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1070 off.  This makes it possible to use the Lisp debugger to debug the
1071 filter function.  @xref{Debugger}.
1073   Many filter functions sometimes or always insert the text in the
1074 process's buffer, mimicking the actions of Emacs when there is no
1075 filter.  Such filter functions need to use @code{set-buffer} in order to
1076 be sure to insert in that buffer.  To avoid setting the current buffer
1077 semipermanently, these filter functions must save and restore the
1078 current buffer.  They should also update the process marker, and in some
1079 cases update the value of point.  Here is how to do these things:
1081 @smallexample
1082 @group
1083 (defun ordinary-insertion-filter (proc string)
1084   (with-current-buffer (process-buffer proc)
1085     (let ((moving (= (point) (process-mark proc))))
1086 @end group
1087 @group
1088       (save-excursion
1089         ;; @r{Insert the text, advancing the process marker.}
1090         (goto-char (process-mark proc))
1091         (insert string)
1092         (set-marker (process-mark proc) (point)))
1093       (if moving (goto-char (process-mark proc))))))
1094 @end group
1095 @end smallexample
1097 @noindent
1098 The reason to use @code{with-current-buffer}, rather than using
1099 @code{save-excursion} to save and restore the current buffer, is so as
1100 to preserve the change in point made by the second call to
1101 @code{goto-char}.
1103   To make the filter force the process buffer to be visible whenever new
1104 text arrives, insert the following line just before the
1105 @code{with-current-buffer} construct:
1107 @smallexample
1108 (display-buffer (process-buffer proc))
1109 @end smallexample
1111   To force point to the end of the new output, no matter where it was
1112 previously, eliminate the variable @code{moving} and call
1113 @code{goto-char} unconditionally.
1115   In earlier Emacs versions, every filter function that did regular
1116 expression searching or matching had to explicitly save and restore the
1117 match data.  Now Emacs does this automatically for filter functions;
1118 they never need to do it explicitly.  @xref{Match Data}.
1120   A filter function that writes the output into the buffer of the
1121 process should check whether the buffer is still alive.  If it tries to
1122 insert into a dead buffer, it will get an error.  The expression
1123 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
1124 if the buffer is dead.
1126   The output to the function may come in chunks of any size.  A program
1127 that produces the same output twice in a row may send it as one batch of
1128 200 characters one time, and five batches of 40 characters the next.  If
1129 the filter looks for certain text strings in the subprocess output, make
1130 sure to handle the case where one of these strings is split across two
1131 or more batches of output.
1133 @defun set-process-filter process filter
1134 This function gives @var{process} the filter function @var{filter}.  If
1135 @var{filter} is @code{nil}, it gives the process no filter.
1136 @end defun
1138 @defun process-filter process
1139 This function returns the filter function of @var{process}, or @code{nil}
1140 if it has none.
1141 @end defun
1143   Here is an example of use of a filter function:
1145 @smallexample
1146 @group
1147 (defun keep-output (process output)
1148    (setq kept (cons output kept)))
1149      @result{} keep-output
1150 @end group
1151 @group
1152 (setq kept nil)
1153      @result{} nil
1154 @end group
1155 @group
1156 (set-process-filter (get-process "shell") 'keep-output)
1157      @result{} keep-output
1158 @end group
1159 @group
1160 (process-send-string "shell" "ls ~/other\n")
1161      @result{} nil
1162 kept
1163      @result{} ("lewis@@slug[8] % "
1164 @end group
1165 @group
1166 "FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
1167 address.txt             backup.psf              kolstad.psf
1168 backup.bib~             david.mss               resume-Dec-86.mss~
1169 backup.err              david.psf               resume-Dec.psf
1170 backup.mss              dland                   syllabus.mss
1172 "#backups.mss#          backup.mss~             kolstad.mss
1174 @end group
1175 @end smallexample
1177 @ignore   @c The code in this example doesn't show the right way to do things.
1178 Here is another, more realistic example, which demonstrates how to use
1179 the process mark to do insertion in the same fashion as is done when
1180 there is no filter function:
1182 @smallexample
1183 @group
1184 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
1185 ;;   @r{and make sure that buffer is shown in some window.}
1186 (defun my-process-filter (proc str)
1187   (let ((cur (selected-window))
1188         (pop-up-windows t))
1189     (pop-to-buffer my-shell-buffer)
1190 @end group
1191 @group
1192     (goto-char (point-max))
1193     (insert str)
1194     (set-marker (process-mark proc) (point-max))
1195     (select-window cur)))
1196 @end group
1197 @end smallexample
1198 @end ignore
1200 @node Accepting Output
1201 @subsection Accepting Output from Processes
1203   Output from asynchronous subprocesses normally arrives only while
1204 Emacs is waiting for some sort of external event, such as elapsed time
1205 or terminal input.  Occasionally it is useful in a Lisp program to
1206 explicitly permit output to arrive at a specific point, or even to wait
1207 until output arrives from a process.
1209 @defun accept-process-output &optional process seconds millisec
1210 This function allows Emacs to read pending output from processes.  The
1211 output is inserted in the associated buffers or given to their filter
1212 functions.  If @var{process} is non-@code{nil} then this function does
1213 not return until some output has been received from @var{process}.
1215 @c Emacs 19 feature
1216 The arguments @var{seconds} and @var{millisec} let you specify timeout
1217 periods.  The former specifies a period measured in seconds and the
1218 latter specifies one measured in milliseconds.  The two time periods
1219 thus specified are added together, and @code{accept-process-output}
1220 returns after that much time whether or not there has been any
1221 subprocess output.
1223 The argument @var{seconds} need not be an integer.  If it is a floating
1224 point number, this function waits for a fractional number of seconds.
1225 Some systems support only a whole number of seconds; on these systems,
1226 @var{seconds} is rounded down.
1228 Not all operating systems support waiting periods other than multiples
1229 of a second; on those that do not, you get an error if you specify
1230 nonzero @var{millisec}.
1232 The function @code{accept-process-output} returns non-@code{nil} if it
1233 did get some output, or @code{nil} if the timeout expired before output
1234 arrived.
1235 @end defun
1237 @node Sentinels
1238 @section Sentinels: Detecting Process Status Changes
1239 @cindex process sentinel
1240 @cindex sentinel
1242   A @dfn{process sentinel} is a function that is called whenever the
1243 associated process changes status for any reason, including signals
1244 (whether sent by Emacs or caused by the process's own actions) that
1245 terminate, stop, or continue the process.  The process sentinel is
1246 also called if the process exits.  The sentinel receives two
1247 arguments: the process for which the event occurred, and a string
1248 describing the type of event.
1250   The string describing the event looks like one of the following:
1252 @itemize @bullet
1253 @item 
1254 @code{"finished\n"}.
1256 @item
1257 @code{"exited abnormally with code @var{exitcode}\n"}.
1259 @item
1260 @code{"@var{name-of-signal}\n"}.
1262 @item
1263 @code{"@var{name-of-signal} (core dumped)\n"}.
1264 @end itemize
1266   A sentinel runs only while Emacs is waiting (e.g., for terminal
1267 input, or for time to elapse, or for process output).  This avoids the
1268 timing errors that could result from running them at random places in
1269 the middle of other Lisp programs.  A program can wait, so that
1270 sentinels will run, by calling @code{sit-for} or @code{sleep-for}
1271 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
1272 Output}).  Emacs also allows sentinels to run when the command loop is
1273 reading input.  @code{delete-process} calls the sentinel when it
1274 terminates a running process.
1276   Emacs does not keep a queue of multiple reasons to call the sentinel
1277 of one process; it records just the current status and the fact that
1278 there has been a change.  Therefore two changes in status, coming in
1279 quick succession, can call the sentinel just once.  However, process
1280 termination will always run the sentinel exactly once.  This is
1281 because the process status can't change again after termination.
1283   Quitting is normally inhibited within a sentinel---otherwise, the
1284 effect of typing @kbd{C-g} at command level or to quit a user command
1285 would be unpredictable.  If you want to permit quitting inside a
1286 sentinel, bind @code{inhibit-quit} to @code{nil}.  @xref{Quitting}.
1288   A sentinel that writes the output into the buffer of the process
1289 should check whether the buffer is still alive.  If it tries to insert
1290 into a dead buffer, it will get an error.  If the buffer is dead,
1291 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
1293   If an error happens during execution of a sentinel, it is caught
1294 automatically, so that it doesn't stop the execution of whatever
1295 programs was running when the sentinel was started.  However, if
1296 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1297 off.  This makes it possible to use the Lisp debugger to debug the
1298 sentinel.  @xref{Debugger}.
1300   While a sentinel is running, the process sentinel is temporarily
1301 set to @code{nil} so that the sentinel won't run recursively.
1302 For this reason it is not possible for a sentinel to specify
1303 a new sentinel.
1305   In earlier Emacs versions, every sentinel that did regular expression
1306 searching or matching had to explicitly save and restore the match data.
1307 Now Emacs does this automatically for sentinels; they never need to do
1308 it explicitly.  @xref{Match Data}.
1310 @defun set-process-sentinel process sentinel
1311 This function associates @var{sentinel} with @var{process}.  If
1312 @var{sentinel} is @code{nil}, then the process will have no sentinel.
1313 The default behavior when there is no sentinel is to insert a message in
1314 the process's buffer when the process status changes.
1316 Changes in process sentinel take effect immediately---if the sentinel
1317 is slated to be run but has not been called yet, and you specify a new
1318 sentinel, the eventual call to the sentinel will use the new one.
1320 @smallexample
1321 @group
1322 (defun msg-me (process event)
1323    (princ
1324      (format "Process: %s had the event `%s'" process event)))
1325 (set-process-sentinel (get-process "shell") 'msg-me)
1326      @result{} msg-me
1327 @end group
1328 @group
1329 (kill-process (get-process "shell"))
1330      @print{} Process: #<process shell> had the event `killed'
1331      @result{} #<process shell>
1332 @end group
1333 @end smallexample
1334 @end defun
1336 @defun process-sentinel process
1337 This function returns the sentinel of @var{process}, or @code{nil} if it
1338 has none.
1339 @end defun
1341 @defun waiting-for-user-input-p
1342 While a sentinel or filter function is running, this function returns
1343 non-@code{nil} if Emacs was waiting for keyboard input from the user at
1344 the time the sentinel or filter function was called, @code{nil} if it
1345 was not.
1346 @end defun
1348 @node Transaction Queues
1349 @section Transaction Queues
1350 @cindex transaction queue
1352 You can use a @dfn{transaction queue} to communicate with a subprocess
1353 using transactions.  First use @code{tq-create} to create a transaction
1354 queue communicating with a specified process.  Then you can call
1355 @code{tq-enqueue} to send a transaction.
1357 @defun tq-create process
1358 This function creates and returns a transaction queue communicating with
1359 @var{process}.  The argument @var{process} should be a subprocess
1360 capable of sending and receiving streams of bytes.  It may be a child
1361 process, or it may be a TCP connection to a server, possibly on another
1362 machine.
1363 @end defun
1365 @defun tq-enqueue queue question regexp closure fn
1366 This function sends a transaction to queue @var{queue}.  Specifying the
1367 queue has the effect of specifying the subprocess to talk to.
1369 The argument @var{question} is the outgoing message that starts the
1370 transaction.  The argument @var{fn} is the function to call when the
1371 corresponding answer comes back; it is called with two arguments:
1372 @var{closure}, and the answer received.
1374 The argument @var{regexp} is a regular expression that should match
1375 text at the end of the entire answer, but nothing before; that's how
1376 @code{tq-enqueue} determines where the answer ends.
1378 The return value of @code{tq-enqueue} itself is not meaningful.
1379 @end defun
1381 @defun tq-close queue
1382 Shut down transaction queue @var{queue}, waiting for all pending transactions
1383 to complete, and then terminate the connection or child process.
1384 @end defun
1386 Transaction queues are implemented by means of a filter function.
1387 @xref{Filter Functions}.
1389 @node Network
1390 @section Network Connections
1391 @cindex network connection
1392 @cindex TCP
1394   Emacs Lisp programs can open TCP network connections to other processes on
1395 the same machine or other machines.  A network connection is handled by Lisp
1396 much like a subprocess, and is represented by a process object.
1397 However, the process you are communicating with is not a child of the
1398 Emacs process, so you can't kill it or send it signals.  All you can do
1399 is send and receive data.  @code{delete-process} closes the connection,
1400 but does not kill the process at the other end; that process must decide
1401 what to do about closure of the connection.
1403   You can distinguish process objects representing network connections
1404 from those representing subprocesses with the @code{process-status}
1405 function.  It always returns either @code{open} or @code{closed} for a
1406 network connection, and it never returns either of those values for a
1407 real subprocess.  @xref{Process Information}.
1409 @defun open-network-stream name buffer-or-name host service
1410 This function opens a TCP connection for a service to a host.  It
1411 returns a process object to represent the connection.
1413 The @var{name} argument specifies the name for the process object.  It
1414 is modified as necessary to make it unique.
1416 The @var{buffer-or-name} argument is the buffer to associate with the
1417 connection.  Output from the connection is inserted in the buffer,
1418 unless you specify a filter function to handle the output.  If
1419 @var{buffer-or-name} is @code{nil}, it means that the connection is not
1420 associated with any buffer.
1422 The arguments @var{host} and @var{service} specify where to connect to;
1423 @var{host} is the host name (a string), and @var{service} is the name of
1424 a defined network service (a string) or a port number (an integer).
1425 @end defun