Mercurial > emacs
diff lispref/processes.texi @ 6558:fa8ff07eaafc
Initial revision
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Mon, 28 Mar 1994 20:21:44 +0000 |
parents | |
children | 9a9e88e65617 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/processes.texi Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,1139 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/processes +@node Processes, System Interface, Abbrevs, Top +@chapter Processes +@cindex child process +@cindex parent process +@cindex subprocess +@cindex process + + In the terminology of operating systems, a @dfn{process} is a space in +which a program can execute. Emacs runs in a process. Emacs Lisp +programs can invoke other programs in processes of their own. These are +called @dfn{subprocesses} or @dfn{child processes} of the Emacs process, +which is their @dfn{parent process}. + + A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous}, +depending on how it is created. When you create a synchronous +subprocess, the Lisp program waits for the subprocess to terminate +before continuing execution. When you create an asynchronous +subprocess, it can run in parallel with the Lisp program. This kind of +subprocess is represented within Emacs by a Lisp object which is also +called a ``process''. Lisp programs can use this object to communicate +with the subprocess or to control it. For example, you can send +signals, obtain status information, receive output from the process, or +send input to it. + +@defun processp object +This function returns @code{t} if @var{object} is a process, +@code{nil} otherwise. +@end defun + +@menu +* Subprocess Creation:: Functions that start subprocesses. +* Synchronous Processes:: Details of using synchronous subprocesses. +* Asynchronous Processes:: Starting up an asynchronous subprocess. +* Deleting Processes:: Eliminating an asynchronous subprocess. +* Process Information:: Accessing run-status and other attributes. +* Input to Processes:: Sending input to an asynchronous subprocess. +* Signals to Processes:: Stopping, continuing or interrupting + an asynchronous subprocess. +* Output from Processes:: Collecting output from an asynchronous subprocess. +* Sentinels:: Sentinels run when process run-status changes. +* Transaction Queues:: Transaction-based communication with subprocesses. +* TCP:: Opening network connections. +@end menu + +@node Subprocess Creation +@section Functions that Create Subprocesses + + There are three functions that create a new subprocess in which to run +a program. One of them, @code{start-process}, creates an asynchronous +process and returns a process object (@pxref{Asynchronous Processes}). +The other two, @code{call-process} and @code{call-process-region}, +create a synchronous process and do not return a process object +(@pxref{Synchronous Processes}). + + Synchronous and asynchronous processes are explained in following +sections. Since the three functions are all called in a similar +fashion, their common arguments are described here. + +@cindex execute program +@cindex @code{PATH} environment variable +@cindex @code{HOME} environment variable + In all cases, the function's @var{program} argument specifies the +program to be run. An error is signaled if the file is not found or +cannot be executed. If the file name is relative, the variable +@code{exec-path} contains a list of directories to search. Emacs +initializes @code{exec-path} when it starts up, based on the value of +the environment variable @code{PATH}. The standard file name +constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usual +in @code{exec-path}, but environment variable substitutions +(@samp{$HOME}, etc.) are not recognized; use +@code{substitute-in-file-name} to perform them (@pxref{File Name +Expansion}). + + Each of the subprocess-creating functions has a @var{buffer-or-name} +argument which specifies where the standard output from the program will +go. If @var{buffer-or-name} is @code{nil}, that says to discard the +output unless a filter function handles it. (@xref{Filter Functions}, +and @ref{Streams}.) Normally, you should avoid having multiple +processes send output to the same buffer because their output would be +intermixed randomly. + +@cindex program arguments + All three of the subprocess-creating functions have a @code{&rest} +argument, @var{args}. The @var{args} must all be strings, and they are +supplied to @var{program} as separate command line arguments. Wildcard +characters and other shell constructs are not allowed in these strings, +since they are passed directly to the specified program. + + @strong{Please note:} the argument @var{program} contains only the +name of the program; it may not contain any command-line arguments. You +must use @var{args} to provide those. + + The subprocess gets its current directory from the value of +@code{default-directory} (@pxref{File Name Expansion}). + +@cindex environment variables, subprocesses + The subprocess inherits its environment from Emacs; but you can +specify overrides for it with @code{process-environment}. @xref{System +Environment}. + +@defvar exec-directory +@pindex wakeup +The value of this variable is the name of a directory (a string) that +contains programs that come with GNU Emacs, that are intended for Emacs +to invoke. The program @code{wakeup} is an example of such a program; +the @code{display-time} command uses it to get a reminder once per +minute. +@end defvar + +@defopt exec-path +The value of this variable is a list of directories to search for +programs to run in subprocesses. Each element is either the name of a +directory (i.e., a string), or @code{nil}, which stands for the default +directory (which is the value of @code{default-directory}). +@cindex program directories + +The value of @code{exec-path} is used by @code{call-process} and +@code{start-process} when the @var{program} argument is not an absolute +file name. +@end defopt + +@node Synchronous Processes +@section Creating a Synchronous Process +@cindex synchronous subprocess + + After a @dfn{synchronous process} is created, Emacs waits for the +process to terminate before continuing. Starting Dired is an example of +this: it runs @code{ls} in a synchronous process, then modifies the +output slightly. Because the process is synchronous, the entire +directory listing arrives in the buffer before Emacs tries to do +anything with it. + + While Emacs waits for the synchronous subprocess to terminate, the +user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill +the subprocess with a @code{SIGINT} signal; but it waits until the +subprocess actually terminates before quitting. If during that time the +user types another @kbd{C-g}, that kills the subprocess instantly with +@code{SIGKILL} and quits immediately. @xref{Quitting}. + + The synchronous subprocess functions returned @code{nil} in version +18. In version 19, they return an indication of how the process +terminated. + +@defun call-process program &optional infile buffer-or-name display &rest args +This function calls @var{program} in a separate process and waits for +it to finish. + +The standard input for the process comes from file @var{infile} if +@var{infile} is not @code{nil} and from @file{/dev/null} otherwise. The +process output gets inserted in buffer @var{buffer-or-name} before point, +if that argument names a buffer. If @var{buffer-or-name} is @code{t}, +output is sent to the current buffer; if @var{buffer-or-name} is +@code{nil}, output is discarded. + +If @var{buffer-or-name} is the integer 0, @code{call-process} returns +@code{nil} immediately and discards any output. In this case, the +process is not truly synchronous, since it can run in parallel with +Emacs; but you can think of it as synchronous in that Emacs is +essentially finished with the subprocess as soon as this function +returns. + +If @var{display} is non-@code{nil}, then @code{call-process} redisplays +the buffer as output is inserted. Otherwise the function does no +redisplay, and the results become visible on the screen only when Emacs +redisplays that buffer in the normal course of events. + +The remaining arguments, @var{args}, are strings that specify command +line arguments for the program. + +The value returned by @code{call-process} (unless you told it not to +wait) indicates the reason for process termination. A number gives the +exit status of the subprocess; 0 means success, and any other value +means failure. If the process terminated with a signal, +@code{call-process} returns a string describing the signal. + +In the examples below, the buffer @samp{foo} is current. + +@smallexample +@group +(call-process "pwd" nil t) + @result{} nil + +---------- Buffer: foo ---------- +/usr/user/lewis/manual +---------- Buffer: foo ---------- +@end group + +@group +(call-process "grep" nil "bar" nil "lewis" "/etc/passwd") + @result{} nil + +---------- Buffer: bar ---------- +lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh + +---------- Buffer: bar ---------- +@end group +@end smallexample + +The @code{insert-directory} function contains a good example of the use +of @code{call-process}: + +@smallexample +@group +(call-process insert-directory-program nil t nil switches + (if full-directory-p + (concat (file-name-as-directory file) ".") + file)) +@end group +@end smallexample +@end defun + +@defun call-process-region start end program &optional delete buffer-or-name display &rest args +This function sends the text between @var{start} to @var{end} as +standard input to a process running @var{program}. It deletes the text +sent if @var{delete} is non-@code{nil}; this is useful when @var{buffer} +is @code{t}, to insert the output in the current buffer. + +The arguments @var{buffer-or-name} and @var{display} control what to do +with the output from the subprocess, and whether to update the display +as it comes in. For details, see the description of +@code{call-process}, above. If @var{buffer-or-name} is the integer 0, +@code{call-process-region} discards the output and returns @code{nil} +immediately, without waiting for the subprocess to finish. + +The remaining arguments, @var{args}, are strings that specify command +line arguments for the program. + +The return value of @code{call-process-region} is just like that of +@code{call-process}: @code{nil} if you told it to return without +waiting; otherwise, a number or string which indicates how the +subprocess terminated. + +In the following example, we use @code{call-process-region} to run the +@code{cat} utility, with standard input being the first five characters +in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its +standard input into its standard output. Since the argument +@var{buffer-or-name} is @code{t}, this output is inserted in the current +buffer. + +@smallexample +@group +---------- Buffer: foo ---------- +input@point{} +---------- Buffer: foo ---------- +@end group + +@group +(call-process-region 1 6 "cat" nil t) + @result{} nil + +---------- Buffer: foo ---------- +inputinput@point{} +---------- Buffer: foo ---------- +@end group +@end smallexample + + The @code{shell-command-on-region} command uses +@code{call-process-region} like this: + +@smallexample +@group +(call-process-region + start end + shell-file-name ; @r{Name of program.} + nil ; @r{Do not delete region.} + buffer ; @r{Send output to @code{buffer}.} + nil ; @r{No redisplay during output.} + "-c" command) ; @r{Arguments for the shell.} +@end group +@end smallexample +@end defun + +@node Asynchronous Processes +@section Creating an Asynchronous Process +@cindex asynchronous subprocess + + After an @dfn{asynchronous process} is created, Emacs and the Lisp +program both continue running immediately. The process may thereafter +run in parallel with Emacs, and the two may communicate with each other +using the functions described in following sections. Here we describe +how to create an asynchronous process with @code{start-process}. + +@defun start-process name buffer-or-name program &rest args +This function creates a new asynchronous subprocess and starts the +program @var{program} running in it. It returns a process object that +stands for the new subprocess in Lisp. The argument @var{name} +specifies the name for the process object; if a process with this name +already exists, then @var{name} is modified (by adding @samp{<1>}, etc.) +to be unique. The buffer @var{buffer-or-name} is the buffer to +associate with the process. + +The remaining arguments, @var{args}, are strings that specify command +line arguments for the program. + +In the example below, the first process is started and runs (rather, +sleeps) for 100 seconds. Meanwhile, the second process is started, and +given the name @samp{my-process<1>} for the sake of uniqueness. It +inserts the directory listing at the end of the buffer @samp{foo}, +before the first process finishes. Then it finishes, and a message to +that effect is inserted in the buffer. Much later, the first process +finishes, and another message is inserted in the buffer for it. + +@smallexample +@group +(start-process "my-process" "foo" "sleep" "100") + @result{} #<process my-process> +@end group + +@group +(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") + @result{} #<process my-process<1>> + +---------- Buffer: foo ---------- +total 2 +lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs +-rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon + +Process my-process<1> finished + +Process my-process finished +---------- Buffer: foo ---------- +@end group +@end smallexample +@end defun + +@defun start-process-shell-command name buffer-or-name command &rest command-args +This function is like @code{start-process} except that it uses a shell +to execute the specified command. The argument @var{command} is a shell +command name, and @var{command-args} are the arguments for the shell +command. +@end defun + +@defvar process-connection-type +@cindex pipes +@cindex @sc{pty}s +This variable controls the type of device used to communicate with +asynchronous subprocesses. If it is @code{nil}, then pipes are used. +If it is @code{t}, then @sc{pty}s are used (or pipes if @sc{pty}s are +not supported). + +@sc{pty}s are usually preferable for processes visible to the user, as +in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z}, +etc.) to work between the process and its children whereas pipes do not. +For subprocesses used for internal purposes by programs, it is often +better to use a pipe, because they are more efficient. In addition, the +total number of @sc{pty}s is limited on many systems and it is good not +to waste them. + +The value @code{process-connection-type} is used when +@code{start-process} is called. So you can specify how to communicate +with one subprocess by binding the variable around the call to +@code{start-process}. + +@smallexample +@group +(let ((process-connection-type nil)) ; @r{Use a pipe.} + (start-process @dots{})) +@end group +@end smallexample +@end defvar + +@node Deleting Processes +@section Deleting Processes +@cindex deleting processes + + @dfn{Deleting a process} disconnects Emacs immediately from the +subprocess, and removes it from the list of active processes. It sends +a signal to the subprocess to make the subprocess terminate, but this is +not guaranteed to happen immediately. The process object itself +continues to exist as long as other Lisp objects point to it. + + You can delete a process explicitly at any time. Processes are +deleted automatically after they terminate, but not necessarily right +away. If you delete a terminated process explicitly before it is +deleted automatically, no harm results. + +@defvar delete-exited-processes +This variable controls automatic deletion of processes that have +terminated (due to calling @code{exit} or to a signal). If it is +@code{nil}, then they continue to exist until the user runs +@code{list-processes}. Otherwise, they are deleted immediately after +they exit. +@end defvar + +@defun delete-process name +This function deletes the process associated with @var{name}, killing it +with a @code{SIGHUP} signal. The argument @var{name} may be a process, +the name of a process, a buffer, or the name of a buffer. + +@smallexample +@group +(delete-process "*shell*") + @result{} nil +@end group +@end smallexample +@end defun + +@defun process-kill-without-query process +This function declares that Emacs need not query the user if +@var{process} is still running when Emacs is exited. The process will +be deleted silently. The value is @code{t}. + +@smallexample +@group +(process-kill-without-query (get-process "shell")) + @result{} t +@end group +@end smallexample +@end defun + +@node Process Information +@section Process Information + + Several functions return information about processes. +@code{list-processes} is provided for interactive use. + +@deffn Command list-processes +This command displays a listing of all living processes. In addition, +it finally deletes any process whose status was @samp{Exited} or +@samp{Signaled}. It returns @code{nil}. +@end deffn + +@defun process-list +This function returns a list of all processes that have not been deleted. + +@smallexample +@group +(process-list) + @result{} (#<process display-time> #<process shell>) +@end group +@end smallexample +@end defun + +@defun get-process name +This function returns the process named @var{name}, or @code{nil} if +there is none. An error is signaled if @var{name} is not a string. + +@smallexample +@group +(get-process "shell") + @result{} #<process shell> +@end group +@end smallexample +@end defun + +@defun process-command process +This function returns the command that was executed to start +@var{process}. This is a list of strings, the first string being the +program executed and the rest of the strings being the arguments that +were given to the program. + +@smallexample +@group +(process-command (get-process "shell")) + @result{} ("/bin/csh" "-i") +@end group +@end smallexample +@end defun + +@defun process-id process +This function returns the @sc{pid} of @var{process}. This is an +integer which distinguishes the process @var{process} from all other +processes running on the same computer at the current time. The +@sc{pid} of a process is chosen by the operating system kernel when the +process is started and remains constant as long as the process exists. +@end defun + +@defun process-name process +This function returns the name of @var{process}. +@end defun + +@defun process-status process-name +This function returns the status of @var{process-name} as a symbol. +The argument @var{process-name} must be a process, a buffer, a +process name (string) or a buffer name (string). + +The possible values for an actual subprocess are: + +@table @code +@item run +for a process that is running. +@item stop +for a process that is stopped but continuable. +@item exit +for a process that has exited. +@item signal +for a process that has received a fatal signal. +@item open +for a network connection that is open. +@item closed +for a network connection that is closed. Once a connection +is closed, you cannot reopen it, though you might be able to open +a new connection to the same place. +@item nil +if @var{process-name} is not the name of an existing process. +@end table + +@smallexample +@group +(process-status "shell") + @result{} run +@end group +@group +(process-status (get-buffer "*shell*")) + @result{} run +@end group +@group +x + @result{} #<process xx<1>> +(process-status x) + @result{} exit +@end group +@end smallexample + +For a network connection, @code{process-status} returns one of the symbols +@code{open} or @code{closed}. The latter means that the other side +closed the connection, or Emacs did @code{delete-process}. + +In earlier Emacs versions (prior to version 19), the status of a network +connection was @code{run} if open, and @code{exit} if closed. +@end defun + +@defun process-exit-status process +This function returns the exit status of @var{process} or the signal +number that killed it. (Use the result of @code{process-status} to +determine which of those it is.) If @var{process} has not yet +terminated, the value is 0. +@end defun + +@node Input to Processes +@section Sending Input to Processes +@cindex process input + + Asynchronous subprocesses receive input when it is sent to them by +Emacs, which is done with the functions in this section. You must +specify the process to send input to, and the input data to send. The +data appears on the ``standard input'' of the subprocess. + + Some operating systems have limited space for buffered input in a +@sc{pty}. On these systems, Emacs sends an @sc{eof} periodically amidst +the other characters, to force them through. For most programs, +these @sc{eof}s do no harm. + +@defun process-send-string process-name string +This function sends @var{process-name} the contents of @var{string} as +standard input. The argument @var{process-name} must be a process or +the name of a process. If it is @code{nil}, the current buffer's +process is used. + + The function returns @code{nil}. + +@smallexample +@group +(process-send-string "shell<1>" "ls\n") + @result{} nil +@end group + + +@group +---------- Buffer: *shell* ---------- +... +introduction.texi syntax-tables.texi~ +introduction.texi~ text.texi +introduction.txt text.texi~ +... +---------- Buffer: *shell* ---------- +@end group +@end smallexample +@end defun + +@deffn Command process-send-region process-name start end +This function sends the text in the region defined by @var{start} and +@var{end} as standard input to @var{process-name}, which is a process or +a process name. (If it is @code{nil}, the current buffer's process is +used.) + +An error is signaled unless both @var{start} and @var{end} are +integers or markers that indicate positions in the current buffer. (It +is unimportant which number is larger.) +@end deffn + +@defun process-send-eof &optional process-name + This function makes @var{process-name} see an end-of-file in its +input. The @sc{eof} comes after any text already sent to it. + + If @var{process-name} is not supplied, or if it is @code{nil}, then +this function sends the @sc{eof} to the current buffer's process. An +error is signaled if the current buffer has no process. + + The function returns @var{process-name}. + +@smallexample +@group +(process-send-eof "shell") + @result{} "shell" +@end group +@end smallexample +@end defun + +@node Signals to Processes +@section Sending Signals to Processes +@cindex process signals +@cindex sending signals +@cindex signals + + @dfn{Sending a signal} to a subprocess is a way of interrupting its +activities. There are several different signals, each with its own +meaning. The set of signals and their names is defined by the operating +system. For example, the signal @code{SIGINT} means that the user has +typed @kbd{C-c}, or that some analogous thing has happened. + + Each signal has a standard effect on the subprocess. Most signals +kill the subprocess, but some stop or resume execution instead. Most +signals can optionally be handled by programs; if the program handles +the signal, then we can say nothing in general about its effects. + + You can send signals explicitly by calling the functions in this +section. Emacs also sends signals automatically at certain times: +killing a buffer sends a @code{SIGHUP} signal to all its associated +processes; killing Emacs sends a @code{SIGHUP} signal to all remaining +processes. (@code{SIGHUP} is a signal that usually indicates that the +user hung up the phone.) + + Each of the signal-sending functions takes two optional arguments: +@var{process-name} and @var{current-group}. + + The argument @var{process-name} must be either a process, the name of +one, or @code{nil}. If it is @code{nil}, the process defaults to the +process associated with the current buffer. An error is signaled if +@var{process-name} does not identify a process. + + The argument @var{current-group} is a flag that makes a difference +when you are running a job-control shell as an Emacs subprocess. If it +is non-@code{nil}, then the signal is sent to the current process-group +of the terminal which Emacs uses to communicate with the subprocess. If +the process is a job-control shell, this means the shell's current +subjob. If it is @code{nil}, the signal is sent to the process group of +the immediate subprocess of Emacs. If the subprocess is a job-control +shell, this is the shell itself. + + The flag @var{current-group} has no effect when a pipe is used to +communicate with the subprocess, because the operating system does not +support the distinction in the case of pipes. For the same reason, +job-control shells won't work when a pipe is used. See +@code{process-connection-type} in @ref{Asynchronous Processes}. + +@defun interrupt-process &optional process-name current-group +This function interrupts the process @var{process-name} by sending the +signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt +character'' (normally @kbd{C-c} on some systems, and @code{DEL} on +others) sends this signal. When the argument @var{current-group} is +non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' +on the terminal by which Emacs talks to the subprocess. +@end defun + +@defun kill-process &optional process-name current-group +This function kills the process @var{process-name} by sending the +signal @code{SIGKILL}. This signal kills the subprocess immediately, +and cannot be handled by the subprocess. +@end defun + +@defun quit-process &optional process-name current-group +This function sends the signal @code{SIGQUIT} to the process +@var{process-name}. This signal is the one sent by the ``quit +character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside +Emacs. +@end defun + +@defun stop-process &optional process-name current-group +This function stops the process @var{process-name} by sending the +signal @code{SIGTSTP}. Use @code{continue-process} to resume its +execution. + +On systems with job control, the ``stop character'' (usually @kbd{C-z}) +sends this signal (outside of Emacs). When @var{current-group} is +non-@code{nil}, you can think of this function as ``typing @kbd{C-z}'' +on the terminal Emacs uses to communicate with the subprocess. +@end defun + +@defun continue-process &optional process-name current-group +This function resumes execution of the process @var{process} by sending +it the signal @code{SIGCONT}. This presumes that @var{process-name} was +stopped previously. +@end defun + +@c Emacs 19 feature +@defun signal-process pid signal +This function sends a signal to process @var{pid}, which need not be +a child of Emacs. The argument @var{signal} specifies which signal +to send; it should be an integer. +@end defun + +@node Output from Processes +@section Receiving Output from Processes +@cindex process output +@cindex output from processes + + There are two ways to receive the output that a subprocess writes to +its standard output stream. The output can be inserted in a buffer, +which is called the associated buffer of the process, or a function +called the @dfn{filter function} can be called to act on the output. + +@menu +* Process Buffers:: If no filter, output is put in a buffer. +* Filter Functions:: Filter functions accept output from the process. +* Accepting Output:: Explicitly permitting subprocess output. + Waiting for subprocess output. +@end menu + +@node Process Buffers +@subsection Process Buffers + + A process can (and usually does) have an @dfn{associated buffer}, +which is an ordinary Emacs buffer that is used for two purposes: storing +the output from the process, and deciding when to kill the process. You +can also use the buffer to identify a process to operate on, since in +normal practice only one process is associated with any given buffer. +Many applications of processes also use the buffer for editing input to +be sent to the process, but this is not built into Emacs Lisp. + + Unless the process has a filter function (@pxref{Filter Functions}), +its output is inserted in the associated buffer. The position to insert +the output is determined by the @code{process-mark} (@pxref{Process +Information}), which is then updated to point to the end of the text +just inserted. Usually, but not always, the @code{process-mark} is at +the end of the buffer. If the process has no buffer and no filter +function, its output is discarded. + +@defun process-buffer process +This function returns the associated buffer of the process +@var{process}. + +@smallexample +@group +(process-buffer (get-process "shell")) + @result{} #<buffer *shell*> +@end group +@end smallexample +@end defun + +@defun process-mark process +This function returns the process marker for @var{process}, which is the +marker that says where to insert output from the process. + +If @var{process} does not have a buffer, @code{process-mark} returns a +marker that points nowhere. + +Insertion of process output in a buffer uses this marker to decide where +to insert, and updates it to point after the inserted text. That is why +successive batches of output are inserted consecutively. + +Filter functions normally should use this marker in the same fashion +as is done by direct insertion of output in the buffer. A good +example of a filter function that uses @code{process-mark} is found at +the end of the following section. + +When the user is expected to enter input in the process buffer for +transmission to the process, the process marker is useful for +distinguishing the new input from previous output. +@end defun + +@defun set-process-buffer process buffer +This function sets the buffer associated with @var{process} to +@var{buffer}. If @var{buffer} is @code{nil}, the process becomes +associated with no buffer. +@end defun + +@defun get-buffer-process buffer-or-name +This function returns the process associated with @var{buffer-or-name}. +If there are several processes associated with it, then one is chosen. +(Presently, the one chosen is the one most recently created.) It is +usually a bad idea to have more than one process associated with the +same buffer. + +@smallexample +@group +(get-buffer-process "*shell*") + @result{} #<process shell> +@end group +@end smallexample + +Killing the process's buffer deletes the process, which kills the +subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). +@end defun + +@node Filter Functions +@subsection Process Filter Functions +@cindex filter function +@cindex process filter + + A process @dfn{filter function} is a function that receives the +standard output from the associated process. If a process has a filter, +then @emph{all} output from that process, that would otherwise have been +in a buffer, is passed to the filter. The process buffer is used +directly for output from the process only when there is no filter. + + A filter function must accept two arguments: the associated process and +a string, which is the output. The function is then free to do whatever it +chooses with the output. + + A filter function runs only while Emacs is waiting (e.g., for terminal +input, or for time to elapse, or for process output). This avoids the +timing errors that could result from running filters at random places in +the middle of other Lisp programs. You may explicitly cause Emacs to +wait, so that filter functions will run, by calling @code{sit-for}, +@code{sleep-for} or @code{accept-process-output} (@pxref{Accepting +Output}). Emacs is also waiting when the command loop is reading input. + + Quitting is normally inhibited within a filter function---otherwise, +the effect of typing @kbd{C-g} at command level or to quit a user +command would be unpredictable. If you want to permit quitting inside a +filter function, bind @code{inhibit-quit} to @code{nil}. +@xref{Quitting}. + + Many filter functions sometimes or always insert the text in the +process's buffer, mimicking the actions of Emacs when there is no +filter. Such filter functions need to use @code{set-buffer} in order to +be sure to insert in that buffer. To avoid setting the current buffer +semipermanently, these filter functions must use @code{unwind-protect} +to make sure to restore the previous current buffer. They should also +update the process marker, and in some cases update the value of point. +Here is how to do these things: + +@smallexample +@group +(defun ordinary-insertion-filter (proc string) + (let ((old-buffer (current-buffer))) + (unwind-protect + (let (moving) + (set-buffer (process-buffer proc)) + (setq moving (= (point) (process-mark proc))) +@end group +@group + (save-excursion + ;; @r{Insert the text, moving the process-marker.} + (goto-char (process-mark proc)) + (insert string) + (set-marker (process-mark proc) (point))) + (if moving (goto-char (process-mark proc)))) + (set-buffer old-buffer)))) +@end group +@end smallexample + +@noindent +The reason to use an explicit @code{unwind-protect} rather than letting +@code{save-excursion} restore the current buffer is so as to preserve +the change in point made by @code{goto-char}. + + To make the filter force the process buffer to be visible whenever new +text arrives, insert the following line just before the +@code{unwind-protect}: + +@smallexample +(display-buffer (process-buffer proc)) +@end smallexample + + To force point to move to the end of the new output no matter where +it was previously, eliminate the variable @code{moving} and call +@code{goto-char} unconditionally. + + All filter functions that do regexp searching or matching should save +and restore the match data. Otherwise, a filter function that runs +during a call to @code{sit-for} might clobber the match data of the +program that called @code{sit-for}. @xref{Match Data}. + + A filter function that writes the output into the buffer of the +process should check whether the process is still alive. If it tries to +insert into a dead buffer, it will get an error. If the buffer is dead, +@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. + + The output to the function may come in chunks of any size. A program +that produces the same output twice in a row may send it as one batch +of 200 characters one time, and five batches of 40 characters the next. + +@defun set-process-filter process filter +This function gives @var{process} the filter function @var{filter}. If +@var{filter} is @code{nil}, it gives the process no filter. +@end defun + +@defun process-filter process +This function returns the filter function of @var{process}, or @code{nil} +if it has none. +@end defun + + Here is an example of use of a filter function: + +@smallexample +@group +(defun keep-output (process output) + (setq kept (cons output kept))) + @result{} keep-output +@end group +@group +(setq kept nil) + @result{} nil +@end group +@group +(set-process-filter (get-process "shell") 'keep-output) + @result{} keep-output +@end group +@group +(process-send-string "shell" "ls ~/other\n") + @result{} nil +kept + @result{} ("lewis@@slug[8] % " +@end group +@group +"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ +address.txt backup.psf kolstad.psf +backup.bib~ david.mss resume-Dec-86.mss~ +backup.err david.psf resume-Dec.psf +backup.mss dland syllabus.mss +" +"#backups.mss# backup.mss~ kolstad.mss +") +@end group +@end smallexample + +@ignore @c The code in this example doesn't show the right way to do things. +Here is another, more realistic example, which demonstrates how to use +the process mark to do insertion in the same fashion as is done when +there is no filter function: + +@smallexample +@group +;; @r{Insert input in the buffer specified by @code{my-shell-buffer}} +;; @r{and make sure that buffer is shown in some window.} +(defun my-process-filter (proc str) + (let ((cur (selected-window)) + (pop-up-windows t)) + (pop-to-buffer my-shell-buffer) +@end group +@group + (goto-char (point-max)) + (insert str) + (set-marker (process-mark proc) (point-max)) + (select-window cur))) +@end group +@end smallexample +@end ignore + +@node Accepting Output +@subsection Accepting Output from Processes + + Output from asynchronous subprocesses normally arrives only while +Emacs is waiting for some sort of external event, such as elapsed time +or terminal input. Occasionally it is useful in a Lisp program to +explicitly permit output to arrive at a specific point, or even to wait +until output arrives from a process. + +@defun accept-process-output &optional process seconds millisec +This function allows Emacs to read pending output from processes. The +output is inserted in the associated buffers or given to their filter +functions. If @var{process} is non-@code{nil} then this function does +not return until some output has been received from @var{process}. + +@c Emacs 19 feature +The arguments @var{seconds} and @var{millisec} let you specify timeout +periods. The former specifies a period measured in seconds and the +latter specifies one measured in milliseconds. The two time periods +thus specified are added together, and @code{accept-process-output} +returns after that much time whether or not there has been any +subprocess output. + +Not all operating systems support waiting periods other than multiples +of a second; on those that do not, you get an error if you specify +nonzero @var{millisec}. + +The function @code{accept-process-output} returns non-@code{nil} if it +did get some output, or @code{nil} if the timeout expired before output +arrived. +@end defun + +@node Sentinels +@section Sentinels: Detecting Process Status Changes +@cindex process sentinel +@cindex sentinel + + A @dfn{process sentinel} is a function that is called whenever the +associated process changes status for any reason, including signals +(whether sent by Emacs or caused by the process's own actions) that +terminate, stop, or continue the process. The process sentinel is also +called if the process exits. The sentinel receives two arguments: the +process for which the event occurred, and a string describing the type +of event. + + The string describing the event looks like one of the following: + +@itemize @bullet +@item +@code{"finished\n"}. + +@item +@code{"exited abnormally with code @var{exitcode}\n"}. + +@item +@code{"@var{name-of-signal}\n"}. + +@item +@code{"@var{name-of-signal} (core dumped)\n"}. +@end itemize + + A sentinel runs only while Emacs is waiting (e.g., for terminal input, +or for time to elapse, or for process output). This avoids the timing +errors that could result from running them at random places in the +middle of other Lisp programs. A program can wait, so that sentinels +will run, by calling @code{sit-for}, @code{sleep-for} or +@code{accept-process-output} (@pxref{Accepting Output}). Emacs is also +waiting when the command loop is reading input. + + Quitting is normally inhibited within a sentinel---otherwise, the +effect of typing @kbd{C-g} at command level or to quit a user command +would be unpredictable. If you want to permit quitting inside a +sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}. + + A sentinel that writes the output into the buffer of the process +should check whether the process is still alive. If it tries to insert +into a dead buffer, it will get an error. If the buffer is dead, +@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. + + All sentinels that do regexp searching or matching should save and +restore the match data. Otherwise, a sentinel that runs during a call +to @code{sit-for} might clobber the match data of the program that +called @code{sit-for}. @xref{Match Data}. + +@defun set-process-sentinel process sentinel +This function associates @var{sentinel} with @var{process}. If +@var{sentinel} is @code{nil}, then the process will have no sentinel. +The default behavior when there is no sentinel is to insert a message in +the process's buffer when the process status changes. + +@smallexample +@group +(defun msg-me (process event) + (princ + (format "Process: %s had the event `%s'" process event))) +(set-process-sentinel (get-process "shell") 'msg-me) + @result{} msg-me +@end group +@group +(kill-process (get-process "shell")) + @print{} Process: #<process shell> had the event `killed' + @result{} #<process shell> +@end group +@end smallexample +@end defun + +@defun process-sentinel process +This function returns the sentinel of @var{process}, or @code{nil} if it +has none. +@end defun + +@defun waiting-for-user-input-p +While a sentinel or filter function is running, this function returns +non-@code{nil} if Emacs was waiting for keyboard input from the user at +the time the sentinel or filter function was called, @code{nil} if it +was not. +@end defun + +@node Transaction Queues +@section Transaction Queues +@cindex transaction queue + +You can use a @dfn{transaction queue} for more convenient communication +with subprocesses using transactions. First use @code{tq-create} to +create a transaction queue communicating with a specified process. Then +you can call @code{tq-enqueue} to send a transaction. + +@defun tq-create process +This function creates and returns a transaction queue communicating with +@var{process}. The argument @var{process} should be a subprocess +capable of sending and receiving streams of bytes. It may be a child +process, or it may be a TCP connection to a server possibly on another +machine. +@end defun + +@defun tq-enqueue queue question regexp closure fn +This function sends a transaction to queue @var{queue}. Specifying the +queue has the effect of specifying the subprocess to talk to. + +The argument @var{question} is the outgoing message which starts the +transaction. The argument @var{fn} is the function to call when the +corresponding answer comes back; it is called with two arguments: +@var{closure}, and the answer received. + +The argument @var{regexp} is a regular expression that should match the +entire answer, but nothing less; that's how @code{tq-enqueue} determines +where the answer ends. + +The return value of @code{tq-enqueue} itself is not meaningful. +@end defun + +@defun tq-close queue +Shut down transaction queue @var{queue}, waiting for all pending transactions +to complete, and then terminate the connection or child process. +@end defun + +Transaction queues are implemented by means of a filter function. +@xref{Filter Functions}. + +@node TCP +@section TCP +@cindex TCP + + Emacs Lisp programs can open TCP connections to other processes on the +same machine or other machines. A network connection is handled by Lisp +much like a subprocess, and is represented by a process object. +However, the process you are communicating with is not a child of the +Emacs process, so you can't kill it or send it signals. All you can do +is send and receive data. @code{delete-process} closes the connection, +but does not kill the process at the other end; that process must decide +what to do about closure of the connection. + + You can distinguish process objects representing network connections +from those representing subprocesses with the @code{process-status} +function. @xref{Process Information}. + +@defun open-network-stream name buffer-or-name host service +This function opens a TCP connection for a service to a host. It +returns a process object to represent the connection. + +The @var{name} argument specifies the name for the process object. It +is modified as necessary to make it unique. + +The @var{buffer-or-name} argument is the buffer to associate with the +connection. Output from the connection is inserted in the buffer, +unless you specify a filter function to handle the output. If +@var{buffer-or-name} is @code{nil}, it means that the connection is not +associated with any buffer. + +The arguments @var{host} and @var{service} specify where to connect to; +@var{host} is the host name (a string), and @var{service} is the name of +a defined network service (a string) or a port number (an integer). +@end defun