diff lispref/processes.texi @ 6558:fa8ff07eaafc

Initial revision

--- /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