2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/processes.info
6 @node Processes, System Interface, Databases, Top
13 In the terminology of operating systems, a @dfn{process} is a space in
14 which a program can execute. XEmacs runs in a process. XEmacs Lisp
15 programs can invoke other programs in processes of their own. These are
16 called @dfn{subprocesses} or @dfn{child processes} of the XEmacs process,
17 which is their @dfn{parent process}.
19 A subprocess of XEmacs may be @dfn{synchronous} or @dfn{asynchronous},
20 depending on how it is created. When you create a synchronous
21 subprocess, the Lisp program waits for the subprocess to terminate
22 before continuing execution. When you create an asynchronous
23 subprocess, it can run in parallel with the Lisp program. This kind of
24 subprocess is represented within XEmacs by a Lisp object which is also
25 called a ``process''. Lisp programs can use this object to communicate
26 with the subprocess or to control it. For example, you can send
27 signals, obtain status information, receive output from the process, or
30 @defun processp object
31 This function returns @code{t} if @var{object} is a process,
36 * Subprocess Creation:: Functions that start subprocesses.
37 * Synchronous Processes:: Details of using synchronous subprocesses.
38 * MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
39 for data sent to and from a subprocess.
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 * Process Window Size:: Changing the logical window size of 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 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 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. If @var{buffer-or-name} is @code{nil}, that says to discard the
85 output unless a filter function handles it. (@xref{Filter Functions},
86 and @ref{Read and Print}.) Normally, you should avoid having multiple
87 processes send output to the same buffer because their output would be
90 @cindex program arguments
91 All three of the subprocess-creating functions have a @code{&rest}
92 argument, @var{args}. The @var{args} must all be strings, and they are
93 supplied to @var{program} as separate command line arguments. Wildcard
94 characters and other shell constructs are not allowed in these strings,
95 since they are passed directly to the specified program.
97 @strong{Please note:} The argument @var{program} contains only the
98 name of the program; it may not contain any command-line arguments. You
99 must use @var{args} to provide those.
101 The subprocess gets its current directory from the value of
102 @code{default-directory} (@pxref{File Name Expansion}).
104 @cindex environment variables, subprocesses
105 The subprocess inherits its environment from XEmacs; but you can
106 specify overrides for it with @code{process-environment}. @xref{System
109 @defvar exec-directory
111 The value of this variable is the name of a directory (a string) that
112 contains programs that come with XEmacs, that are intended for XEmacs
113 to invoke. The program @code{wakeup} is an example of such a program;
114 the @code{display-time} command uses it to get a reminder once per
119 The value of this variable is a list of directories to search for
120 programs to run in subprocesses. Each element is either the name of a
121 directory (i.e., a string), or @code{nil}, which stands for the default
122 directory (which is the value of @code{default-directory}).
123 @cindex program directories
125 The value of @code{exec-path} is used by @code{call-process} and
126 @code{start-process} when the @var{program} argument is not an absolute
130 @node Synchronous Processes
131 @section Creating a Synchronous Process
132 @cindex synchronous subprocess
134 After a @dfn{synchronous process} is created, XEmacs waits for the
135 process to terminate before continuing. Starting Dired is an example of
136 this: it runs @code{ls} in a synchronous process, then modifies the
137 output slightly. Because the process is synchronous, the entire
138 directory listing arrives in the buffer before XEmacs tries to do
141 While Emacs waits for the synchronous subprocess to terminate, the
142 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
143 the subprocess with a @code{SIGINT} signal; but it waits until the
144 subprocess actually terminates before quitting. If during that time the
145 user types another @kbd{C-g}, that kills the subprocess instantly with
146 @code{SIGKILL} and quits immediately. @xref{Quitting}.
148 The synchronous subprocess functions returned @code{nil} in version
149 18. In version 19, they return an indication of how the process
152 @defun call-process program &optional infile destination display &rest args
153 This function calls @var{program} in a separate process and waits for
156 The standard input for the process comes from file @var{infile} if
157 @var{infile} is not @code{nil} and from @file{/dev/null} otherwise.
158 The argument @var{destination} says where to put the process output.
159 Here are the possibilities:
163 Insert the output in that buffer, before point. This includes both the
164 standard output stream and the standard error stream of the process.
167 Find or create a buffer with that name, then insert
168 the output in that buffer, before point.
171 Insert the output in the current buffer, before point.
177 Discard the output, and return immediately without waiting
178 for the subprocess to finish.
180 In this case, the process is not truly synchronous, since it can run in
181 parallel with Emacs; but you can think of it as synchronous in that
182 Emacs is essentially finished with the subprocess as soon as this
185 @item (@var{real-destination} @var{error-destination})
186 Keep the standard output stream separate from the standard error stream;
187 deal with the ordinary output as specified by @var{real-destination},
188 and dispose of the error output according to @var{error-destination}.
189 The value @code{nil} means discard it, @code{t} means mix it with the
190 ordinary output, and a string specifies a file name to redirect error
193 You can't directly specify a buffer to put the error output in; that is
194 too difficult to implement. But you can achieve this result by sending
195 the error output to a temporary file and then inserting the file into a
199 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
200 the buffer as output is inserted. Otherwise the function does no
201 redisplay, and the results become visible on the screen only when XEmacs
202 redisplays that buffer in the normal course of events.
204 The remaining arguments, @var{args}, are strings that specify command
205 line arguments for the program.
207 The value returned by @code{call-process} (unless you told it not to
208 wait) indicates the reason for process termination. A number gives the
209 exit status of the subprocess; 0 means success, and any other value
210 means failure. If the process terminated with a signal,
211 @code{call-process} returns a string describing the signal.
213 In the examples below, the buffer @samp{foo} is current.
217 (call-process "pwd" nil t)
220 ---------- Buffer: foo ----------
221 /usr/user/lewis/manual
222 ---------- Buffer: foo ----------
226 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
229 ---------- Buffer: bar ----------
230 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
232 ---------- Buffer: bar ----------
236 The @code{insert-directory} function contains a good example of the use
237 of @code{call-process}:
241 (call-process insert-directory-program nil t nil switches
243 (concat (file-name-as-directory file) ".")
249 @defun call-process-region start end program &optional delete destination display &rest args
250 This function sends the text between @var{start} to @var{end} as
251 standard input to a process running @var{program}. It deletes the text
252 sent if @var{delete} is non-@code{nil}; this is useful when @var{buffer}
253 is @code{t}, to insert the output in the current buffer.
255 The arguments @var{destination} and @var{display} control what to do
256 with the output from the subprocess, and whether to update the display
257 as it comes in. For details, see the description of
258 @code{call-process}, above. If @var{destination} is the integer 0,
259 @code{call-process-region} discards the output and returns @code{nil}
260 immediately, without waiting for the subprocess to finish.
262 The remaining arguments, @var{args}, are strings that specify command
263 line arguments for the program.
265 The return value of @code{call-process-region} is just like that of
266 @code{call-process}: @code{nil} if you told it to return without
267 waiting; otherwise, a number or string which indicates how the
268 subprocess terminated.
270 In the following example, we use @code{call-process-region} to run the
271 @code{cat} utility, with standard input being the first five characters
272 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
273 standard input into its standard output. Since the argument
274 @var{destination} is @code{t}, this output is inserted in the current
279 ---------- Buffer: foo ----------
281 ---------- Buffer: foo ----------
285 (call-process-region 1 6 "cat" nil t)
288 ---------- Buffer: foo ----------
290 ---------- Buffer: foo ----------
294 The @code{shell-command-on-region} command uses
295 @code{call-process-region} like this:
301 shell-file-name ; @r{Name of program.}
302 nil ; @r{Do not delete region.}
303 buffer ; @r{Send output to @code{buffer}.}
304 nil ; @r{No redisplay during output.}
305 "-c" command) ; @r{Arguments for the shell.}
310 @node MS-DOS Subprocesses
311 @section MS-DOS Subprocesses
313 On MS-DOS, you must indicate whether the data going to and from
314 a synchronous subprocess are text or binary. Text data requires
315 translation between the end-of-line convention used within Emacs
316 (a single newline character) and the convention used outside Emacs
317 (the two-character sequence, @sc{crlf}).
319 The variable @code{binary-process-input} applies to input sent to the
320 subprocess, and @code{binary-process-output} applies to output received
321 from it. A non-@code{nil} value means the data is non-text; @code{nil}
322 means the data is text, and calls for conversion.
324 @defvar binary-process-input
325 If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
326 the input to a synchronous subprocess.
329 @defvar binary-process-output
330 If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
331 the output from a synchronous subprocess.
334 @xref{Files and MS-DOS}, for related information.
336 @node Asynchronous Processes
337 @section Creating an Asynchronous Process
338 @cindex asynchronous subprocess
340 After an @dfn{asynchronous process} is created, Emacs and the Lisp
341 program both continue running immediately. The process may thereafter
342 run in parallel with Emacs, and the two may communicate with each other
343 using the functions described in following sections. Here we describe
344 how to create an asynchronous process with @code{start-process}.
346 @defun start-process name buffer-or-name program &rest args
347 This function creates a new asynchronous subprocess and starts the
348 program @var{program} running in it. It returns a process object that
349 stands for the new subprocess in Lisp. The argument @var{name}
350 specifies the name for the process object; if a process with this name
351 already exists, then @var{name} is modified (by adding @samp{<1>}, etc.)
352 to be unique. The buffer @var{buffer-or-name} is the buffer to
353 associate with the process.
355 The remaining arguments, @var{args}, are strings that specify command
356 line arguments for the program.
358 In the example below, the first process is started and runs (rather,
359 sleeps) for 100 seconds. Meanwhile, the second process is started, and
360 given the name @samp{my-process<1>} for the sake of uniqueness. It
361 inserts the directory listing at the end of the buffer @samp{foo},
362 before the first process finishes. Then it finishes, and a message to
363 that effect is inserted in the buffer. Much later, the first process
364 finishes, and another message is inserted in the buffer for it.
368 (start-process "my-process" "foo" "sleep" "100")
369 @result{} #<process my-process>
373 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
374 @result{} #<process my-process<1>>
376 ---------- Buffer: foo ----------
378 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
379 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
381 Process my-process<1> finished
383 Process my-process finished
384 ---------- Buffer: foo ----------
389 @defun start-process-shell-command name buffer-or-name command &rest command-args
390 This function is like @code{start-process} except that it uses a shell
391 to execute the specified command. The argument @var{command} is a shell
392 command name, and @var{command-args} are the arguments for the shell
396 @defvar process-connection-type
399 This variable controls the type of device used to communicate with
400 asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are
401 used, when available. Otherwise, pipes are used.
403 @sc{pty}s are usually preferable for processes visible to the user, as
404 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
405 etc.) to work between the process and its children whereas pipes do not.
406 For subprocesses used for internal purposes by programs, it is often
407 better to use a pipe, because they are more efficient. In addition, the
408 total number of @sc{pty}s is limited on many systems and it is good not
411 The value @code{process-connection-type} is used when
412 @code{start-process} is called. So you can specify how to communicate
413 with one subprocess by binding the variable around the call to
414 @code{start-process}.
418 (let ((process-connection-type nil)) ; @r{Use a pipe.}
419 (start-process @dots{}))
423 To determine whether a given subprocess actually got a pipe or a
424 @sc{pty}, use the function @code{process-tty-name} (@pxref{Process
428 @node Deleting Processes
429 @section Deleting Processes
430 @cindex deleting processes
432 @dfn{Deleting a process} disconnects XEmacs immediately from the
433 subprocess, and removes it from the list of active processes. It sends
434 a signal to the subprocess to make the subprocess terminate, but this is
435 not guaranteed to happen immediately. The process object itself
436 continues to exist as long as other Lisp objects point to it.
438 You can delete a process explicitly at any time. Processes are
439 deleted automatically after they terminate, but not necessarily right
440 away. If you delete a terminated process explicitly before it is
441 deleted automatically, no harm results.
443 @defvar delete-exited-processes
444 This variable controls automatic deletion of processes that have
445 terminated (due to calling @code{exit} or to a signal). If it is
446 @code{nil}, then they continue to exist until the user runs
447 @code{list-processes}. Otherwise, they are deleted immediately after
451 @defun delete-process name
452 This function deletes the process associated with @var{name}, killing it
453 with a @code{SIGHUP} signal. The argument @var{name} may be a process,
454 the name of a process, a buffer, or the name of a buffer.
458 (delete-process "*shell*")
464 @defun process-kill-without-query process &optional require-query-p
465 This function declares that XEmacs need not query the user if
466 @var{process} is still running when XEmacs is exited. The process will
467 be deleted silently. If @var{require-query-p} is non-@code{nil},
468 then XEmacs @emph{will} query the user (this is the default). The
469 return value is @code{t} if a query was formerly required, and
470 @code{nil} otherwise.
474 (process-kill-without-query (get-process "shell"))
480 @node Process Information
481 @section Process Information
483 Several functions return information about processes.
484 @code{list-processes} is provided for interactive use.
486 @deffn Command list-processes
487 This command displays a listing of all living processes. In addition,
488 it finally deletes any process whose status was @samp{Exited} or
489 @samp{Signaled}. It returns @code{nil}.
493 This function returns a list of all processes that have not been deleted.
498 @result{} (#<process display-time> #<process shell>)
503 @defun get-process name
504 This function returns the process named @var{name}, or @code{nil} if
505 there is none. An error is signaled if @var{name} is not a string.
509 (get-process "shell")
510 @result{} #<process shell>
515 @defun process-command process
516 This function returns the command that was executed to start
517 @var{process}. This is a list of strings, the first string being the
518 program executed and the rest of the strings being the arguments that
519 were given to the program.
523 (process-command (get-process "shell"))
524 @result{} ("/bin/csh" "-i")
529 @defun process-id process
530 This function returns the @sc{pid} of @var{process}. This is an
531 integer that distinguishes the process @var{process} from all other
532 processes running on the same computer at the current time. The
533 @sc{pid} of a process is chosen by the operating system kernel when the
534 process is started and remains constant as long as the process exists.
537 @defun process-name process
538 This function returns the name of @var{process}.
541 @defun process-status process-name
542 This function returns the status of @var{process-name} as a symbol.
543 The argument @var{process-name} must be a process, a buffer, a
544 process name (string) or a buffer name (string).
546 The possible values for an actual subprocess are:
550 for a process that is running.
552 for a process that is stopped but continuable.
554 for a process that has exited.
556 for a process that has received a fatal signal.
558 for a network connection that is open.
560 for a network connection that is closed. Once a connection
561 is closed, you cannot reopen it, though you might be able to open
562 a new connection to the same place.
564 if @var{process-name} is not the name of an existing process.
569 (process-status "shell")
573 (process-status (get-buffer "*shell*"))
578 @result{} #<process xx<1>>
584 For a network connection, @code{process-status} returns one of the symbols
585 @code{open} or @code{closed}. The latter means that the other side
586 closed the connection, or XEmacs did @code{delete-process}.
588 In earlier Emacs versions (prior to version 19), the status of a network
589 connection was @code{run} if open, and @code{exit} if closed.
592 @defun process-kill-without-query-p process
593 This function returns whether @var{process} will be killed without
594 querying the user, if it is running when XEmacs is exited. The default
598 @defun process-exit-status process
599 This function returns the exit status of @var{process} or the signal
600 number that killed it. (Use the result of @code{process-status} to
601 determine which of those it is.) If @var{process} has not yet
602 terminated, the value is 0.
605 @defun process-tty-name process
606 This function returns the terminal name that @var{process} is using for
607 its communication with Emacs---or @code{nil} if it is using pipes
608 instead of a terminal (see @code{process-connection-type} in
609 @ref{Asynchronous Processes}).
612 @node Input to Processes
613 @section Sending Input to Processes
614 @cindex process input
616 Asynchronous subprocesses receive input when it is sent to them by
617 XEmacs, which is done with the functions in this section. You must
618 specify the process to send input to, and the input data to send. The
619 data appears on the ``standard input'' of the subprocess.
621 Some operating systems have limited space for buffered input in a
622 @sc{pty}. On these systems, Emacs sends an @sc{eof} periodically amidst
623 the other characters, to force them through. For most programs,
624 these @sc{eof}s do no harm.
626 @defun process-send-string process-name string
627 This function sends @var{process-name} the contents of @var{string} as
628 standard input. The argument @var{process-name} must be a process or
629 the name of a process. If it is @code{nil}, the current buffer's
632 The function returns @code{nil}.
636 (process-send-string "shell<1>" "ls\n")
642 ---------- Buffer: *shell* ----------
644 introduction.texi syntax-tables.texi~
645 introduction.texi~ text.texi
646 introduction.txt text.texi~
648 ---------- Buffer: *shell* ----------
653 @deffn Command process-send-region process-name start end
654 This function sends the text in the region defined by @var{start} and
655 @var{end} as standard input to @var{process-name}, which is a process or
656 a process name. (If it is @code{nil}, the current buffer's process is
659 An error is signaled unless both @var{start} and @var{end} are
660 integers or markers that indicate positions in the current buffer. (It
661 is unimportant which number is larger.)
664 @defun process-send-eof &optional process-name
665 This function makes @var{process-name} see an end-of-file in its
666 input. The @sc{eof} comes after any text already sent to it.
668 If @var{process-name} is not supplied, or if it is @code{nil}, then
669 this function sends the @sc{eof} to the current buffer's process. An
670 error is signaled if the current buffer has no process.
672 The function returns @var{process-name}.
676 (process-send-eof "shell")
682 @node Signals to Processes
683 @section Sending Signals to Processes
684 @cindex process signals
685 @cindex sending signals
688 @dfn{Sending a signal} to a subprocess is a way of interrupting its
689 activities. There are several different signals, each with its own
690 meaning. The set of signals and their names is defined by the operating
691 system. For example, the signal @code{SIGINT} means that the user has
692 typed @kbd{C-c}, or that some analogous thing has happened.
694 Each signal has a standard effect on the subprocess. Most signals
695 kill the subprocess, but some stop or resume execution instead. Most
696 signals can optionally be handled by programs; if the program handles
697 the signal, then we can say nothing in general about its effects.
699 The set of signals and their names is defined by the operating system;
700 XEmacs has facilities for sending only a few of the signals that are
701 defined. XEmacs can send signals only to its own subprocesses.
703 You can send signals explicitly by calling the functions in this
704 section. XEmacs also sends signals automatically at certain times:
705 killing a buffer sends a @code{SIGHUP} signal to all its associated
706 processes; killing XEmacs sends a @code{SIGHUP} signal to all remaining
707 processes. (@code{SIGHUP} is a signal that usually indicates that the
708 user hung up the phone.)
710 Each of the signal-sending functions takes two optional arguments:
711 @var{process-name} and @var{current-group}.
713 The argument @var{process-name} must be either a process, the name of
714 one, or @code{nil}. If it is @code{nil}, the process defaults to the
715 process associated with the current buffer. An error is signaled if
716 @var{process-name} does not identify a process.
718 The argument @var{current-group} is a flag that makes a difference
719 when you are running a job-control shell as an XEmacs subprocess. If it
720 is non-@code{nil}, then the signal is sent to the current process-group
721 of the terminal that XEmacs uses to communicate with the subprocess. If
722 the process is a job-control shell, this means the shell's current
723 subjob. If it is @code{nil}, the signal is sent to the process group of
724 the immediate subprocess of XEmacs. If the subprocess is a job-control
725 shell, this is the shell itself.
727 The flag @var{current-group} has no effect when a pipe is used to
728 communicate with the subprocess, because the operating system does not
729 support the distinction in the case of pipes. For the same reason,
730 job-control shells won't work when a pipe is used. See
731 @code{process-connection-type} in @ref{Asynchronous Processes}.
733 @defun interrupt-process &optional process-name current-group
734 This function interrupts the process @var{process-name} by sending the
735 signal @code{SIGINT}. Outside of XEmacs, typing the ``interrupt
736 character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
737 others) sends this signal. When the argument @var{current-group} is
738 non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
739 on the terminal by which XEmacs talks to the subprocess.
742 @defun kill-process &optional process-name current-group
743 This function kills the process @var{process-name} by sending the
744 signal @code{SIGKILL}. This signal kills the subprocess immediately,
745 and cannot be handled by the subprocess.
748 @defun quit-process &optional process-name current-group
749 This function sends the signal @code{SIGQUIT} to the process
750 @var{process-name}. This signal is the one sent by the ``quit
751 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
755 @defun stop-process &optional process-name current-group
756 This function stops the process @var{process-name} by sending the
757 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
760 On systems with job control, the ``stop character'' (usually @kbd{C-z})
761 sends this signal (outside of XEmacs). When @var{current-group} is
762 non-@code{nil}, you can think of this function as ``typing @kbd{C-z}''
763 on the terminal XEmacs uses to communicate with the subprocess.
766 @defun continue-process &optional process-name current-group
767 This function resumes execution of the process @var{process} by sending
768 it the signal @code{SIGCONT}. This presumes that @var{process-name} was
773 @defun signal-process pid signal
774 This function sends a signal to process @var{pid}, which need not be
775 a child of XEmacs. The argument @var{signal} specifies which signal
776 to send; it should be an integer.
779 @node Output from Processes
780 @section Receiving Output from Processes
781 @cindex process output
782 @cindex output from processes
784 There are two ways to receive the output that a subprocess writes to
785 its standard output stream. The output can be inserted in a buffer,
786 which is called the associated buffer of the process, or a function
787 called the @dfn{filter function} can be called to act on the output. If
788 the process has no buffer and no filter function, its output is
792 * Process Buffers:: If no filter, output is put in a buffer.
793 * Filter Functions:: Filter functions accept output from the process.
794 * Accepting Output:: Explicitly permitting subprocess output.
795 Waiting for subprocess output.
798 @node Process Buffers
799 @subsection Process Buffers
801 A process can (and usually does) have an @dfn{associated buffer},
802 which is an ordinary Emacs buffer that is used for two purposes: storing
803 the output from the process, and deciding when to kill the process. You
804 can also use the buffer to identify a process to operate on, since in
805 normal practice only one process is associated with any given buffer.
806 Many applications of processes also use the buffer for editing input to
807 be sent to the process, but this is not built into XEmacs Lisp.
809 Unless the process has a filter function (@pxref{Filter Functions}),
810 its output is inserted in the associated buffer. The position to insert
811 the output is determined by the @code{process-mark}, which is then
812 updated to point to the end of the text just inserted. Usually, but not
813 always, the @code{process-mark} is at the end of the buffer.
815 @defun process-buffer process
816 This function returns the associated buffer of the process
821 (process-buffer (get-process "shell"))
822 @result{} #<buffer *shell*>
827 @defun process-mark process
828 This function returns the process marker for @var{process}, which is the
829 marker that says where to insert output from the process.
831 If @var{process} does not have a buffer, @code{process-mark} returns a
832 marker that points nowhere.
834 Insertion of process output in a buffer uses this marker to decide where
835 to insert, and updates it to point after the inserted text. That is why
836 successive batches of output are inserted consecutively.
838 Filter functions normally should use this marker in the same fashion
839 as is done by direct insertion of output in the buffer. A good
840 example of a filter function that uses @code{process-mark} is found at
841 the end of the following section.
843 When the user is expected to enter input in the process buffer for
844 transmission to the process, the process marker is useful for
845 distinguishing the new input from previous output.
848 @defun set-process-buffer process buffer
849 This function sets the buffer associated with @var{process} to
850 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
851 associated with no buffer.
854 @defun get-buffer-process buffer-or-name
855 This function returns the process associated with @var{buffer-or-name}.
856 If there are several processes associated with it, then one is chosen.
857 (Presently, the one chosen is the one most recently created.) It is
858 usually a bad idea to have more than one process associated with the
863 (get-buffer-process "*shell*")
864 @result{} #<process shell>
868 Killing the process's buffer deletes the process, which kills the
869 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
872 @node Filter Functions
873 @subsection Process Filter Functions
874 @cindex filter function
875 @cindex process filter
877 A process @dfn{filter function} is a function that receives the
878 standard output from the associated process. If a process has a filter,
879 then @emph{all} output from that process is passed to the filter. The
880 process buffer is used directly for output from the process only when
883 A filter function must accept two arguments: the associated process and
884 a string, which is the output. The function is then free to do whatever it
885 chooses with the output.
887 A filter function runs only while XEmacs is waiting (e.g., for terminal
888 input, or for time to elapse, or for process output). This avoids the
889 timing errors that could result from running filters at random places in
890 the middle of other Lisp programs. You may explicitly cause Emacs to
891 wait, so that filter functions will run, by calling @code{sit-for} or
892 @code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output}
893 (@pxref{Accepting Output}). Emacs is also waiting when the command loop
896 Quitting is normally inhibited within a filter function---otherwise,
897 the effect of typing @kbd{C-g} at command level or to quit a user
898 command would be unpredictable. If you want to permit quitting inside a
899 filter function, bind @code{inhibit-quit} to @code{nil}.
902 If an error happens during execution of a filter function, it is
903 caught automatically, so that it doesn't stop the execution of whatever
904 program was running when the filter function was started. However, if
905 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
906 off. This makes it possible to use the Lisp debugger to debug the
907 filter function. @xref{Debugger}.
909 Many filter functions sometimes or always insert the text in the
910 process's buffer, mimicking the actions of XEmacs when there is no
911 filter. Such filter functions need to use @code{set-buffer} in order to
912 be sure to insert in that buffer. To avoid setting the current buffer
913 semipermanently, these filter functions must use @code{unwind-protect}
914 to make sure to restore the previous current buffer. They should also
915 update the process marker, and in some cases update the value of point.
916 Here is how to do these things:
920 (defun ordinary-insertion-filter (proc string)
921 (let ((old-buffer (current-buffer)))
924 (set-buffer (process-buffer proc))
925 (setq moving (= (point) (process-mark proc)))
929 ;; @r{Insert the text, moving the process-marker.}
930 (goto-char (process-mark proc))
932 (set-marker (process-mark proc) (point)))
933 (if moving (goto-char (process-mark proc))))
934 (set-buffer old-buffer))))
939 The reason to use an explicit @code{unwind-protect} rather than letting
940 @code{save-excursion} restore the current buffer is so as to preserve
941 the change in point made by @code{goto-char}.
943 To make the filter force the process buffer to be visible whenever new
944 text arrives, insert the following line just before the
945 @code{unwind-protect}:
948 (display-buffer (process-buffer proc))
951 To force point to move to the end of the new output no matter where
952 it was previously, eliminate the variable @code{moving} and call
953 @code{goto-char} unconditionally.
955 In earlier Emacs versions, every filter function that did regexp
956 searching or matching had to explicitly save and restore the match data.
957 Now Emacs does this automatically; filter functions never need to do it
958 explicitly. @xref{Match Data}.
960 A filter function that writes the output into the buffer of the
961 process should check whether the buffer is still alive. If it tries to
962 insert into a dead buffer, it will get an error. If the buffer is dead,
963 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
965 The output to the function may come in chunks of any size. A program
966 that produces the same output twice in a row may send it as one batch
967 of 200 characters one time, and five batches of 40 characters the next.
969 @defun set-process-filter process filter
970 This function gives @var{process} the filter function @var{filter}. If
971 @var{filter} is @code{nil}, then the process will have no filter. If
972 @var{filter} is @code{t}, then no output from the process will be
973 accepted until the filter is changed. (Output received during this
974 time is not discarded, but is queued, and will be processed as soon
975 as the filter is changed.)
978 @defun process-filter process
979 This function returns the filter function of @var{process}, or @code{nil}
980 if it has none. @code{t} means that output processing has been stopped.
983 Here is an example of use of a filter function:
987 (defun keep-output (process output)
988 (setq kept (cons output kept)))
989 @result{} keep-output
996 (set-process-filter (get-process "shell") 'keep-output)
997 @result{} keep-output
1000 (process-send-string "shell" "ls ~/other\n")
1003 @result{} ("lewis@@slug[8] % "
1006 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
1007 address.txt backup.psf kolstad.psf
1008 backup.bib~ david.mss resume-Dec-86.mss~
1009 backup.err david.psf resume-Dec.psf
1010 backup.mss dland syllabus.mss
1012 "#backups.mss# backup.mss~ kolstad.mss
1017 @ignore @c The code in this example doesn't show the right way to do things.
1018 Here is another, more realistic example, which demonstrates how to use
1019 the process mark to do insertion in the same fashion as is done when
1020 there is no filter function:
1024 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
1025 ;; @r{and make sure that buffer is shown in some window.}
1026 (defun my-process-filter (proc str)
1027 (let ((cur (selected-window))
1029 (pop-to-buffer my-shell-buffer)
1032 (goto-char (point-max))
1034 (set-marker (process-mark proc) (point-max))
1035 (select-window cur)))
1040 @node Accepting Output
1041 @subsection Accepting Output from Processes
1043 Output from asynchronous subprocesses normally arrives only while
1044 XEmacs is waiting for some sort of external event, such as elapsed time
1045 or terminal input. Occasionally it is useful in a Lisp program to
1046 explicitly permit output to arrive at a specific point, or even to wait
1047 until output arrives from a process.
1049 @defun accept-process-output &optional process seconds millisec
1050 This function allows XEmacs to read pending output from processes. The
1051 output is inserted in the associated buffers or given to their filter
1052 functions. If @var{process} is non-@code{nil} then this function does
1053 not return until some output has been received from @var{process}.
1056 The arguments @var{seconds} and @var{millisec} let you specify timeout
1057 periods. The former specifies a period measured in seconds and the
1058 latter specifies one measured in milliseconds. The two time periods
1059 thus specified are added together, and @code{accept-process-output}
1060 returns after that much time whether or not there has been any
1061 subprocess output. Note that @var{seconds} is allowed to be a
1062 floating-point number; thus, there is no need to ever use
1063 @var{millisec}. (It is retained for compatibility purposes.)
1064 @ignore Not in XEmacs
1066 The argument @var{seconds} need not be an integer. If it is a floating
1067 point number, this function waits for a fractional number of seconds.
1068 Some systems support only a whole number of seconds; on these systems,
1069 @var{seconds} is rounded down. If the system doesn't support waiting
1070 fractions of a second, you get an error if you specify nonzero
1073 Not all operating systems support waiting periods other than multiples
1074 of a second; on those that do not, you get an error if you specify
1075 nonzero @var{millisec}.
1078 The function @code{accept-process-output} returns non-@code{nil} if it
1079 did get some output, or @code{nil} if the timeout expired before output
1084 @section Sentinels: Detecting Process Status Changes
1085 @cindex process sentinel
1088 A @dfn{process sentinel} is a function that is called whenever the
1089 associated process changes status for any reason, including signals
1090 (whether sent by XEmacs or caused by the process's own actions) that
1091 terminate, stop, or continue the process. The process sentinel is also
1092 called if the process exits. The sentinel receives two arguments: the
1093 process for which the event occurred, and a string describing the type
1096 The string describing the event looks like one of the following:
1100 @code{"finished\n"}.
1103 @code{"exited abnormally with code @var{exitcode}\n"}.
1106 @code{"@var{name-of-signal}\n"}.
1109 @code{"@var{name-of-signal} (core dumped)\n"}.
1112 A sentinel runs only while XEmacs is waiting (e.g., for terminal input,
1113 or for time to elapse, or for process output). This avoids the timing
1114 errors that could result from running them at random places in the
1115 middle of other Lisp programs. A program can wait, so that sentinels
1116 will run, by calling @code{sit-for} or @code{sleep-for}
1117 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
1118 Output}). Emacs is also waiting when the command loop is reading input.
1120 Quitting is normally inhibited within a sentinel---otherwise, the
1121 effect of typing @kbd{C-g} at command level or to quit a user command
1122 would be unpredictable. If you want to permit quitting inside a
1123 sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}.
1125 A sentinel that writes the output into the buffer of the process
1126 should check whether the buffer is still alive. If it tries to insert
1127 into a dead buffer, it will get an error. If the buffer is dead,
1128 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
1130 If an error happens during execution of a sentinel, it is caught
1131 automatically, so that it doesn't stop the execution of whatever
1132 programs was running when the sentinel was started. However, if
1133 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1134 off. This makes it possible to use the Lisp debugger to debug the
1135 sentinel. @xref{Debugger}.
1137 In earlier Emacs versions, every sentinel that did regexp searching or
1138 matching had to explicitly save and restore the match data. Now Emacs
1139 does this automatically; sentinels never need to do it explicitly.
1142 @defun set-process-sentinel process sentinel
1143 This function associates @var{sentinel} with @var{process}. If
1144 @var{sentinel} is @code{nil}, then the process will have no sentinel.
1145 The default behavior when there is no sentinel is to insert a message in
1146 the process's buffer when the process status changes.
1150 (defun msg-me (process event)
1152 (format "Process: %s had the event `%s'" process event)))
1153 (set-process-sentinel (get-process "shell") 'msg-me)
1157 (kill-process (get-process "shell"))
1158 @print{} Process: #<process shell> had the event `killed'
1159 @result{} #<process shell>
1164 @defun process-sentinel process
1165 This function returns the sentinel of @var{process}, or @code{nil} if it
1169 @defun waiting-for-user-input-p
1170 While a sentinel or filter function is running, this function returns
1171 non-@code{nil} if XEmacs was waiting for keyboard input from the user at
1172 the time the sentinel or filter function was called, @code{nil} if it
1177 @node Process Window Size
1178 @section Process Window Size
1179 @cindex process window size
1181 @defun set-process-window-size process height width
1182 This function tells @var{process} that its logical window size is
1183 @var{height} by @var{width} characters. This is principally useful
1187 @node Transaction Queues
1188 @section Transaction Queues
1189 @cindex transaction queue
1191 You can use a @dfn{transaction queue} for more convenient communication
1192 with subprocesses using transactions. First use @code{tq-create} to
1193 create a transaction queue communicating with a specified process. Then
1194 you can call @code{tq-enqueue} to send a transaction.
1196 @defun tq-create process
1197 This function creates and returns a transaction queue communicating with
1198 @var{process}. The argument @var{process} should be a subprocess
1199 capable of sending and receiving streams of bytes. It may be a child
1200 process, or it may be a TCP connection to a server, possibly on another
1204 @defun tq-enqueue queue question regexp closure fn
1205 This function sends a transaction to queue @var{queue}. Specifying the
1206 queue has the effect of specifying the subprocess to talk to.
1208 The argument @var{question} is the outgoing message that starts the
1209 transaction. The argument @var{fn} is the function to call when the
1210 corresponding answer comes back; it is called with two arguments:
1211 @var{closure}, and the answer received.
1213 The argument @var{regexp} is a regular expression that should match the
1214 entire answer, but nothing less; that's how @code{tq-enqueue} determines
1215 where the answer ends.
1217 The return value of @code{tq-enqueue} itself is not meaningful.
1220 @defun tq-close queue
1221 Shut down transaction queue @var{queue}, waiting for all pending transactions
1222 to complete, and then terminate the connection or child process.
1225 Transaction queues are implemented by means of a filter function.
1226 @xref{Filter Functions}.
1229 @section Network Connections
1230 @cindex network connection
1233 XEmacs Lisp programs can open TCP network connections to other processes on
1234 the same machine or other machines. A network connection is handled by Lisp
1235 much like a subprocess, and is represented by a process object.
1236 However, the process you are communicating with is not a child of the
1237 XEmacs process, so you can't kill it or send it signals. All you can do
1238 is send and receive data. @code{delete-process} closes the connection,
1239 but does not kill the process at the other end; that process must decide
1240 what to do about closure of the connection.
1242 You can distinguish process objects representing network connections
1243 from those representing subprocesses with the @code{process-status}
1244 function. It always returns either @code{open} or @code{closed} for a
1245 network connection, and it never returns either of those values for a
1246 real subprocess. @xref{Process Information}.
1248 @defun open-network-stream name buffer-or-name host service
1249 This function opens a TCP connection for a service to a host. It
1250 returns a process object to represent the connection.
1252 The @var{name} argument specifies the name for the process object. It
1253 is modified as necessary to make it unique.
1255 The @var{buffer-or-name} argument is the buffer to associate with the
1256 connection. Output from the connection is inserted in the buffer,
1257 unless you specify a filter function to handle the output. If
1258 @var{buffer-or-name} is @code{nil}, it means that the connection is not
1259 associated with any buffer.
1261 The arguments @var{host} and @var{service} specify where to connect to;
1262 @var{host} is the host name or IP address (a string), and @var{service}
1263 is the name of a defined network service (a string) or a port number (an