X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/61cb81625eb951e2f119cb9e5fc73a34607736f9..2252bdcf999bcd1cc65f4a748995373241b15250:/lispref/processes.texi diff --git a/lispref/processes.texi b/lispref/processes.texi index 4d89ed41fd..7cf9607efc 100644 --- a/lispref/processes.texi +++ b/lispref/processes.texi @@ -1,9 +1,10 @@ @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 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/processes -@node Processes, System Interface, Abbrevs, Top +@node Processes, Display, Abbrevs, Top @chapter Processes @cindex child process @cindex parent process @@ -34,9 +35,8 @@ This function returns @code{t} if @var{object} is a process, @menu * Subprocess Creation:: Functions that start subprocesses. +* Shell Arguments:: Quoting an argument to pass it to a shell. * 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. @@ -46,7 +46,7 @@ This function returns @code{t} if @var{object} is a process, * 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. +* Network:: Opening network connections. @end menu @node Subprocess Creation @@ -59,7 +59,7 @@ 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 + Synchronous and asynchronous processes are explained in the following sections. Since the three functions are all called in a similar fashion, their common arguments are described here. @@ -80,20 +80,22 @@ 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{Read and Print}.) Normally, you should avoid having multiple -processes send output to the same buffer because their output would be -intermixed randomly. +go. It should be a buffer or a buffer name; if it is a buffer name, +that will create the buffer if it does not already exist. It can also +be @code{nil}, which says to discard the output unless a filter function +handles it. (@xref{Filter Functions}, and @ref{Read and Print}.) +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. +characters and other shell constructs have no special meanings in these +strings, since the whole strings are passed directly to the specified +program. - @strong{Please note:} the argument @var{program} contains only the + @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. @@ -101,17 +103,16 @@ must use @var{args} to provide those. @code{default-directory} (@pxref{File Name Expansion}). @cindex environment variables, subprocesses - The subprocess inherits its environment from Emacs; but you can + 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. +@pindex movemail +The value of this variable is a string, the name of a directory that +contains programs that come with GNU Emacs, programs intended for Emacs +to invoke. The program @code{movemail} is an example of such a program; +Rmail uses it to fetch new mail from an inbox. @end defvar @defopt exec-path @@ -126,50 +127,135 @@ The value of @code{exec-path} is used by @code{call-process} and file name. @end defopt +@node Shell Arguments +@section Shell Arguments + + Lisp programs sometimes need to run a shell and give it a command +that contains file names that were specified by the user. These +programs ought to be able to support any valid file name. But the shell +gives special treatment to certain characters, and if these characters +occur in the file name, they will confuse the shell. To handle these +characters, use the function @code{shell-quote-argument}: + +@defun shell-quote-argument argument +This function returns a string which represents, in shell syntax, +an argument whose actual contents are @var{argument}. It should +work reliably to concatenate the return value into a shell command +and then pass it to a shell for execution. + +Precisely what this function does depends on your operating system. The +function is designed to work with the syntax of your system's standard +shell; if you use an unusual shell, you will need to redefine this +function. + +@example +;; @r{This example shows the behavior on GNU and Unix systems.} +(shell-quote-argument "foo > bar") + @result{} "foo\\ \\>\\ bar" + +;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.} +(shell-quote-argument "foo > bar") + @result{} "\"foo > bar\"" +@end example + +Here's an example of using @code{shell-quote-argument} to construct +a shell command: + +@example +(concat "diff -c " + (shell-quote-argument oldfile) + " " + (shell-quote-argument newfile)) +@end example +@end defun + @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. +process to terminate before continuing. Starting Dired on GNU or +Unix@footnote{On other systems, Emacs uses a Lisp emulation of +@code{ls}; see @ref{Contents of Directories}.} 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}. +@code{SIGKILL} and quits immediately (except on MS-DOS, where killing +other processes doesn't work). @xref{Quitting}. + + The synchronous subprocess functions return an indication of how the +process terminated. - The synchronous subprocess functions returned @code{nil} in version -18. In version 19, they return an indication of how the process -terminated. + The output from a synchronous subprocess is generally decoded using a +coding system, much like text read from a file. The input sent to a +subprocess by @code{call-process-region} is encoded using a coding +system, much like text written into a file. @xref{Coding Systems}. -@defun call-process program &optional infile buffer-or-name display &rest args +@defun call-process program &optional infile destination 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. +@var{infile} is not @code{nil}, and from the null device otherwise. +The argument @var{destination} says where to put the process output. +Here are the possibilities: + +@table @asis +@item a buffer +Insert the output in that buffer, before point. This includes both the +standard output stream and the standard error stream of the process. + +@item a string +Insert the output in a buffer with that name, before point. + +@item @code{t} +Insert the output in the current buffer, before point. + +@item @code{nil} +Discard the output. + +@item 0 +Discard the output, and return @code{nil} immediately without waiting +for the subprocess to finish. + +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. + +MS-DOS doesn't support asynchronous subprocesses, so this option doesn't +work there. + +@item @code{(@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}. +If @var{error-destination} is @code{nil}, that means to discard the +error output, @code{t} means mix it with the ordinary output, and a +string specifies a file name to redirect error output into. + +You can't directly specify a buffer to put the error output in; that is +too difficult to implement. But you can achieve this result by sending +the error output to a temporary file and then inserting the file into a +buffer. +@end table 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 buffer as output is inserted. (However, if the coding system chosen +for decoding output is @code{undecided}, meaning deduce the encoding +from the actual data, then redisplay sometimes cannot continue once +non-@sc{ascii} characters are encountered. There are fundamental +reasons why it is hard to fix this; see @ref{Output from Processes}.) + +Otherwise the function @code{call-process} 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. @@ -185,7 +271,7 @@ In the examples below, the buffer @samp{foo} is current. @smallexample @group (call-process "pwd" nil t) - @result{} nil + @result{} 0 ---------- Buffer: foo ---------- /usr/user/lewis/manual @@ -194,7 +280,7 @@ In the examples below, the buffer @samp{foo} is current. @group (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") - @result{} nil + @result{} 0 ---------- Buffer: bar ---------- lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh @@ -203,12 +289,12 @@ lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh @end group @end smallexample -The @code{insert-directory} function contains a good example of the use -of @code{call-process}: +Here is a good example of the use of @code{call-process}, which used to +be found in the definition of @code{insert-directory}: @smallexample @group -(call-process insert-directory-program nil t nil switches +(call-process insert-directory-program nil t nil @var{switches} (if full-directory-p (concat (file-name-as-directory file) ".") file)) @@ -216,18 +302,20 @@ of @code{call-process}: @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 +@defun call-process-region start end program &optional delete destination display &rest args +This function sends the text from @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. +sent if @var{delete} is non-@code{nil}; this is useful when +@var{destination} is @code{t}, to insert the output in the current +buffer in place of the input. -The arguments @var{buffer-or-name} and @var{display} control what to do +The arguments @var{destination} 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}, 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. +immediately, without waiting for the subprocess to finish (this only +works if asynchronous subprocesses are supported). The remaining arguments, @var{args}, are strings that specify command line arguments for the program. @@ -241,7 +329,7 @@ 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 +@var{destination} is @code{t}, this output is inserted in the current buffer. @smallexample @@ -253,7 +341,7 @@ input@point{} @group (call-process-region 1 6 "cat" nil t) - @result{} nil + @result{} 0 ---------- Buffer: foo ---------- inputinput@point{} @@ -277,49 +365,33 @@ inputinput@point{} @end smallexample @end defun -@node MS-DOS Subprocesses -@section MS-DOS Subprocesses - - On MS-DOS, you must indicate whether the data going to and from -a synchronous subprocess are text or binary. Text data requires -translation between the end-of-line convention used within Emacs -(a single newline character) and the convention used outside Emacs -(the two-character sequence, CRLF). - - The variable @code{binary-process-input} applies to input sent to the -subprocess, and @code{binary-process-output} applies to output received -from 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-input -If this variable is @code{nil}, convert newlines to CRLF sequences in -the input to a synchronous subprocess. -@end defvar - -@defvar binary-process-output -If this variable is @code{nil}, convert CRLF sequences to newlines in -the output from a synchronous subprocess. -@end defvar - - @xref{Files and MS-DOS}, for related information. +@defun shell-command-to-string command +This function executes @var{command} (a string) as a shell command, +then returns the command's output as a string. +@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}. + After an @dfn{asynchronous process} is created, Emacs and the subprocess +both continue running immediately. The process thereafter runs +in parallel with Emacs, and the two can communicate with each other +using the functions described in the following sections. However, +communication is only partially asynchronous: Emacs sends data to the +process only when certain functions are called, and Emacs accepts data +from the process only when Emacs is waiting for input or for a time +delay. + + Here we describe how to create an asynchronous 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 +already exists, then @var{name} is modified (by appending @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 @@ -360,26 +432,34 @@ Process my-process finished 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. +command. The variable @code{shell-file-name} specifies which shell to +use. + +The point of running a program through the shell, rather than directly +with @code{start-process}, is so that you can employ shell features such +as wildcards in the arguments. It follows that if you include an +arbitrary user-specified arguments in the command, you should quote it +with @code{shell-quote-argument} first, so that any special shell +characters do @emph{not} have their special shell meanings. @xref{Shell +Arguments}. @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). +asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are +used, when available. Otherwise, pipes are used. @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. +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 +The value of @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}. @@ -390,6 +470,10 @@ with one subprocess by binding the variable around the call to (start-process @dots{})) @end group @end smallexample + +To determine whether a given subprocess actually got a pipe or a +@sc{pty}, use the function @code{process-tty-name} (@pxref{Process +Information}). @end defvar @node Deleting Processes @@ -400,20 +484,22 @@ with one subprocess by binding the variable around the call to 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. +continues to exist as long as other Lisp objects point to it. The +process mark continues to point to the same place as before (usually +into a buffer where output from the process was being inserted). 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 +@defopt 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 +@end defopt @defun delete-process name This function deletes the process associated with @var{name}, killing it @@ -428,10 +514,15 @@ the name of a process, a buffer, or the name of a buffer. @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}. +@defun process-kill-without-query process &optional do-query +This function specifies whether Emacs should query the user if +@var{process} is still running when Emacs is exited. If @var{do-query} +is @code{nil}, the process will be deleted silently. +Otherwise, Emacs will query about killing it. + +The value is @code{t} if the process was formerly set up to require +query, @code{nil} otherwise. A newly-created process always requires +query. @smallexample @group @@ -492,7 +583,7 @@ were given to the program. @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 +integer that 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. @@ -502,6 +593,12 @@ process is started and remains constant as long as the process exists. This function returns the name of @var{process}. @end defun +@defun process-contact process +This function returns @code{t} for an ordinary child process, and +@code{(@var{hostname} @var{service})} for a net connection +(@pxref{Network}). +@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 @@ -548,9 +645,6 @@ x 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 @@ -560,6 +654,30 @@ determine which of those it is.) If @var{process} has not yet terminated, the value is 0. @end defun +@defun process-tty-name process +This function returns the terminal name that @var{process} is using for +its communication with Emacs---or @code{nil} if it is using pipes +instead of a terminal (see @code{process-connection-type} in +@ref{Asynchronous Processes}). +@end defun + +@defun process-coding-system process +This function returns a cons cell describing the coding systems in use +for decoding output from @var{process} and for encoding input to +@var{process} (@pxref{Coding Systems}). The value has this form: + +@example +(@var{coding-system-for-decoding} . @var{coding-system-for-encoding}) +@end example +@end defun + +@defun set-process-coding-system process decoding-system encoding-system +This function specifies the coding systems to use for subsequent output +from and input to @var{process}. It will use @var{decoding-system} to +decode subprocess output, and @var{encoding-system} to encode subprocess +input. +@end defun + @node Input to Processes @section Sending Input to Processes @cindex process input @@ -574,6 +692,20 @@ data appears on the ``standard input'' of the subprocess. the other characters, to force them through. For most programs, these @sc{eof}s do no harm. + Subprocess input is normally encoded using a coding system before the +subprocess receives it, much like text written into a file. You can use +@code{set-process-coding-system} to specify which coding system to use +(@pxref{Process Information}). Otherwise, the coding system comes from +@code{coding-system-for-write}, if that is non-@code{nil}; or else from +the defaulting mechanism (@pxref{Default Coding Systems}). + + Sometimes the system is unable to accept input for that process, +because the input buffer is full. When this happens, the send functions +wait a short while, accepting output from subprocesses, and then try +again. This gives the subprocess a chance to read more of its pending +input and make space in the buffer. It also allows filters, sentinels +and timers to run---so take account of that in writing your code. + @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 @@ -601,7 +733,7 @@ introduction.txt text.texi~ @end smallexample @end defun -@deffn Command process-send-region process-name start end +@defun 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 @@ -610,7 +742,7 @@ 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 +@end defun @defun process-send-eof &optional process-name This function makes @var{process-name} see an end-of-file in its @@ -630,6 +762,14 @@ error is signaled if the current buffer has no process. @end smallexample @end defun +@defun process-running-child-p process +@tindex process-running-child-p process +This function will tell you whether a subprocess has given control of +its terminal to its own child process. The value is @code{t} if this is +true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain +that this is not so. +@end defun + @node Signals to Processes @section Sending Signals to Processes @cindex process signals @@ -665,7 +805,7 @@ process associated with the current buffer. An error is signaled if 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 +of the terminal that 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 @@ -704,10 +844,11 @@ 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. +Outside of Emacs, on systems with job control, the ``stop character'' +(usually @kbd{C-z}) normally sends this signal. 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 @@ -731,7 +872,43 @@ to send; it should be an integer. 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. +called the @dfn{filter function} can be called to act on the output. If +the process has no buffer and no filter function, its output is +discarded. + + Output from a subprocess can arrive only while Emacs is waiting: when +reading terminal input, in @code{sit-for} and @code{sleep-for} +(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting +Output}). This minimizes the problem of timing errors that usually +plague parallel programming. For example, you can safely create a +process and only then specify its buffer or filter function; no output +can arrive before you finish, if the code in between does not call any +primitive that waits. + + It is impossible to separate the standard output and standard error +streams of the subprocess, because Emacs normally spawns the subprocess +inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If +you want to keep the output to those streams separate, you should +redirect one of them to a file--for example, by using an appropriate +shell command. + + Subprocess output is normally decoded using a coding system before the +buffer or filter function receives it, much like text read from a file. +You can use @code{set-process-coding-system} to specify which coding +system to use (@pxref{Process Information}). Otherwise, the coding +system comes from @code{coding-system-for-read}, if that is +non-@code{nil}; or else from the defaulting mechanism (@pxref{Default +Coding Systems}). + + @strong{Warning:} Coding systems such as @code{undecided} which +determine the coding system from the data do not work entirely reliably +with asynchronous subprocess output. This is because Emacs has to +process asynchronous subprocess output in batches, as it arrives. Emacs +must try to detect the proper coding system from one batch at a time, +and this does not always work. Therefore, if at all possible, use a +coding system which determines both the character code conversion and +the end of line conversion---that is, one like @code{latin-1-unix}, +rather than @code{undecided} or @code{latin-1}. @menu * Process Buffers:: If no filter, output is put in a buffer. @@ -753,11 +930,9 @@ 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. +the output is determined by the @code{process-mark}, 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. @defun process-buffer process This function returns the associated buffer of the process @@ -788,8 +963,8 @@ 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. +transmission to the process, the process marker separates the new input +from previous output. @end defun @defun set-process-buffer process buffer @@ -801,7 +976,7 @@ associated with no buffer. @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 +(Currently, 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. @@ -823,21 +998,19 @@ subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). 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. +then @emph{all} output from that process is passed to the filter. The +process buffer is used directly for output from the process only when +there is no filter. + + The filter function can only be called when Emacs is waiting for +something, because process output arrives only at such times. Emacs +waits when reading terminal input, in @code{sit-for} and +@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output} +(@pxref{Accepting Output}). + + A filter function must accept two arguments: the associated process +and a string, which is output just received from it. The function is +then free to do whatever it chooses with the output. Quitting is normally inhibited within a filter function---otherwise, the effect of typing @kbd{C-g} at command level or to quit a user @@ -845,65 +1018,72 @@ command would be unpredictable. If you want to permit quitting inside a filter function, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}. + If an error happens during execution of a filter function, it is +caught automatically, so that it doesn't stop the execution of whatever +program was running when the filter function was started. However, if +@code{debug-on-error} is non-@code{nil}, the error-catching is turned +off. This makes it possible to use the Lisp debugger to debug the +filter function. @xref{Debugger}. + 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: +semipermanently, these filter functions must save and restore the +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))) + (with-current-buffer (process-buffer proc) + (let ((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)))) + (save-excursion + ;; @r{Insert the text, advancing the process marker.} + (goto-char (process-mark proc)) + (insert string) + (set-marker (process-mark proc) (point))) + (if moving (goto-char (process-mark proc)))))) @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}. +The reason to use @code{with-current-buffer}, rather than using +@code{save-excursion} to save and restore the current buffer, is so as +to preserve the change in point made by the second call to +@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}: +@code{with-current-buffer} construct: @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 + To force point 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}. + In earlier Emacs versions, every filter function that did regular +expression searching or matching had to explicitly save and restore the +match data. Now Emacs does this automatically for filter functions; +they never need to do it explicitly. @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}. +process should check whether the buffer is still alive. If it tries to +insert into a dead buffer, it will get an error. The expression +@code{(buffer-name (process-buffer @var{process}))} returns @code{nil} +if the buffer is dead. 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. +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. If +the filter looks for certain text strings in the subprocess output, make +sure to handle the case where one of these strings is split across two +or more batches of output. @defun set-process-filter process filter This function gives @var{process} the filter function @var{filter}. If @@ -959,15 +1139,15 @@ there is no filter function: ;; @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) + (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))) + (goto-char (point-max)) + (insert str) + (set-marker (process-mark proc) (point-max)) + (select-window cur))) @end group @end smallexample @end ignore @@ -995,6 +1175,11 @@ thus specified are added together, and @code{accept-process-output} returns after that much time whether or not there has been any subprocess output. +The argument @var{seconds} need not be an integer. If it is a floating +point 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. + 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}. @@ -1037,9 +1222,10 @@ of event. 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. +will run, by calling @code{sit-for} or @code{sleep-for} +(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting +Output}). Emacs also allows sentinels to run 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 @@ -1047,14 +1233,21 @@ 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 +should check whether the buffer 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}. + If an error happens during execution of a sentinel, it is caught +automatically, so that it doesn't stop the execution of whatever +programs was running when the sentinel was started. However, if +@code{debug-on-error} is non-@code{nil}, the error-catching is turned +off. This makes it possible to use the Lisp debugger to debug the +sentinel. @xref{Debugger}. + + In earlier Emacs versions, every sentinel that did regular expression +searching or matching had to explicitly save and restore the match data. +Now Emacs does this automatically for sentinels; they never need to do +it explicitly. @xref{Match Data}. @defun set-process-sentinel process sentinel This function associates @var{sentinel} with @var{process}. If @@ -1094,16 +1287,16 @@ was not. @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. +You can use a @dfn{transaction queue} to communicate with a subprocess +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 +process, or it may be a TCP connection to a server, possibly on another machine. @end defun @@ -1111,14 +1304,14 @@ machine. 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 +The argument @var{question} is the outgoing message that 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 argument @var{regexp} is a regular expression that should match +text at the end of the entire answer, but nothing before; that's how +@code{tq-enqueue} determines where the answer ends. The return value of @code{tq-enqueue} itself is not meaningful. @end defun @@ -1131,12 +1324,13 @@ to complete, and then terminate the connection or child process. Transaction queues are implemented by means of a filter function. @xref{Filter Functions}. -@node TCP -@section TCP +@node Network +@section Network Connections +@cindex network connection @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 + Emacs Lisp programs can open TCP network 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 @@ -1146,7 +1340,9 @@ 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}. +function. It always returns either @code{open} or @code{closed} for a +network connection, and it never returns either of those values for a +real subprocess. @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