xemacs-beta: man/lispref/processes.texi comparison

comparison man/lispref/processes.texi @ 0:376386a54a3c r19-14

Import from CVS: tag r19-14

author	cvs
date	Mon, 13 Aug 2007 08:45:50 +0200
parents
children	abe6d1db359e

comparison

equal deleted inserted replaced

--1:000000000000
+:376386a54a3c
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/processes.info
+@node Processes, System Interface, Databases, 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.  XEmacs runs in a process.  XEmacs Lisp
+programs can invoke other programs in processes of their own.  These are
+called @dfn{subprocesses} or @dfn{child processes} of the XEmacs process,
+which is their @dfn{parent process}.
+A subprocess of XEmacs 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 XEmacs 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.
+* 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.
+* Process Window Size::      Changing the logical window size of a process.
+* 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 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{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.
+@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 XEmacs; 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 XEmacs, that are intended for XEmacs
+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, XEmacs 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 XEmacs 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 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 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
+Find or create a buffer with that name, then insert
+the 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 0
+Discard the output, and return 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.
+@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 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 XEmacs
+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 destination 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{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{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 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{destination} 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 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, @sc{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 @sc{crlf} sequences in
+the input to a synchronous subprocess.
+@end defvar
+@defvar binary-process-output
+If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
+the 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 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 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.
+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
+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
+@section Deleting Processes
+@cindex deleting processes
+@dfn{Deleting a process} disconnects XEmacs 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 &optional require-query-p
+This function declares that XEmacs need not query the user if
+@var{process} is still running when XEmacs is exited.  The process will
+be deleted silently.  If @var{require-query-p} is non-@code{nil},
+then XEmacs @emph{will} query the user (this is the default).  The
+return value is @code{t} if a query was formerly required, and
+@code{nil} otherwise.
+@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 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.
+@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 XEmacs 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-kill-without-query-p process
+This function returns whether @var{process} will be killed without
+querying the user, if it is running when XEmacs is exited.  The default
+value is @code{nil}.
+@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
+@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
+@node Input to Processes
+@section Sending Input to Processes
+@cindex process input
+Asynchronous subprocesses receive input when it is sent to them by
+XEmacs, 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.
+The set of signals and their names is defined by the operating system;
+XEmacs has facilities for sending only a few of the signals that are
+defined.  XEmacs can send signals only to its own subprocesses.
+You can send signals explicitly by calling the functions in this
+section.  XEmacs also sends signals automatically at certain times:
+killing a buffer sends a @code{SIGHUP} signal to all its associated
+processes; killing XEmacs 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 XEmacs subprocess.  If it
+is non-@code{nil}, then the signal is sent to the current process-group
+of the terminal that XEmacs 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 XEmacs.  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 XEmacs, 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 XEmacs 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
+XEmacs.
+@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 XEmacs).  When @var{current-group} is
+non-@code{nil}, you can think of this function as ``typing @kbd{C-z}''
+on the terminal XEmacs 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 XEmacs.  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.  If
+the process has no buffer and no filter function, its output is
+discarded.
+@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 XEmacs 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}, 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
+@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 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 XEmacs 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} or
+@code{sleep-for} (@pxref{Waiting}), 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}.
+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 XEmacs 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.
+In earlier Emacs versions, every filter function that did regexp
+searching or matching had to explicitly save and restore the match data.
+Now Emacs does this automatically; filter functions 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 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}.
+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}, then the process will have no filter.  If
+@var{filter} is @code{t}, then no output from the process will be
+accepted until the filter is changed. (Output received during this
+time is not discarded, but is queued, and will be processed as soon
+as the filter is changed.)
+@end defun
+@defun process-filter process
+This function returns the filter function of @var{process}, or @code{nil}
+if it has none.  @code{t} means that output processing has been stopped.
+@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
+XEmacs 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 XEmacs 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.  Note that @var{seconds} is allowed to be a
+floating-point number; thus, there is no need to ever use
+@var{millisec}. (It is retained for compatibility purposes.)
+@ignore Not in XEmacs
+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.  If the system doesn't support waiting
+fractions of a second, you get an error if you specify nonzero
+@var{millisec}.
+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}.
+@end ignore
+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 XEmacs 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 XEmacs 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} or @code{sleep-for}
+(@pxref{Waiting}), 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 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}.
+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 regexp searching or
+matching had to explicitly save and restore the match data.  Now Emacs
+does this automatically; sentinels never need to do it explicitly.
+@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 XEmacs 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
+@c XEmacs feature
+@node Process Window Size
+@section Process Window Size
+@cindex process window size
+@defun set-process-window-size process height width
+This function tells @var{process} that its logical window size is
+@var{height} by @var{width} characters.  This is principally useful
+with pty's.
+@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 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 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 Network
+@section Network Connections
+@cindex network connection
+@cindex TCP
+XEmacs 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
+XEmacs 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.  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
+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 or IP address (a string), and @var{service}
+is the name of a defined network service (a string) or a port number (an
+integer).
+@end defun

Mercurial > hg > xemacs-beta

comparison man/lispref/processes.texi @ 0:376386a54a3c r19-14