2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/processes.info
8 @node Processes, System Interface, Databases, Top
11 @cindex parent process
15 In the terminology of operating systems, a @dfn{process} is a space in
16 which a program can execute. SXEmacs runs in a process. SXEmacs Lisp
17 programs can invoke other programs in processes of their own. These are
18 called @dfn{subprocesses} or @dfn{child processes} of the SXEmacs process,
19 which is their @dfn{parent process}.
21 A subprocess of SXEmacs may be @dfn{synchronous} or @dfn{asynchronous},
22 depending on how it is created. When you create a synchronous
23 subprocess, the Lisp program waits for the subprocess to terminate
24 before continuing execution. When you create an asynchronous
25 subprocess, it can run in parallel with the Lisp program. This kind of
26 subprocess is represented within SXEmacs by a Lisp object which is also
27 called a ``process''. Lisp programs can use this object to communicate
28 with the subprocess or to control it. For example, you can send
29 signals, obtain status information, receive output from the process, or
32 @defun processp object
33 This function returns @code{t} if @var{object} is a process,
38 * Subprocess Creation:: Functions that start subprocesses.
39 * Synchronous Processes:: Details of using synchronous subprocesses.
40 * Asynchronous Processes:: Starting up an asynchronous subprocess.
41 * Deleting Processes:: Eliminating an asynchronous subprocess.
42 * Process Information:: Accessing run-status and other attributes.
43 * Input to Processes:: Sending input to an asynchronous subprocess.
44 * Signals to Processes:: Stopping, continuing or interrupting
45 an asynchronous subprocess.
46 * Output from Processes:: Collecting output from an asynchronous subprocess.
47 * Sentinels:: Sentinels run when process run-status changes.
48 * Process Window Size:: Changing the logical window size of a process.
49 * Transaction Queues:: Transaction-based communication with subprocesses.
50 * Network:: Opening network connections.
54 @node Subprocess Creation
55 @section Functions that Create Subprocesses
57 There are three functions that create a new subprocess in which to run
58 a program. One of them, @code{start-process}, creates an asynchronous
59 process and returns a process object (@pxref{Asynchronous Processes}).
60 The other two, @code{call-process} and @code{call-process-region},
61 create a synchronous process and do not return a process object
62 (@pxref{Synchronous Processes}).
64 Synchronous and asynchronous processes are explained in the following
65 sections. Since the three functions are all called in a similar
66 fashion, their common arguments are described here.
68 @cindex execute program
69 @cindex @code{PATH} environment variable
70 @cindex @code{HOME} environment variable
71 In all cases, the function's @var{program} argument specifies the
72 program to be run. An error is signaled if the file is not found or
73 cannot be executed. If the file name is relative, the variable
74 @code{exec-path} contains a list of directories to search. SXEmacs
75 initializes @code{exec-path} when it starts up, based on the value of
76 the environment variable @code{PATH}. The standard file name
77 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usual
78 in @code{exec-path}, but environment variable substitutions
79 (@samp{$HOME}, etc.) are not recognized; use
80 @code{substitute-in-file-name} to perform them (@pxref{File Name
83 Each of the subprocess-creating functions has a @var{buffer-or-name}
84 argument which specifies where the standard output from the program will
85 go. If @var{buffer-or-name} is @code{nil}, that says to discard the
86 output unless a filter function handles it. (@xref{Filter Functions},
87 and @ref{Read and Print}.) Normally, you should avoid having multiple
88 processes send output to the same buffer because their output would be
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 are not allowed in these strings,
96 since they are passed directly to the specified program.
98 @strong{Please note:} The argument @var{program} contains only the
99 name of the program; it may not contain any command-line arguments. You
100 must use @var{args} to provide those.
102 If you want to use features of the shell, then invoke the shell directly
103 using, for example, @var{program} of @code{"sh"}, and @var{args} of
104 @code{"-c"} and @var{"command line..."}.
106 The subprocess gets its current directory from the value of
107 @code{default-directory} (@pxref{File Name Expansion}).
109 @cindex environment variables, subprocesses
110 The subprocess inherits its environment from SXEmacs; but you can
111 specify overrides for it with @code{process-environment}. @xref{System
114 @defvar exec-directory
116 The value of this variable is the name of a directory (a string) that
117 contains programs that come with SXEmacs, that are intended for SXEmacs
118 to invoke. The program @code{wakeup} is an example of such a program;
119 the @code{display-time} command uses it to get a reminder once per
124 The value of this variable is a list of directories to search for
125 programs to run in subprocesses. Each element is either the name of a
126 directory (i.e., a string), or @code{nil}, which stands for the default
127 directory (which is the value of @code{default-directory}).
128 @cindex program directories
130 The value of @code{exec-path} is used by @code{call-process} and
131 @code{start-process} when the @var{program} argument is not an absolute
136 @node Synchronous Processes
137 @section Creating a Synchronous Process
138 @cindex synchronous subprocess
140 After a @dfn{synchronous process} is created, SXEmacs waits for the
141 process to terminate before continuing. Starting Dired is an example of
142 this: it runs @code{ls} in a synchronous process, then modifies the
143 output slightly. Because the process is synchronous, the entire
144 directory listing arrives in the buffer before SXEmacs tries to do
147 While SXEmacs waits for the synchronous subprocess to terminate, the
148 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
149 the subprocess with a @code{SIGINT} signal; but it waits until the
150 subprocess actually terminates before quitting. If during that time the
151 user types another @kbd{C-g}, that kills the subprocess instantly with
152 @code{SIGKILL} and quits immediately. @xref{Quitting}.
154 Note: The synchronous subprocess functions returned @code{nil} in
155 FSF Emacs 18. In version 19, they return an indication of how the
158 @defun call-process program &optional infile destination display &rest args
159 This function calls @var{program} in a separate process and waits for
162 The standard input for the process comes from file @var{infile} if
163 @var{infile} is not @code{nil} and from @file{/dev/null} otherwise.
164 The argument @var{destination} says where to put the process output.
165 Here are the possibilities:
169 Insert the output in that buffer, before point. This includes both the
170 standard output stream and the standard error stream of the process.
173 Find or create a buffer with that name, then insert
174 the output in that buffer, before point.
177 Insert the output in the current buffer, before point.
183 Discard the output, and return immediately without waiting
184 for the subprocess to finish.
186 In this case, the process is not truly synchronous, since it can run in
187 parallel with SXEmacs; but you can think of it as synchronous in that
188 SXEmacs is essentially finished with the subprocess as soon as this
191 @item (@var{real-destination} @var{error-destination})
192 Keep the standard output stream separate from the standard error stream;
193 deal with the ordinary output as specified by @var{real-destination},
194 and dispose of the error output according to @var{error-destination}.
195 The value @code{nil} means discard it, @code{t} means mix it with the
196 ordinary output, and a string specifies a file name to redirect error
199 You can't directly specify a buffer to put the error output in; that is
200 too difficult to implement. But you can achieve this result by sending
201 the error output to a temporary file and then inserting the file into a
205 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
206 the buffer as output is inserted. Otherwise the function does no
207 redisplay, and the results become visible on the screen only when SXEmacs
208 redisplays that buffer in the normal course of events.
210 The remaining arguments, @var{args}, are strings that specify command
211 line arguments for the program.
213 The value returned by @code{call-process} (unless you told it not to
214 wait) indicates the reason for process termination. A number gives the
215 exit status of the subprocess; 0 means success, and any other value
216 means failure. If the process terminated with a signal,
217 @code{call-process} returns a string describing the signal.
219 In the examples below, the buffer @samp{foo} is current.
223 (call-process "pwd" nil t)
226 ---------- Buffer: foo ----------
227 /usr/user/lewis/manual
228 ---------- Buffer: foo ----------
232 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
235 ---------- Buffer: bar ----------
236 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
238 ---------- Buffer: bar ----------
242 The @code{insert-directory} function contains a good example of the use
243 of @code{call-process}:
247 (call-process insert-directory-program nil t nil switches
249 (concat (file-name-as-directory file) ".")
255 @defun call-process-region start end program &optional deletep destination displayp &rest args
256 This function sends the text between @var{start} to @var{end} as
257 standard input to a process running @var{program}. It deletes the text
258 sent if @var{deletep} is non-@code{nil}; this is useful when @var{buffer}
259 is @code{t}, to insert the output in the current buffer.
261 The arguments @var{destination} and @var{displayp} control what to do
262 with the output from the subprocess, and whether to update the display
263 as it comes in. For details, see the description of
264 @code{call-process}, above. If @var{destination} is the integer 0,
265 @code{call-process-region} discards the output and returns @code{nil}
266 immediately, without waiting for the subprocess to finish.
268 The remaining arguments, @var{args}, are strings that specify command
269 line arguments for the program.
271 The return value of @code{call-process-region} is just like that of
272 @code{call-process}: @code{nil} if you told it to return without
273 waiting; otherwise, a number or string which indicates how the
274 subprocess terminated.
276 In the following example, we use @code{call-process-region} to run the
277 @code{cat} utility, with standard input being the first five characters
278 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
279 standard input into its standard output. Since the argument
280 @var{destination} is @code{t}, this output is inserted in the current
285 ---------- Buffer: foo ----------
287 ---------- Buffer: foo ----------
291 (call-process-region 1 6 "cat" nil t)
294 ---------- Buffer: foo ----------
296 ---------- Buffer: foo ----------
300 The @code{shell-command-on-region} command uses
301 @code{call-process-region} like this:
307 shell-file-name ; @r{Name of program.}
308 nil ; @r{Do not delete region.}
309 buffer ; @r{Send output to @code{buffer}.}
310 nil ; @r{No redisplay during output.}
311 "-c" command) ; @r{Arguments for the shell.}
317 @node Asynchronous Processes
318 @section Creating an Asynchronous Process
319 @cindex asynchronous subprocess
321 After an @dfn{asynchronous process} is created, SXEmacs and the Lisp
322 program both continue running immediately. The process may thereafter
323 run in parallel with SXEmacs, and the two may communicate with each other
324 using the functions described in following sections. Here we describe
325 how to create an asynchronous process with @code{start-process}.
327 @defun start-process name buffer-or-name program &rest args
328 This function creates a new asynchronous subprocess and starts the
329 program @var{program} running in it. It returns a process object that
330 stands for the new subprocess in Lisp. The argument @var{name}
331 specifies the name for the process object; if a process with this name
332 already exists, then @var{name} is modified (by adding @samp{<1>}, etc.)
333 to be unique. The buffer @var{buffer-or-name} is the buffer to
334 associate with the process.
336 The remaining arguments, @var{args}, are strings that specify command
337 line arguments for the program.
339 In the example below, the first process is started and runs (rather,
340 sleeps) for 100 seconds. Meanwhile, the second process is started, and
341 given the name @samp{my-process<1>} for the sake of uniqueness. It
342 inserts the directory listing at the end of the buffer @samp{foo},
343 before the first process finishes. Then it finishes, and a message to
344 that effect is inserted in the buffer. Much later, the first process
345 finishes, and another message is inserted in the buffer for it.
349 (start-process "my-process" "foo" "sleep" "100")
350 @result{} #<process my-process>
354 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
355 @result{} #<process my-process<1>>
357 ---------- Buffer: foo ----------
359 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
360 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
362 Process my-process<1> finished
364 Process my-process finished
365 ---------- Buffer: foo ----------
370 @defun start-process-shell-command name buffer-or-name command &rest command-args
371 This function is like @code{start-process} except that it uses a shell
372 to execute the specified command. The argument @var{command} is a shell
373 command name, and @var{command-args} are the arguments for the shell
377 @defvar process-connection-type
380 This variable controls the type of device used to communicate with
381 asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are
382 used, when available. Otherwise, pipes are used.
384 @sc{pty}s are usually preferable for processes visible to the user, as
385 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
386 etc.) to work between the process and its children whereas pipes do not.
387 For subprocesses used for internal purposes by programs, it is often
388 better to use a pipe, because they are more efficient. In addition, the
389 total number of @sc{pty}s is limited on many systems and it is good not
390 to waste them. A rule of thumb is to use ptys for processes the user
391 interacts with directly, and pipes for processes that are hidden from
394 The value @code{process-connection-type} is used when
395 @code{start-process} is called. So you can specify how to communicate
396 with one subprocess by binding the variable around the call to
397 @code{start-process}.
401 (let ((process-connection-type nil)) ; @r{Use a pipe.}
402 (start-process @dots{}))
406 To determine whether a given subprocess actually got a pipe or a
407 @sc{pty}, use the function @code{process-tty-name} (@pxref{Process
411 Lisp functions that manipulate processes usually accept a @var{process}
412 argument. Besides using an actual process object for this argument, you
413 can use a process name, a buffer object, the name of a buffer, or
414 @code{nil}. Specifying a buffer or buffer name for the @var{process}
415 argument means use the process associated with the buffer (or the most
416 recent one, if there is more than one). @code{nil} means use the
417 process associated with the current buffer.
418 @xref{Process Information}.
419 @xref{Process Buffers}.
422 @node Deleting Processes
423 @section Deleting Processes
424 @cindex deleting processes
426 @dfn{Deleting a process} disconnects SXEmacs immediately from the
427 subprocess, and removes it from the list of active processes. It sends
428 a signal to the subprocess to make the subprocess terminate, but this is
429 not guaranteed to happen immediately. The process object itself
430 continues to exist as long as other Lisp objects point to it.
432 You can delete a process explicitly at any time. Processes are
433 deleted automatically after they terminate, but not necessarily right
434 away. If you delete a terminated process explicitly before it is
435 deleted automatically, no harm results.
437 @defvar delete-exited-processes
438 This variable controls automatic deletion of processes that have
439 terminated (due to calling @code{exit} or to a signal). If it is
440 @code{nil}, then they continue to exist until the user runs
441 @code{list-processes}. Otherwise, they are deleted immediately after
445 @defun delete-process name
446 This function deletes the process associated with @var{name}, killing it
447 with a @code{SIGHUP} signal. The argument @var{name} may be a process,
448 the name of a process, a buffer, or the name of a buffer.
452 (delete-process "*shell*")
458 @defun process-kill-without-query process &optional require-query-p
459 This function declares that SXEmacs need not query the user if
460 @var{process} is still running when SXEmacs is exited. The process will
461 be deleted silently. If @var{require-query-p} is non-@code{nil},
462 then SXEmacs @emph{will} query the user (this is the default). The
463 return value is @code{t} if a query was formerly required, and
464 @code{nil} otherwise.
468 (process-kill-without-query (get-process "shell"))
475 @node Process Information
476 @section Process Information
478 Several functions return information about processes.
479 @code{list-processes} is provided for interactive use.
481 @deffn Command list-processes
482 This command displays a listing of all living processes. In addition,
483 it finally deletes any process whose status was @samp{Exited} or
484 @samp{Signaled}. It returns @code{nil}.
488 This function returns a list of all processes that have not been deleted.
493 @result{} (#<process display-time> #<process shell>)
498 @defun get-process process-name
499 This function returns the process named @var{process-name}. If
500 @var{process-name} is a string and there is no process with that name, the
501 value is @code{nil}. If @var{process-name} is actually a process, it is
502 returned as given. (That is not very useful, so the argument is usually
503 a name.) For example:
507 (get-process "shell")
508 @result{} #<process shell>
513 @defun process-command process
514 This function returns the command that was executed to start
515 @var{process}. This is a list of strings, the first string being the
516 program executed and the rest of the strings being the arguments that
517 were given to the program.
521 (process-command (get-process "shell"))
522 @result{} ("/bin/csh" "-i")
527 @defun process-id process
528 This function returns the @sc{pid} of @var{process}. This is an
529 integer that distinguishes the process @var{process} from all other
530 processes running on the same computer at the current time. The
531 @sc{pid} of a process is chosen by the operating system kernel when the
532 process is started and remains constant as long as the process exists.
535 @defun process-name process
536 This function returns the name of @var{process}.
539 @defun process-status process
540 This function returns the status of @var{process} as a symbol.
541 The argument @var{process} must be a process, a buffer, a
542 process name (string) or a buffer name (string).
544 The possible values for an actual subprocess are:
548 for a process that is running.
550 for a process that is stopped but continuable.
552 for a process that has exited.
554 for a process that has received a fatal signal.
556 for a network connection that is open.
558 for a network connection that is closed. Once a connection
559 is closed, you cannot reopen it, though you might be able to open
560 a new connection to the same place.
562 if @var{process} does not identify an existing process.
567 (process-status "shell")
571 (process-status (get-buffer "*shell*"))
576 @result{} #<process xx<1>>
582 For a network connection, @code{process-status} returns one of the symbols
583 @code{open} or @code{closed}. The latter means that the other side
584 closed the connection, or SXEmacs did @code{delete-process}.
586 In earlier Emacs versions (prior to version 19), the status of a network
587 connection was @code{run} if open, and @code{exit} if closed.
590 @defun process-kill-without-query-p process
591 This function returns whether @var{process} will be killed without
592 querying the user, if it is running when SXEmacs is exited. The default
596 @defun process-exit-status process
597 This function returns the exit status of @var{process} or the signal
598 number that killed it. (Use the result of @code{process-status} to
599 determine which of those it is.) If @var{process} has not yet
600 terminated, the value is 0.
603 @defun process-tty-name process
604 This function returns the terminal name that @var{process} is using for
605 its communication with SXEmacs---or @code{nil} if it is using pipes
606 instead of a terminal (see @code{process-connection-type} in
607 @ref{Asynchronous Processes}).
611 @node Input to Processes
612 @section Sending Input to Processes
613 @cindex process input
615 Asynchronous subprocesses receive input when it is sent to them by
616 SXEmacs, which is done with the functions in this section. You must
617 specify the process to send input to, and the input data to send. The
618 data appears on the ``standard input'' of the subprocess.
620 Some operating systems have limited space for buffered input in a
621 @sc{pty}. On these systems, SXEmacs sends long input in chunks, with
622 @sc{eof} characters added amidst the other characters, to force the
623 operating system to periodically drain the input buffer. For most
624 programs, these @sc{eof}s do no harm.
626 @defun process-send-string process string &optional start end
627 This function sends @var{process} the contents of @var{string} as
630 The argument @var{process} may be a process or the name of a process, or
631 a buffer or the name of a buffer, in which case the buffer's process is
632 used. If it is @code{nil}, the current buffer's process is used.
634 Optional arguments @var{start} and @var{end} specify part of @var{string};
635 see @code{substring}.
637 The function returns @code{nil}.
641 (process-send-string "shell<1>" "ls\n")
647 ---------- Buffer: *shell* ----------
649 introduction.texi syntax-tables.texi~
650 introduction.texi~ text.texi
651 introduction.txt text.texi~
653 ---------- Buffer: *shell* ----------
658 @defun process-send-region process start end &optional buffer
659 This function sends the text in the region defined by @var{start} and
660 @var{end} as standard input to @var{process}.
662 The argument @var{process} may be a process or the name of a process, or
663 a buffer or the name of a buffer, in which case the buffer's process is
664 used. If it is @code{nil}, the current buffer's process is used.
666 An error is signaled unless both @var{start} and @var{end} are
667 integers or markers that indicate positions in the current buffer. (It
668 is unimportant which number is larger.)
671 @defun process-send-eof &optional process
672 This function makes @var{process} see an end-of-file in its
673 input. The @sc{eof} comes after any text already sent to it.
675 @var{process} may be a process, a buffer, the name of a process or
676 buffer, or @code{nil}, indicating the current buffer's process. An
677 error is signaled if @var{process} does not identify any process.
679 The function returns the process object identified by @var{process}.
683 (process-send-eof "shell")
690 @node Signals to Processes
691 @section Sending Signals to Processes
692 @cindex process signals
693 @cindex sending signals
696 @dfn{Sending a signal} to a subprocess is a way of interrupting its
697 activities. There are several different signals, each with its own
698 meaning. The set of signals and their names is defined by the operating
699 system. For example, the signal @code{SIGINT} means that the user has
700 typed @kbd{C-c}, or that some analogous thing has happened.
702 Each signal has a standard effect on the subprocess. Most signals
703 kill the subprocess, but some stop or resume execution instead. Most
704 signals can optionally be handled by programs; if the program handles
705 the signal, then we can say nothing in general about its effects.
707 The set of signals and their names is defined by the operating system;
708 SXEmacs has facilities for sending only a few of the signals that are
709 defined. SXEmacs can send signals only to its own subprocesses.
711 You can send signals explicitly by calling the functions in this
712 section. SXEmacs also sends signals automatically at certain times:
713 killing a buffer sends a @code{SIGHUP} signal to all its associated
714 processes; killing SXEmacs sends a @code{SIGHUP} signal to all remaining
715 processes. @code{SIGHUP} is a signal that indicates that the
716 connection between the user and the process is broken, for example if a
717 connection via a telephone line is hung up.
719 Each of the signal-sending functions takes two optional arguments:
720 @var{process} and @var{current-group}.
722 The argument @var{process} must be either a process or a buffer,
723 the name of one, or @code{nil}. If it is @code{nil}, the process
724 defaults to the process associated with the current buffer. An error is
725 signaled if @var{process} does not identify a process.
727 The argument @var{current-group} is a flag that makes a difference
728 when you are running a job-control shell as an SXEmacs subprocess. If it
729 is non-@code{nil}, then the signal is sent to the current foreground
730 process group of the terminal that SXEmacs uses to communicate with the
731 subprocess. If the process is a job-control shell, this means the
732 shell's current subjob. If it is @code{nil}, the signal is sent to the
733 process group of the immediate subprocess of SXEmacs. If the subprocess
734 is a job-control shell, this is the shell itself.
736 The flag @var{current-group} has no effect when a pipe is used to
737 communicate with the subprocess, because the operating system does not
738 support the distinction in the case of pipes. For the same reason,
739 job-control shells won't work when a pipe is used. See
740 @code{process-connection-type} in @ref{Asynchronous Processes}.
742 Some of the functions below take a @var{signal} argument, which
743 identifies a signal to be sent. It must be either an integer or a
744 symbol which names the signal, like @code{SIGSEGV}.
746 @defun process-send-signal signal &optional process current-group
747 This function sends the signal @var{signal} to the process @var{process}.
748 The following functions can be implemented in terms of
749 @code{process-send-signal}.
752 @defun interrupt-process &optional process current-group
753 This function interrupts the process @var{process} by sending the signal
754 @code{SIGINT}. Outside of SXEmacs, typing the ``interrupt character''
755 (normally @kbd{C-c}) sends this signal. When the argument
756 @var{current-group} is non-@code{nil}, you can think of this function as
757 ``typing @kbd{C-c}'' on the terminal by which SXEmacs talks to the
761 @defun kill-process &optional process current-group
762 This function kills the process @var{process} by sending the
763 signal @code{SIGKILL}. This signal kills the subprocess immediately,
764 and cannot be handled by the subprocess.
767 @defun quit-process &optional process current-group
768 This function sends the signal @code{SIGQUIT} to the process
769 @var{process}. This signal is the one sent by the ``quit
770 character'' (usually @kbd{C-\}) when you are not inside SXEmacs.
773 @defun stop-process &optional process current-group
774 This function stops the process @var{process} by sending the
775 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
778 On systems with job control, the ``stop character'' (usually @kbd{C-z})
779 sends this signal (outside of SXEmacs). When @var{current-group} is
780 non-@code{nil}, you can think of this function as ``typing @kbd{C-z}''
781 on the terminal SXEmacs uses to communicate with the subprocess.
784 @defun continue-process &optional process current-group
785 This function resumes execution of the process @var{process} by sending
786 it the signal @code{SIGCONT}. This presumes that @var{process} was
790 @deffn Command signal-process pid signal
791 This function sends a signal to the process with process id @var{pid},
792 which need not be a child of SXEmacs. The argument @var{signal}
793 specifies which signal to send.
797 @node Output from Processes
798 @section Receiving Output from Processes
799 @cindex process output
800 @cindex output from processes
802 There are two ways to receive the output that a subprocess writes to
803 its standard output stream. The output can be inserted in a buffer,
804 which is called the associated buffer of the process, or a function
805 called the @dfn{filter function} can be called to act on the output. If
806 the process has no buffer and no filter function, its output is
810 * Process Buffers:: If no filter, output is put in a buffer.
811 * Filter Functions:: Filter functions accept output from the process.
812 * Accepting Output:: Explicitly permitting subprocess output.
813 Waiting for subprocess output.
817 @node Process Buffers
818 @subsection Process Buffers
820 A process can (and usually does) have an @dfn{associated buffer},
821 which is an ordinary SXEmacs buffer that is used for two purposes: storing
822 the output from the process, and deciding when to kill the process. You
823 can also use the buffer to identify a process to operate on, since in
824 normal practice only one process is associated with any given buffer.
825 Many applications of processes also use the buffer for editing input to
826 be sent to the process, but this is not built into SXEmacs Lisp.
828 Unless the process has a filter function (@pxref{Filter Functions}),
829 its output is inserted in the associated buffer. The position to insert
830 the output is determined by the @code{process-mark}, which is then
831 updated to point to the end of the text just inserted. Usually, but not
832 always, the @code{process-mark} is at the end of the buffer.
834 @defun process-buffer process
835 This function returns the associated buffer of the process
840 (process-buffer (get-process "shell"))
841 @result{} #<buffer *shell*>
846 @defun process-mark process
847 This function returns the process marker for @var{process}, which is the
848 marker that says where to insert output from the process.
850 If @var{process} does not have a buffer, @code{process-mark} returns a
851 marker that points nowhere.
853 Insertion of process output in a buffer uses this marker to decide where
854 to insert, and updates it to point after the inserted text. That is why
855 successive batches of output are inserted consecutively.
857 Filter functions normally should use this marker in the same fashion
858 as is done by direct insertion of output in the buffer. A good
859 example of a filter function that uses @code{process-mark} is found at
860 the end of the following section.
862 When the user is expected to enter input in the process buffer for
863 transmission to the process, the process marker is useful for
864 distinguishing the new input from previous output.
867 @defun set-process-buffer process buffer
868 This function sets the buffer associated with @var{process} to
869 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
870 associated with no buffer.
873 @defun get-buffer-process buffer-or-name
874 This function returns the process associated with @var{buffer-or-name}.
875 If there are several processes associated with @var{buffer-or-name},
876 then one is chosen. (Presently, the one chosen is the one most recently
877 created.) It is usually a bad idea to have more than one process
878 associated with the same buffer.
882 (get-buffer-process "*shell*")
883 @result{} #<process shell>
887 Killing the process's buffer deletes the process, which kills the
888 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
892 @node Filter Functions
893 @subsection Process Filter Functions
894 @cindex filter function
895 @cindex process filter
897 A process @dfn{filter function} is a function that receives the
898 standard output from the associated process. If a process has a filter,
899 then @emph{all} output from that process is passed to the filter. The
900 process buffer is used directly for output from the process only when
903 A filter function must accept two arguments: the associated process and
904 a string, which is the output. The function is then free to do whatever it
905 chooses with the output.
907 A filter function runs only while SXEmacs is waiting (e.g., for terminal
908 input, or for time to elapse, or for process output). This avoids the
909 timing errors that could result from running filters at random places in
910 the middle of other Lisp programs. You may explicitly cause SXEmacs to
911 wait, so that filter functions will run, by calling @code{sit-for} or
912 @code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output}
913 (@pxref{Accepting Output}). SXEmacs is also waiting when the command loop
916 Quitting is normally inhibited within a filter function---otherwise,
917 the effect of typing @kbd{C-g} at command level or to quit a user
918 command would be unpredictable. If you want to permit quitting inside a
919 filter function, bind @code{inhibit-quit} to @code{nil}.
922 If an error happens during execution of a filter function, it is
923 caught automatically, so that it doesn't stop the execution of whatever
924 program was running when the filter function was started. However, if
925 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
926 off. This makes it possible to use the Lisp debugger to debug the
927 filter function. @xref{Debugger}.
929 Many filter functions sometimes or always insert the text in the
930 process's buffer, mimicking the actions of SXEmacs when there is no
931 filter. Such filter functions need to use @code{set-buffer} in order to
932 be sure to insert in that buffer. To avoid setting the current buffer
933 semipermanently, these filter functions must use @code{unwind-protect}
934 to make sure to restore the previous current buffer. They should also
935 update the process marker, and in some cases update the value of point.
936 Here is how to do these things:
940 (defun ordinary-insertion-filter (process string)
941 (let ((old-buffer (current-buffer)))
944 (set-buffer (process-buffer process))
945 (setq moving (= (point) (process-mark process)))
949 ;; @r{Insert the text, moving the process-marker.}
950 (goto-char (process-mark process))
952 (set-marker (process-mark process) (point)))
953 (if moving (goto-char (process-mark process))))
954 (set-buffer old-buffer))))
959 The reason to use an explicit @code{unwind-protect} rather than letting
960 @code{save-excursion} restore the current buffer is so as to preserve
961 the change in point made by @code{goto-char}.
963 To make the filter force the process buffer to be visible whenever new
964 text arrives, insert the following line just before the
965 @code{unwind-protect}:
968 (display-buffer (process-buffer process))
971 To force point to move to the end of the new output no matter where
972 it was previously, eliminate the variable @code{moving} and call
973 @code{goto-char} unconditionally.
975 In earlier Emacs versions, every filter function that did regexp
976 searching or matching had to explicitly save and restore the match data.
977 SXEmacs does this automatically; filter functions never need to do it
978 explicitly. @xref{Match Data}.
980 A filter function that writes the output into the buffer of the
981 process should check whether the buffer is still alive. If it tries to
982 insert into a dead buffer, it will get an error. If the buffer is dead,
983 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
985 The output to the function may come in chunks of any size. A program
986 that produces the same output twice in a row may send it as one batch
987 of 200 characters one time, and five batches of 40 characters the next.
989 @defun set-process-filter process filter
990 This function gives @var{process} the filter function @var{filter}. If
991 @var{filter} is @code{nil}, then the process will have no filter. If
992 @var{filter} is @code{t}, then no output from the process will be
993 accepted until the filter is changed. (Output received during this
994 time is not discarded, but is queued, and will be processed as soon
995 as the filter is changed.)
998 @defun process-filter process
999 This function returns the filter function of @var{process}, or @code{nil}
1000 if it has none. @code{t} means that output processing has been stopped.
1003 Here is an example of use of a filter function:
1007 (defun keep-output (process output)
1008 (setq kept (cons output kept)))
1009 @result{} keep-output
1016 (set-process-filter (get-process "shell") 'keep-output)
1017 @result{} keep-output
1020 (process-send-string "shell" "ls ~/other\n")
1023 @result{} ("lewis@@slug[8] % "
1026 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
1027 address.txt backup.psf kolstad.psf
1028 backup.bib~ david.mss resume-Dec-86.mss~
1029 backup.err david.psf resume-Dec.psf
1030 backup.mss dland syllabus.mss
1032 "#backups.mss# backup.mss~ kolstad.mss
1037 @ignore @c The code in this example doesn't show the right way to do things.
1038 Here is another, more realistic example, which demonstrates how to use
1039 the process mark to do insertion in the same fashion as is done when
1040 there is no filter function:
1044 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
1045 ;; @r{and make sure that buffer is shown in some window.}
1046 (defun my-process-filter (process string)
1047 (let ((cur (selected-window))
1049 (pop-to-buffer my-shell-buffer)
1052 (goto-char (point-max))
1054 (set-marker (process-mark process) (point-max))
1055 (select-window cur)))
1061 @node Accepting Output
1062 @subsection Accepting Output from Processes
1064 Output from asynchronous subprocesses normally arrives only while
1065 SXEmacs is waiting for some sort of external event, such as elapsed time
1066 or terminal input. Occasionally it is useful in a Lisp program to
1067 explicitly permit output to arrive at a specific point, or even to wait
1068 until output arrives from a process.
1070 @defun accept-process-output &optional process seconds millisec
1071 This function allows SXEmacs to read pending output from processes. The
1072 output is inserted in the associated buffers or given to their filter
1073 functions. If @var{process} is non-@code{nil} then this function does
1074 not return until some output has been received from @var{process}.
1077 The arguments @var{seconds} and @var{millisec} let you specify timeout
1078 periods. The former specifies a period measured in seconds and the
1079 latter specifies one measured in milliseconds. The two time periods
1080 thus specified are added together, and @code{accept-process-output}
1081 returns after that much time whether or not there has been any
1082 subprocess output. Note that @var{seconds} is allowed to be a
1083 floating-point number; thus, there is no need to ever use
1084 @var{millisec}. (It is retained for compatibility purposes.)
1085 @ignore Not in SXEmacs
1087 The argument @var{seconds} need not be an integer. If it is a floating
1088 point number, this function waits for a fractional number of seconds.
1089 Some systems support only a whole number of seconds; on these systems,
1090 @var{seconds} is rounded down. If the system doesn't support waiting
1091 fractions of a second, you get an error if you specify nonzero
1094 Not all operating systems support waiting periods other than multiples
1095 of a second; on those that do not, you get an error if you specify
1096 nonzero @var{millisec}.
1099 The function @code{accept-process-output} returns non-@code{nil} if it
1100 did get some output, or @code{nil} if the timeout expired before output
1106 @section Sentinels: Detecting Process Status Changes
1107 @cindex process sentinel
1110 A @dfn{process sentinel} is a function that is called whenever the
1111 associated process changes status for any reason, including signals
1112 (whether sent by SXEmacs or caused by the process's own actions) that
1113 terminate, stop, or continue the process. The process sentinel is also
1114 called if the process exits. The sentinel receives two arguments: the
1115 process for which the event occurred, and a string describing the type
1118 The string describing the event looks like one of the following:
1122 @code{"finished\n"}.
1125 @code{"exited abnormally with code @var{exitcode}\n"}.
1128 @code{"@var{name-of-signal}\n"}.
1131 @code{"@var{name-of-signal} (core dumped)\n"}.
1134 A sentinel runs only while SXEmacs is waiting (e.g., for terminal input,
1135 or for time to elapse, or for process output). This avoids the timing
1136 errors that could result from running them at random places in the
1137 middle of other Lisp programs. A program can wait, so that sentinels
1138 will run, by calling @code{sit-for} or @code{sleep-for}
1139 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
1140 Output}). SXEmacs is also waiting when the command loop is reading input.
1142 Quitting is normally inhibited within a sentinel---otherwise, the
1143 effect of typing @kbd{C-g} at command level or to quit a user command
1144 would be unpredictable. If you want to permit quitting inside a
1145 sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}.
1147 A sentinel that writes the output into the buffer of the process
1148 should check whether the buffer is still alive. If it tries to insert
1149 into a dead buffer, it will get an error. If the buffer is dead,
1150 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
1152 If an error happens during execution of a sentinel, it is caught
1153 automatically, so that it doesn't stop the execution of whatever
1154 programs was running when the sentinel was started. However, if
1155 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1156 off. This makes it possible to use the Lisp debugger to debug the
1157 sentinel. @xref{Debugger}.
1159 In earlier Emacs versions, every sentinel that did regexp searching or
1160 matching had to explicitly save and restore the match data.
1161 SXEmacs does this automatically; sentinels never need to do it
1162 explicitly. @xref{Match Data}.
1164 @defun set-process-sentinel process sentinel
1165 This function associates @var{sentinel} with @var{process}. If
1166 @var{sentinel} is @code{nil}, then the process will have no sentinel.
1167 The default behavior when there is no sentinel is to insert a message in
1168 the process's buffer when the process status changes.
1172 (defun msg-me (process event)
1174 (format "Process: %s had the event `%s'" process event)))
1175 (set-process-sentinel (get-process "shell") 'msg-me)
1179 (kill-process (get-process "shell"))
1180 @print{} Process: #<process shell> had the event `killed'
1181 @result{} #<process shell>
1186 @defun process-sentinel process
1187 This function returns the sentinel of @var{process}, or @code{nil} if it
1191 @defun waiting-for-user-input-p
1192 While a sentinel or filter function is running, this function returns
1193 non-@code{nil} if SXEmacs was waiting for keyboard input from the user at
1194 the time the sentinel or filter function was called, @code{nil} if it
1199 @c SXEmacs+XEmacs feature
1200 @node Process Window Size
1201 @section Process Window Size
1202 @cindex process window size
1204 @defun set-process-window-size process height width
1205 This function tells @var{process} that its logical window size is
1206 @var{height} by @var{width} characters. This is principally useful
1211 @node Transaction Queues
1212 @section Transaction Queues
1213 @cindex transaction queue
1215 You can use a @dfn{transaction queue} for more convenient communication
1216 with subprocesses using transactions. First use @code{tq-create} to
1217 create a transaction queue communicating with a specified process. Then
1218 you can call @code{tq-enqueue} to send a transaction.
1220 @defun tq-create process
1221 This function creates and returns a transaction queue communicating with
1222 @var{process}. The argument @var{process} should be a subprocess
1223 capable of sending and receiving streams of bytes. It may be a child
1224 process, or it may be a TCP connection to a server, possibly on another
1228 @defun tq-enqueue queue question regexp closure fn
1229 This function sends a transaction to queue @var{queue}. Specifying the
1230 queue has the effect of specifying the subprocess to talk to.
1232 The argument @var{question} is the outgoing message that starts the
1233 transaction. The argument @var{fn} is the function to call when the
1234 corresponding answer comes back; it is called with two arguments:
1235 @var{closure}, and the answer received.
1237 The argument @var{regexp} is a regular expression that should match the
1238 entire answer, but nothing less; that's how @code{tq-enqueue} determines
1239 where the answer ends.
1241 The return value of @code{tq-enqueue} itself is not meaningful.
1244 @defun tq-close queue
1245 Shut down transaction queue @var{queue}, waiting for all pending transactions
1246 to complete, and then terminate the connection or child process.
1249 Transaction queues are implemented by means of a filter function.
1250 @xref{Filter Functions}.
1254 @section Network Connections
1255 @cindex network connection
1258 SXEmacs Lisp programs can open TCP network connections to other processes
1259 on the same machine or other machines. A network connection is handled by
1260 Lisp much like a subprocess, and is represented by a process object.
1262 However, the process you are communicating with is not a child of the
1263 SXEmacs process, so you can't kill it or send it signals. All you can do
1264 is send and receive data. @code{delete-process} closes the connection,
1265 but does not kill the process at the other end; that process must decide
1266 what to do about closure of the connection.
1268 You can distinguish process objects representing network connections
1269 from those representing subprocesses with the @code{process-status}
1270 function. It always returns either @code{open} or @code{closed} for a
1271 network connection, and it never returns either of those values for a
1272 real subprocess. @xref{Process Information}.
1274 @defun open-network-stream name buffer-or-name host service &optional protocol
1275 This function opens a TCP connection for a service to a host. It
1276 returns a process object to represent the connection.
1279 Input and output work as for other process objects.
1280 @code{delete-process} closes the connection.
1282 The @var{name} argument specifies the name for the process object. It
1283 is modified as necessary to make it unique.
1285 The @var{buffer-or-name} argument is the buffer to associate with the
1286 connection. It can be a buffer or the name of one. Output from the
1287 connection is inserted in the buffer, unless you specify a filter
1288 function to handle the output. If @var{buffer-or-name} is @code{nil},
1289 it means that the connection is not associated with any buffer.
1291 The arguments @var{host} and @var{service} specify where to connect to;
1292 @var{host} is the host name or IP address (a string), and @var{service}
1293 is the name of a defined network service (a string) or a port number (an
1296 Optional fifth arg @var{protocol} is the network protocol to use.
1297 Currently only @code{tcp} (Transmission Control Protocol) and @code{udp}
1298 (User Datagram Protocol) are supported. When omitted, @code{tcp} is assumed.
1300 Output via @code{process-send-string} and input via buffer or filter
1301 (see @code{set-process-filter}) are stream-oriented. That means
1302 UDP datagrams are not guaranteed to be sent and received in
1303 discrete packets. (But small datagrams around 500 bytes that are not
1304 truncated by @code{process-send-string} are usually fine.) Note further
1305 that the UDP protocol does not guard against lost packets.
1308 @defun open-network-server-stream name buffer-or-name host service &optional protocol acceptor filter sentinel
1309 This function establishes listening for TCP connections for a service
1310 to the local host. It returns a process object to represent the listening
1313 When a new connection request arrives, it is automatically
1314 accepted. A network-stream process is automatically created for that
1315 connection. If needed a new buffer is also created. If given the
1316 acceptor function is called. If defined filter and sentinel are set
1317 for the new connection process .
1319 Input and output work as for other process objects.
1320 @code{delete-process} closes the connection.
1323 The @var{name} argument is name for process. It is modified if
1324 necessary to make it unique. This name is taken as the basis for the
1325 name of the accepted connection's processes.
1327 The @var{buffer-or-name} is the buffer to associate with the process.
1328 Listening Process output goes at end of that buffer, unless you
1329 specify an output stream or filter function to handle the output. No
1330 real process output of listening process is expected. However the
1331 name of this buffer will be used as a base for generating a new
1332 buffer name for the accepted connections.
1334 If @var{buffer-or-name} is @code{nil}, this process is not
1335 associated with any buffer. In this case a filter should be specified
1336 otherwise there will be no way to retrieve the process output.
1338 When @var{buffer-or-name} is @code{auto} a buffer is automatically
1339 created for the accepted connection.
1341 The argument @var{host} is the name of the IP to bind to, or its IP
1342 address, If it is @code{nil} or @code{ip_any} will bind to all
1343 addresses on the machine. When @var{host} is @code{localhost}, the
1344 listening connection will listen to connections from the local
1347 The @var{service} argument is name of the service desired, or an integer
1348 specifying a port number to listen for connections.
1350 The optional @var{protocol} argument is a network protocol. Currently
1351 @code{tcp} (Transmission Control Protocol) and @code{udp} (User Datagram
1352 Protocol) are supported. When omitted, @code{tcp} is assumed.
1354 The argument @var{acceptor} is a function which will be called upon
1355 connection acceptance with two the accepted connection process. This
1356 can be used to exchange or accept credentials, establish an SSL layer,
1359 The @var{acceptor} takes a single argument: the network
1360 stream itself. In the function @var{acceptor} you can use
1361 @code{network-process-listener} to get the original listen process,
1362 and @code{process-buffer} to retrieve the associated buffers. If
1363 sentinels and/or filters are set in the @var{acceptor} they will
1364 override the @var{filter} and @var{sentinel} args to this function.
1366 When the argument @var{filter} is specified the function will be
1367 set as filter for the accepted connections automatically. See
1368 @code{set-process-filter} for more details.
1370 The optional @var{sentinel} is a function which will be set as sentinel
1371 the accepted connections automatically. see @code{set-process-sentinel}
1374 Output via @code{process-send-string} and input via buffer or filter
1375 (see @code{set-process-filter}) are stream-oriented. That means
1376 UDP datagrams are not guaranteed to be sent and received in
1377 discrete packets. (But small datagrams around 500 bytes that are not
1378 truncated by @code{process-send-string} are usually fine.) Note further
1379 that the UDP protocol does not guard against lost packets.
1383 @defun network-process-listener process
1384 This function returns the process that listened and accepted the given
1385 network process. Returns @code{nil} if process is closed or was not accepted
1386 through a network server stream.
1388 The argument @var{process} should be a network-stream process accepted
1389 through a network server stream.