@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 inwhich a program can execute. Emacs runs in a process. Emacs Lispprograms can invoke other programs in processes of their own. These arecalled @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 synchronoussubprocess, the Lisp program waits for the subprocess to terminatebefore continuing execution. When you create an asynchronoussubprocess, it can run in parallel with the Lisp program. This kind ofsubprocess is represented within Emacs by a Lisp object which is alsocalled a ``process''. Lisp programs can use this object to communicatewith the subprocess or to control it. For example, you can sendsignals, obtain status information, receive output from the process, orsend input to it.@defun processp objectThis 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.* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary for data sent to and from a subprocess.* 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.* Network:: 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 runa program. One of them, @code{start-process}, creates an asynchronousprocess 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 followingsections. Since the three functions are all called in a similarfashion, 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 theprogram to be run. An error is signaled if the file is not found orcannot be executed. If the file name is relative, the variable@code{exec-path} contains a list of directories to search. Emacsinitializes @code{exec-path} when it starts up, based on the value ofthe environment variable @code{PATH}. The standard file nameconstructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usualin @code{exec-path}, but environment variable substitutions(@samp{$HOME}, etc.) are not recognized; use@code{substitute-in-file-name} to perform them (@pxref{File NameExpansion}). Each of the subprocess-creating functions has a @var{buffer-or-name}argument which specifies where the standard output from the program willgo. If @var{buffer-or-name} is @code{nil}, that says to discard theoutput unless a filter function handles it. (@xref{Filter Functions},and @ref{Read and Print}.) Normally, you should avoid having multipleprocesses send output to the same buffer because their output would beintermixed 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 aresupplied to @var{program} as separate command line arguments. Wildcardcharacters 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 thename of the program; it may not contain any command-line arguments. Youmust 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 canspecify overrides for it with @code{process-environment}. @xref{SystemEnvironment}.@defvar exec-directory @pindex wakeupThe value of this variable is the name of a directory (a string) thatcontains programs that come with GNU Emacs, that are intended for Emacsto invoke. The program @code{wakeup} is an example of such a program;the @code{display-time} command uses it to get a reminder once perminute.@end defvar@defopt exec-pathThe value of this variable is a list of directories to search forprograms to run in subprocesses. Each element is either the name of adirectory (i.e., a string), or @code{nil}, which stands for the defaultdirectory (which is the value of @code{default-directory}).@cindex program directoriesThe value of @code{exec-path} is used by @code{call-process} and@code{start-process} when the @var{program} argument is not an absolutefile name.@end defopt@node Synchronous Processes@section Creating a Synchronous Process@cindex synchronous subprocess After a @dfn{synchronous process} is created, Emacs waits for theprocess to terminate before continuing. Starting Dired is an example ofthis: it runs @code{ls} in a synchronous process, then modifies theoutput slightly. Because the process is synchronous, the entiredirectory listing arrives in the buffer before Emacs tries to doanything with it. While Emacs waits for the synchronous subprocess to terminate, theuser can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to killthe subprocess with a @code{SIGINT} signal; but it waits until thesubprocess actually terminates before quitting. If during that time theuser 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 version18. In version 19, they return an indication of how the processterminated.@defun call-process program &optional infile destination display &rest argsThis function calls @var{program} in a separate process and waits forit 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 argument @var{destination} says where to put the process output.Here are the possibilities:@table @asis@item a bufferInsert the output in that buffer, before point. This includes both thestandard output stream and the standard error stream of the process.@item a stringFind or create a buffer with that name, then insertthe output in that buffer, before point.@item @code{t}Insert the output in the current buffer, before point.@item @code{nil}Discard the output.@item 0Discard the output, and return immediately without waitingfor the subprocess to finish.In this case, the process is not truly synchronous, since it can run inparallel with Emacs; but you can think of it as synchronous in thatEmacs is essentially finished with the subprocess as soon as thisfunction returns.@item (@var{real-destination} @var{error-destination})Keep the standard output stream separate from the standard error stream;deal with the ordinary output as specified by @var{real-destination},and dispose of the error output according to @var{error-destination}.The value @code{nil} means discard it, @code{t} means mix it with theordinary output, and a string specifies a file name to redirect erroroutput into.You can't directly specify a buffer to put the error output in; that istoo difficult to implement. But you can achieve this result by sendingthe error output to a temporary file and then inserting the file into abuffer.@end tableIf @var{display} is non-@code{nil}, then @code{call-process} redisplaysthe buffer as output is inserted. Otherwise the function does noredisplay, and the results become visible on the screen only when Emacsredisplays that buffer in the normal course of events.The remaining arguments, @var{args}, are strings that specify commandline arguments for the program.The value returned by @code{call-process} (unless you told it not towait) indicates the reason for process termination. A number gives theexit status of the subprocess; 0 means success, and any other valuemeans 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 smallexampleThe @code{insert-directory} function contains a good example of the useof @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 destination display &rest argsThis function sends the text between @var{start} to @var{end} asstandard input to a process running @var{program}. It deletes the textsent 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{destination} and @var{display} control what to dowith the output from the subprocess, and whether to update the displayas it comes in. For details, see the description of@code{call-process}, above. If @var{destination} 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 commandline 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 withoutwaiting; otherwise, a number or string which indicates how thesubprocess terminated.In the following example, we use @code{call-process-region} to run the@code{cat} utility, with standard input being the first five charactersin buffer @samp{foo} (the word @samp{input}). @code{cat} copies itsstandard input into its standard output. Since the argument@var{destination} is @code{t}, this output is inserted in the currentbuffer.@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 MS-DOS Subprocesses@section MS-DOS Subprocesses On MS-DOS, you must indicate whether the data going to and froma synchronous subprocess are text or binary. Text data requirestranslation between the end-of-line convention used within Emacs(a single newline character) and the convention used outside Emacs(the two-character sequence, @sc{crlf}). The variable @code{binary-process-input} applies to input sent to thesubprocess, and @code{binary-process-output} applies to output receivedfrom it. A non-@code{nil} value means the data is non-text; @code{nil}means the data is text, and calls for conversion.@defvar binary-process-inputIf this variable is @code{nil}, convert newlines to @sc{crlf} sequences inthe input to a synchronous subprocess.@end defvar@defvar binary-process-outputIf this variable is @code{nil}, convert @sc{crlf} sequences to newlines inthe output from a synchronous subprocess.@end defvar @xref{Files and MS-DOS}, for related information.@node Asynchronous Processes@section Creating an Asynchronous Process@cindex asynchronous subprocess After an @dfn{asynchronous process} is created, Emacs and the Lispprogram both continue running immediately. The process may thereafterrun in parallel with Emacs, and the two may communicate with each otherusing the functions described in following sections. Here we describehow to create an asynchronous process with @code{start-process}.@defun start-process name buffer-or-name program &rest argsThis function creates a new asynchronous subprocess and starts theprogram @var{program} running in it. It returns a process object thatstands for the new subprocess in Lisp. The argument @var{name}specifies the name for the process object; if a process with this namealready exists, then @var{name} is modified (by adding @samp{<1>}, etc.)to be unique. The buffer @var{buffer-or-name} is the buffer toassociate with the process.The remaining arguments, @var{args}, are strings that specify commandline 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, andgiven the name @samp{my-process<1>} for the sake of uniqueness. Itinserts the directory listing at the end of the buffer @samp{foo},before the first process finishes. Then it finishes, and a message tothat effect is inserted in the buffer. Much later, the first processfinishes, 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 2lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs-rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemonProcess my-process<1> finishedProcess my-process finished---------- Buffer: foo ----------@end group@end smallexample@end defun@defun start-process-shell-command name buffer-or-name command &rest command-argsThis function is like @code{start-process} except that it uses a shellto execute the specified command. The argument @var{command} is a shellcommand name, and @var{command-args} are the arguments for the shellcommand.@end defun@defvar process-connection-type@cindex pipes@cindex @sc{pty}sThis variable controls the type of device used to communicate withasynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s areused, when available. Otherwise, pipes are used.@sc{pty}s are usually preferable for processes visible to the user, asin 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 oftenbetter to use a pipe, because they are more efficient. In addition, thetotal number of @sc{pty}s is limited on many systems and it is good notto waste them.The value @code{process-connection-type} is used when@code{start-process} is called. So you can specify how to communicatewith 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 smallexampleTo determine whether a given subprocess actually got a pipe or a@sc{pty}, use the function @code{process-tty-name} (@pxref{ProcessInformation}).@end defvar@node Deleting Processes@section Deleting Processes@cindex deleting processes @dfn{Deleting a process} disconnects Emacs immediately from thesubprocess, and removes it from the list of active processes. It sendsa signal to the subprocess to make the subprocess terminate, but this isnot guaranteed to happen immediately. The process object itselfcontinues to exist as long as other Lisp objects point to it. You can delete a process explicitly at any time. Processes aredeleted automatically after they terminate, but not necessarily rightaway. If you delete a terminated process explicitly before it isdeleted automatically, no harm results.@defvar delete-exited-processesThis variable controls automatic deletion of processes that haveterminated (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 afterthey exit.@end defvar@defun delete-process nameThis function deletes the process associated with @var{name}, killing itwith 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 processThis function declares that Emacs need not query the user if@var{process} is still running when Emacs is exited. The process willbe 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-processesThis 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-listThis 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 nameThis function returns the process named @var{name}, or @code{nil} ifthere 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 processThis function returns the command that was executed to start@var{process}. This is a list of strings, the first string being theprogram executed and the rest of the strings being the arguments thatwere given to the program.@smallexample@group(process-command (get-process "shell")) @result{} ("/bin/csh" "-i")@end group@end smallexample@end defun@defun process-id processThis function returns the @sc{pid} of @var{process}. This is aninteger that distinguishes the process @var{process} from all otherprocesses running on the same computer at the current time. The@sc{pid} of a process is chosen by the operating system kernel when theprocess is started and remains constant as long as the process exists.@end defun@defun process-name processThis function returns the name of @var{process}.@end defun@defun process-status process-nameThis function returns the status of @var{process-name} as a symbol.The argument @var{process-name} must be a process, a buffer, aprocess name (string) or a buffer name (string).The possible values for an actual subprocess are:@table @code@item runfor a process that is running.@item stopfor a process that is stopped but continuable.@item exitfor a process that has exited.@item signalfor a process that has received a fatal signal.@item openfor a network connection that is open.@item closedfor a network connection that is closed. Once a connectionis closed, you cannot reopen it, though you might be able to opena new connection to the same place.@item nilif @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@groupx @result{} #<process xx<1>>(process-status x) @result{} exit@end group@end smallexampleFor a network connection, @code{process-status} returns one of the symbols@code{open} or @code{closed}. The latter means that the other sideclosed the connection, or Emacs did @code{delete-process}.In earlier Emacs versions (prior to version 19), the status of a networkconnection was @code{run} if open, and @code{exit} if closed.@end defun@defun process-exit-status processThis function returns the exit status of @var{process} or the signalnumber that killed it. (Use the result of @code{process-status} todetermine which of those it is.) If @var{process} has not yetterminated, the value is 0.@end defun@defun process-tty-name processThis function returns the terminal name that @var{process} is using forits communication with Emacs---or @code{nil} if it is using pipesinstead of a terminal (see @code{process-connection-type} in@ref{Asynchronous Processes}).@end defun@node Input to Processes@section Sending Input to Processes@cindex process input Asynchronous subprocesses receive input when it is sent to them byEmacs, which is done with the functions in this section. You mustspecify the process to send input to, and the input data to send. Thedata 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 amidstthe other characters, to force them through. For most programs,these @sc{eof}s do no harm.@defun process-send-string process-name stringThis function sends @var{process-name} the contents of @var{string} asstandard input. The argument @var{process-name} must be a process orthe name of a process. If it is @code{nil}, the current buffer'sprocess 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.texiintroduction.txt text.texi~...---------- Buffer: *shell* ----------@end group@end smallexample@end defun@deffn Command process-send-region process-name start endThis 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 ora process name. (If it is @code{nil}, the current buffer's process isused.)An error is signaled unless both @var{start} and @var{end} areintegers or markers that indicate positions in the current buffer. (Itis 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 itsinput. The @sc{eof} comes after any text already sent to it. If @var{process-name} is not supplied, or if it is @code{nil}, thenthis function sends the @sc{eof} to the current buffer's process. Anerror 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 itsactivities. There are several different signals, each with its ownmeaning. The set of signals and their names is defined by the operatingsystem. For example, the signal @code{SIGINT} means that the user hastyped @kbd{C-c}, or that some analogous thing has happened. Each signal has a standard effect on the subprocess. Most signalskill the subprocess, but some stop or resume execution instead. Mostsignals can optionally be handled by programs; if the program handlesthe signal, then we can say nothing in general about its effects. You can send signals explicitly by calling the functions in thissection. Emacs also sends signals automatically at certain times:killing a buffer sends a @code{SIGHUP} signal to all its associatedprocesses; killing Emacs sends a @code{SIGHUP} signal to all remainingprocesses. (@code{SIGHUP} is a signal that usually indicates that theuser 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 ofone, or @code{nil}. If it is @code{nil}, the process defaults to theprocess 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 differencewhen you are running a job-control shell as an Emacs subprocess. If itis non-@code{nil}, then the signal is sent to the current process-groupof the terminal that Emacs uses to communicate with the subprocess. Ifthe process is a job-control shell, this means the shell's currentsubjob. If it is @code{nil}, the signal is sent to the process group ofthe immediate subprocess of Emacs. If the subprocess is a job-controlshell, this is the shell itself. The flag @var{current-group} has no effect when a pipe is used tocommunicate with the subprocess, because the operating system does notsupport 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-groupThis function interrupts the process @var{process-name} by sending thesignal @code{SIGINT}. Outside of Emacs, typing the ``interruptcharacter'' (normally @kbd{C-c} on some systems, and @code{DEL} onothers) sends this signal. When the argument @var{current-group} isnon-@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-groupThis function kills the process @var{process-name} by sending thesignal @code{SIGKILL}. This signal kills the subprocess immediately,and cannot be handled by the subprocess.@end defun@defun quit-process &optional process-name current-groupThis function sends the signal @code{SIGQUIT} to the process@var{process-name}. This signal is the one sent by the ``quitcharacter'' (usually @kbd{C-b} or @kbd{C-\}) when you are not insideEmacs.@end defun@defun stop-process &optional process-name current-groupThis function stops the process @var{process-name} by sending thesignal @code{SIGTSTP}. Use @code{continue-process} to resume itsexecution.On systems with job control, the ``stop character'' (usually @kbd{C-z})sends this signal (outside of Emacs). When @var{current-group} isnon-@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-groupThis function resumes execution of the process @var{process} by sendingit the signal @code{SIGCONT}. This presumes that @var{process-name} wasstopped previously.@end defun@c Emacs 19 feature@defun signal-process pid signalThis function sends a signal to process @var{pid}, which need not bea child of Emacs. The argument @var{signal} specifies which signalto 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 toits standard output stream. The output can be inserted in a buffer,which is called the associated buffer of the process, or a functioncalled the @dfn{filter function} can be called to act on the output. Ifthe process has no buffer and no filter function, its output isdiscarded.@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: storingthe output from the process, and deciding when to kill the process. Youcan also use the buffer to identify a process to operate on, since innormal practice only one process is associated with any given buffer.Many applications of processes also use the buffer for editing input tobe 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 insertthe output is determined by the @code{process-mark}, which is thenupdated to point to the end of the text just inserted. Usually, but notalways, the @code{process-mark} is at the end of the buffer.@defun process-buffer processThis 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 processThis function returns the process marker for @var{process}, which is themarker that says where to insert output from the process.If @var{process} does not have a buffer, @code{process-mark} returns amarker that points nowhere.Insertion of process output in a buffer uses this marker to decide whereto insert, and updates it to point after the inserted text. That is whysuccessive batches of output are inserted consecutively.Filter functions normally should use this marker in the same fashionas is done by direct insertion of output in the buffer. A goodexample of a filter function that uses @code{process-mark} is found atthe end of the following section.When the user is expected to enter input in the process buffer fortransmission to the process, the process marker is useful fordistinguishing the new input from previous output.@end defun@defun set-process-buffer process bufferThis function sets the buffer associated with @var{process} to@var{buffer}. If @var{buffer} is @code{nil}, the process becomesassociated with no buffer.@end defun@defun get-buffer-process buffer-or-nameThis 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 isusually a bad idea to have more than one process associated with thesame buffer.@smallexample@group(get-buffer-process "*shell*") @result{} #<process shell>@end group@end smallexampleKilling the process's buffer deletes the process, which kills thesubprocess 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 thestandard output from the associated process. If a process has a filter,then @emph{all} output from that process is passed to the filter. Theprocess buffer is used directly for output from the process only whenthere is no filter. A filter function must accept two arguments: the associated process anda string, which is the output. The function is then free to do whatever itchooses with the output. A filter function runs only while Emacs is waiting (e.g., for terminalinput, or for time to elapse, or for process output). This avoids thetiming errors that could result from running filters at random places inthe middle of other Lisp programs. You may explicitly cause Emacs towait, so that filter functions will run, by calling @code{sit-for} or@code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output}(@pxref{Accepting Output}). Emacs is also waiting when the command loopis 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 usercommand would be unpredictable. If you want to permit quitting inside afilter function, bind @code{inhibit-quit} to @code{nil}.@xref{Quitting}. If an error happens during execution of a filter function, it iscaught automatically, so that it doesn't stop the execution of whateverprogram was running when the filter function was started. However, if@code{debug-on-error} is non-@code{nil}, the error-catching is turnedoff. This makes it possible to use the Lisp debugger to debug thefilter function. @xref{Debugger}. Many filter functions sometimes or always insert the text in theprocess's buffer, mimicking the actions of Emacs when there is nofilter. Such filter functions need to use @code{set-buffer} in order tobe sure to insert in that buffer. To avoid setting the current buffersemipermanently, these filter functions must use @code{unwind-protect}to make sure to restore the previous current buffer. They should alsoupdate 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@noindentThe reason to use an explicit @code{unwind-protect} rather than letting@code{save-excursion} restore the current buffer is so as to preservethe change in point made by @code{goto-char}. To make the filter force the process buffer to be visible whenever newtext 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 whereit was previously, eliminate the variable @code{moving} and call@code{goto-char} unconditionally. In earlier Emacs versions, every filter function that did regexpsearching or matching had to explicitly save and restore the match data.Now Emacs does this automatically; filter functions never need to do itexplicitly. @xref{Match Data}. A filter function that writes the output into the buffer of theprocess should check whether the buffer is still alive. If it tries toinsert 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 programthat produces the same output twice in a row may send it as one batchof 200 characters one time, and five batches of 40 characters the next.@defun set-process-filter process filterThis 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 processThis 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{} nilkept @result{} ("lewis@@slug[8] % "@end group@group"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~address.txt backup.psf kolstad.psfbackup.bib~ david.mss resume-Dec-86.mss~backup.err david.psf resume-Dec.psfbackup.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 usethe process mark to do insertion in the same fashion as is done whenthere 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 whileEmacs is waiting for some sort of external event, such as elapsed timeor terminal input. Occasionally it is useful in a Lisp program toexplicitly permit output to arrive at a specific point, or even to waituntil output arrives from a process.@defun accept-process-output &optional process seconds millisecThis function allows Emacs to read pending output from processes. Theoutput is inserted in the associated buffers or given to their filterfunctions. If @var{process} is non-@code{nil} then this function doesnot return until some output has been received from @var{process}.@c Emacs 19 featureThe arguments @var{seconds} and @var{millisec} let you specify timeoutperiods. The former specifies a period measured in seconds and thelatter specifies one measured in milliseconds. The two time periodsthus specified are added together, and @code{accept-process-output}returns after that much time whether or not there has been anysubprocess output.The argument @var{seconds} need not be an integer. If it is a floatingpoint number, this function waits for a fractional number of seconds.Some systems support only a whole number of seconds; on these systems,@var{seconds} is rounded down. If the system doesn't support waitingfractions of a second, you get an error if you specify nonzero@var{millisec}.Not all operating systems support waiting periods other than multiplesof a second; on those that do not, you get an error if you specifynonzero @var{millisec}.The function @code{accept-process-output} returns non-@code{nil} if itdid get some output, or @code{nil} if the timeout expired before outputarrived.@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 theassociated process changes status for any reason, including signals(whether sent by Emacs or caused by the process's own actions) thatterminate, stop, or continue the process. The process sentinel is alsocalled if the process exits. The sentinel receives two arguments: theprocess for which the event occurred, and a string describing the typeof 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 timingerrors that could result from running them at random places in themiddle of other Lisp programs. A program can wait, so that sentinelswill run, by calling @code{sit-for} or @code{sleep-for}(@pxref{Waiting}), or @code{accept-process-output} (@pxref{AcceptingOutput}). Emacs is also waiting when the command loop is reading input. Quitting is normally inhibited within a sentinel---otherwise, theeffect of typing @kbd{C-g} at command level or to quit a user commandwould be unpredictable. If you want to permit quitting inside asentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}. A sentinel that writes the output into the buffer of the processshould check whether the buffer is still alive. If it tries to insertinto a dead buffer, it will get an error. If the buffer is dead,@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. If an error happens during execution of a sentinel, it is caughtautomatically, so that it doesn't stop the execution of whateverprograms was running when the sentinel was started. However, if@code{debug-on-error} is non-@code{nil}, the error-catching is turnedoff. This makes it possible to use the Lisp debugger to debug thesentinel. @xref{Debugger}. In earlier Emacs versions, every sentinel that did regexp searching ormatching had to explicitly save and restore the match data. Now Emacsdoes this automatically; sentinels never need to do it explicitly.@xref{Match Data}.@defun set-process-sentinel process sentinelThis 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 inthe 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 processThis function returns the sentinel of @var{process}, or @code{nil} if ithas none.@end defun@defun waiting-for-user-input-pWhile a sentinel or filter function is running, this function returnsnon-@code{nil} if Emacs was waiting for keyboard input from the user atthe time the sentinel or filter function was called, @code{nil} if itwas not.@end defun@node Transaction Queues@section Transaction Queues@cindex transaction queueYou can use a @dfn{transaction queue} for more convenient communicationwith subprocesses using transactions. First use @code{tq-create} tocreate a transaction queue communicating with a specified process. Thenyou can call @code{tq-enqueue} to send a transaction.@defun tq-create processThis function creates and returns a transaction queue communicating with@var{process}. The argument @var{process} should be a subprocesscapable of sending and receiving streams of bytes. It may be a childprocess, or it may be a TCP connection to a server, possibly on anothermachine.@end defun@defun tq-enqueue queue question regexp closure fnThis function sends a transaction to queue @var{queue}. Specifying thequeue has the effect of specifying the subprocess to talk to.The argument @var{question} is the outgoing message that starts thetransaction. The argument @var{fn} is the function to call when thecorresponding 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 theentire answer, but nothing less; that's how @code{tq-enqueue} determineswhere the answer ends.The return value of @code{tq-enqueue} itself is not meaningful.@end defun@defun tq-close queueShut down transaction queue @var{queue}, waiting for all pending transactionsto complete, and then terminate the connection or child process.@end defunTransaction queues are implemented by means of a filter function.@xref{Filter Functions}.@node Network@section Network Connections@cindex network connection@cindex TCP Emacs Lisp programs can open TCP network connections to other processes onthe same machine or other machines. A network connection is handled by Lispmuch like a subprocess, and is represented by a process object.However, the process you are communicating with is not a child of theEmacs process, so you can't kill it or send it signals. All you can dois send and receive data. @code{delete-process} closes the connection,but does not kill the process at the other end; that process must decidewhat to do about closure of the connection. You can distinguish process objects representing network connectionsfrom those representing subprocesses with the @code{process-status}function. It always returns either @code{open} or @code{closed} for anetwork connection, and it never returns either of those values for areal subprocess. @xref{Process Information}.@defun open-network-stream name buffer-or-name host serviceThis function opens a TCP connection for a service to a host. Itreturns a process object to represent the connection.The @var{name} argument specifies the name for the process object. Itis modified as necessary to make it unique.The @var{buffer-or-name} argument is the buffer to associate with theconnection. 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 notassociated 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 ofa defined network service (a string) or a port number (an integer).@end defun