⟦b7f472403⟧

TextFile

@setfilename ../info/processes
@node Processes, Operating System Interface, Abbreviations, Top
@chapter Processes

  A subprocess of Emacs is represented within Emacs by an object called a
@dfn{process}.  Creating a new (asynchronous) subprocess of Emacs results
in the creation of a process object to represent it for use by Emacs Lisp.

  Emacs provides functions for manipulating processes in most of the
ways you might desire: you may send signals, obtain information from
processes, and so on.

  I/O for a process can be handled in several different ways by the
operating system.  The standard I/O may be directed though a pipe, or
through a @dfn{pseudo terminal} (or ``pty'').

@menu
* Functions that Create Subprocesses::	
* Creating a Synchronous Process::	
* Creating an Asynchronous Process::	
* Deleting Processes::	
* Process Information::	
* Sending Input to Processes::	
* Sending Signals to Processes::	
* Receiving Information from Processes::	
* Subprocess Functions for VMS::	
* TCP::	
@end menu

@defun processp object
 This function returns @code{t} if @var{object} is a process,
@code{nil} otherwise.
@end defun

@node Functions that Create Subprocesses, Creating a Synchronous Process, Processes, Processes
@section Functions that Create Subprocesses

  There are three functions that create a new Unix subprocess in which
to run a program.  The first, @code{start-process}, creates an
asynchronous process and returns a process object.  The other two,
@code{call-process} and @code{call-process-region}, create a synchronous
process and do not return a process object.  Synchronous and asychonous
processes are explained in following sections.  (@xref{Creating an
Asynchronous Process}, and @pxref{Creating a Synchronous Process}.)
Since the three functions are all called in a similar fashion, their
common arguments are described here.

@cindex execute program
@vindex PATH
@vindex HOME
  In all cases, the program to be run, named by the function's
@var{program} argument, is found by following the normal rules for Unix:
if an absolute file name is given for the program, then the program must
be found in the specified place.  If a relative file name is given, then
the program is searched for in each of the directories in
@code{exec-path}, which is set to the user's @code{PATH} variable on
entering Emacs.  The standard symbols, @samp{~}, @samp{.}, and
@samp{..}, are interpreted the same as by Unix shells.  Environment
variables (@file{HOME}, etc.) are not substituted for.  See
@code{expand-file-name} in @ref{Relative File Names}.  It is an error if
the program is not found.

  Each of the subprocess creating functions has a @var{buffer-or-name}
argument.  This argument specifies where the standard output from the
program will go.  @var{buffer-or-name} may be either a buffer or the
name of one; the buffer will be created if it does not already exist.
If @var{buffer-or-name} is @code{nil}, then the output will be discarded
by directing it to @file{/dev/null} unless a filter function is
specified to handle it.  (@xref{Process Filters}, and @pxref{Streams}.)
Normally, you do not want more than one process to send output to the
same buffer because the outputs will 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.
@strong{Note} that the argument @var{program} is only the name of the
program; it may not contain any arguments for the @var{program}.

  Subprocesses also inherit an environment from Emacs; but you can
specify overrides for it with @code{process-environment}.

@defvar process-environment
@cindex shell environment variables
  This global variable is a list of strings to append to the environment
of processes that are started.  Each string assigns a value to a shell
environment variable.  (This applies both to asynchronous and
synchronous processes.)

@example
process-environment
@result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
    "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
    "USER=lewis" 
    "TERM=ibmapa16" 
    "SHELL=/bin/csh"
    "HOME=/user/lewis")
@end example
@end defvar

@defvar exec-directory 
@pindex loadst
  The value of this variable is the name of a directory (a string) that
contains programs that come with GNU Emacs, which are intended for Emacs
to invoke.  The program @code{loadst} is an example of such a program;
it is used by the @code{display time} command and prints a string of the
current time one per minute minute.  We sometimes refer to the default
value of the @code{exec-directory} as @file{emacs/etc}.
@end defvar

@defopt exec-path
@cindex program directories
@vindex default-directory
  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}).

  @code{ exec-path} is used by @code{call-process} or
@code{start-process} when its @var{program} argument does not contain an
absolute file name.
@end defopt

@node Creating a Synchronous Process, Creating an Asynchronous Process, Functions that Create Subprocesses, Processes
@section Creating a Synchronous Process

  After a @dfn{synchronous process} is created, Emacs waits for the
process to terminate before continuing.  Starting @code{dired} is an
example of this: it runs @code{ls} in a synchronous process, then
modifies the output slightly.  You are not able to type a command until
this is finished.

@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.  It returns @code{nil}.

  The process standard input 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 the argument names a buffer.  If @var{buffer-or-name} is @code{t},
output is sent to the current buffer; and if @var{buffer-or-name} is
@code{nil}, output is discarded. 

  If @var{buffer-or-name} is 0, the output is discarded and
@code{call-process} returns immediately.  In this case, the process is
not truly synchronous, since it can run in parallel with Emacs; but
since Emacs gets no output from it, you can think of it as that.  Emacs
is essentially finished with the subprocess when the 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; you will see the results (put in a buffer) only if and when
Emacs redisplays that buffer.

  The remaining arguments, @var{args}, are strings that will be supplied
as the command line arguments for the program.

  While the @code{call-process} function waits for @var{program} to
terminate; if you quit by typing @kbd{C-g}, the
process is killed by sending it a @sc{sigkill} signal.

  The examples below are both run with the buffer @samp{foo} current.

@example
(call-process "pwd" nil t)
     @result{} nil

---------- Buffer: foo ----------
/usr/user/lewis/manual
---------- Buffer: foo ----------

(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 example

The @code{dired-readin} function contains a good example of the use of
@code{call-process}:

@example
(call-process "ls" nil buffer nil dired-listing-switches dirname)
@end example
@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}.  You might want to do this if you are
going to insert the output back in the curent buffer.

  If @var{buffer-or-name} names a buffer, the output is inserted in that
buffer at point.  If @var{buffer-or-name} is @code{t}, then the output
is sent to the current buffer.  If @var{buffer-or-name} is @code{nil},
the output is discarded.

  If @var{display} is non-@code{nil}, then @code{call-process-region}
redisplays the buffer as output is inserted.  Otherwise the function does no
redisplay; you will see the results (put in a buffer) only if and when
Emacs redisplays that buffer.

  The remaining arguments, @var{args}, are strings that are supplied
as the command line arguments for the program.

The @code{shell-command-on-region} function uses
@code{call-process-region}:

@example
(call-process-region start end 
                     shell-file-name    ; @r{Name of program.}
                     nil                ; @r{Do not delete region.}
                     buffer             ; @r{Send output to @var{buffer}.}
                     nil                ; @r{No redisplay during output.}
                     "-c" command)      ; @r{Arguments supplied program.}
@end example

  The @code{call-process-region} function normally waits for the process
to terminate; but if you quit (for example, by typing @kbd{C-g}), the
process is killed.

  In the first example below, the @code{cat} utility is called with
standard input being the first five characters in buffer @samp{foo} (the
word @code{input}).  @code{cat} copies its standard input into its
standard output.  This causes it to be inserted into the buffer.  The
function returns @code{nil}.

@example
---------- Buffer: foo ----------
input
---------- Buffer: foo ----------

(call-process-region 1 6 "cat" nil t)
     @result{} nil

---------- Buffer: foo ----------
inputinput
---------- Buffer: foo ----------
@end example
@end defun

@node Creating an Asynchronous Process, Deleting Processes, Creating a Synchronous Process, Processes
@section Creating an Asynchronous Process

  After an @dfn{asynchronous process} is created by
@code{start-process}, control returns to Emacs.  The process may
thereafter run at the same time as Emacs; and it and Emacs may
communicate with each other using the functions described in following
sections.

@defun start-process name buffer-or-name program &rest args
  This function creates a new process and starts a program in that
process.  The process will be named @var{name} (modified as necessary to
be unique).  The buffer @var{buffer-or-name} is the buffer to associate
with the process.  @var{program} is the program to run.

  The remaining arguments, @var{args}, are strings that will be supplied
as the command line arguments for the program.

  @code{start-process} returns the process object created.

The name given to the process is guaranteed to be unique among
processes.  It will be the name supplied by the user, or the name
modified (by appending @samp{<1>}, @samp{<2>}, etc.) if necessary to
make it unique.

  In the example below, the first process is started and runs (well,
sleeps) for 100 seconds.  Meanwhile, the second process is started and
runs to completion, inserting the directory listing at the end of the
buffer @code{foo} before the first process finishes.  After the first
process finishes, Emacs inserts @samp{Process my-process finished} at
the end of the buffer.

@example
(start-process "my-process" "foo" "sleep" "100")
     @result{} #<process my-process>

(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 example
@end defun

@defvar process-connection-type
@cindex pipes
@cindex ptys
  This global variable controls the type of device used to communicate
with subprocesses.  If it is @code{nil}, then pipes are used.  If it is
@code{t}, then @sc{ptys} are used (or pipes if @sc{ptys} not
supported---this is determined by the C constant @code{HAVE_PTYS}, which
must be defined when Emacs is compiled.).  @sc{ptys} are usually
preferable because they allow job control (@kbd{C-c, C-z, etc.}) to work
between the process and its children whereas pipes do not; the @code{shell}
command uses @sc{ptys} by default.

  The value @code{process-connection-type} is used when
@code{start-process} is called, so to change it for just one call of
@code{start-process}, temporarily rebind it with @code{let}.

@example
(let ((process-connection-type nil))  ; use a pipe
  (start-process @dots{}))
@end example
@end defvar

@node Deleting Processes, Process Information, Creating an Asynchronous Process, Processes
@section Deleting Processes

@defvar delete-exited-processes
  This global variable determines when exited processes will be deleted.
If it is @code{nil}, then they will not be deleted until
@code{list-processes} is run; otherwise, they will be deleted immediately
after they exit.
@end defvar

@defun delete-process name
  This function deletes the process associated with @var{name}.
@var{name} may be a process, the name of a process, a buffer, or the
name of a buffer.  The subprocess is killed with a @code{SIGHUP} signal.

@example
(delete-process "*shell*")
     @result{} nil
@end example
@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.  It returns @code{t}.

@example
(process-kill-without-query (get-process "shell"))
     @result{} t
@end example
@end defun

@node Process Information, Sending Input to Processes, Deleting Processes, Processes
@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.  (Any
processes listed as Exited or Signaled are actually eliminated after the
listing is made.)  This function returns @code{nil}.
@end deffn

@defun process-list
  This function returns a list of all processes that are still alive.

@example
(process-list)
     @result{} (#<process display-time> #<process shell>)
@end example
@end defun

@defun get-process name
  This function returns the process named @var{name}, or @code{nil} if
there is none.  It is an error if @var{name} is not a string.

@example
(get-process "shell")
     @result{} #<process shell>
@end example
@end defun

@defvar mode-line-process
  This buffer-local variable contains the mode line information on
process status.  It is displayed immediately following the major mode
name, with no intervening space.  For example, its value in the
@samp{*shell*} buffer is @code{(":@: %s")}, which allows the shell to
display its status along with the major mode as: @samp{(Shell:@: run)}.
Normally this variable is @code{nil}.
@end defvar

@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 given to
it.

@example
(process-command (get-process "shell"))
     @result{} ("/bin/csh" "-i")
@end example
@end defun

@defun process-exit-status process
  This function returns the exit status of @var{process} or the signal
number that killed it.  If @var{process} has not yet exited or died,
the value is 0.
@end defun

@defun process-id process
  This function returns the process id of @var{process}.  This is the @sc{pid}
of the Unix process which @var{process} refers to.
@end defun

@defun process-mark process
  This function returns the marker which indicates the end of the last
output from @var{process} into its buffer (@pxref{Process Buffers}).
This marker controls where additional output from the process will be
inserted.  Usually, it will be at the end of the buffer.

If @var{process} does not insert its output into a buffer, then
@code{process-mark} returns a marker that points nowhere.
@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.
@var{process-name} must be either a process or a string.  If it is a
string, it need not name an actual process.

@c (What is returned for net connections opened by `open-network-stream'??)

The possible values 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 nil
 if @var{process-name} does not exist.
@end table

@example
(process-status "shell")
     @result{} run
(process-status "never-existed")
     @result{} nil
x
     @result{} #<process xx<1>>
(process-status x)
     @result{} exit
@end example

For a network stream, @code{process-status} returns the symbols
@code{open} or @code{closed}.  The latter means that the other side
closed the connection, or Emacs  did @code{delete-process}.
@end defun

@node Sending Input to Processes, Sending Signals to Processes, Process Information, Processes
@section Sending Input to Processes
@cindex process input

  Asynchronous subprocesses receive input when it is sent to them by
Emacs.  This is done by calling one of the functions in this section.
You must specify the process to send input to, and the input.  The data
you send appears on the ``standard input'' of the subprocess.

  The kernel may fail if you send more characters than it will hold in
an input buffer.  If necessary, use a temporary file, and send a program
to read it.

@defun process-send-string process-name string
  This function sends @var{process-name} the contents of @var{string} as
standard input.   @var{process-name} must be a process or the name of one.

  The function returns @code{nil}.

@example
(process-send-string "shell<1>" "ls\n")
     @result{} nil

---------- Buffer: *shell* ----------
...
introduction.texinfo            syntax-tables.texinfo~
introduction.texinfo~           text.texinfo
introduction.txt                text.texinfo~
...
---------- Buffer: *shell* ----------
@end example
@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.

  It is an error 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 send the @sc{eof} to the current buffer's process.  It is
an error if the current buffer has no process.

  The function returns @var{process-name}.

@example
(process-send-eof "shell")
     @result{} "shell"
@end example
@end defun

@node Sending Signals to Processes, Receiving Information from Processes, Sending Input to Processes, Processes
@section Sending Signals to Processes
@cindex process 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.  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 execution or resume execution
instead.  Some programs handle certain signals and non-standard things.

  The set of signals and their names is defined by the operating system;
Emacs has facilities for sending only a few of the signals that are
defined.

  Emacs can send signals only to its own subprocesses.  This is done
with the functions below, or automatically: 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.  It is an error if
@var{process-name} does not identify a process.

  The argument @var{current-group} is a flag which 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{Creating an Asynchronous
Process}.

@defun interrupt-process &optional process-name current-group
  This function interrupts the process @var{process-name} by sending the
Unix signal @code{SIGINT}.  When you are not in Emacs, typing the ``interrupt
character'' (usually @kbd{C-c} on Berkeley Unix) 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 Unix
signal @code{SIGKILL}.  This signal kills the subprocess immediately; it
cannot be handled by the subprocess.
@end defun

@defun quit-process &optional process-name current-group
  This function sends the Unix 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 Unix
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 (when you are not inside 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 causes the process @var{process} to be continued by
sending the Unix signal @code{SIGCONT}.  This presumes that
@var{process-name} was stopped previously.
@end defun

@node Receiving Information from Processes, Subprocess Functions for VMS, Sending Signals to Processes, Processes
@section Receiving Information from Processes
@cindex process output

  There are three ways to receive information asynchronously from a process;
two are for standard output and the third is for the process status.
It is important to note that the filter and sentinel functions are
only called when Emacs is waiting for something; they never run
while other Lisp code is running.  Similarly, output is only inserted
in an associated buffer when Emacs is waiting.

  You may explicitly cause Emacs to wait by calling @code{sit-for},
@code{sleep-for}, or @code{accept-process-output}.  Emacs also waits in
the command loop for the next key command.

  All sentinels and filters 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 accept-process-output &optional process
  This function allows pending output from any processes to be read by
Emacs.  It is read into the process 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 that process.
@end defun

@defun waiting-for-user-input-p
  This function returns non-@code{nil} if Emacs is waiting for keyboard
input from the user, @code{nil} if it is not.  This is intended for use by
asynchronous process output filters and sentinels.
@end defun

@menu
* Process Filters::     
* Process Buffers::     
* Process Sentinels::   
@end menu

@node Process Filters, Process Buffers, Receiving Information from Processes, Receiving Information from Processes
@subsection Process Filters

  A @dfn{process filter} is a function that receives the standard output
from the associated process.  If a process has a filter, then @emph{all}
standard output from that process will be sent to the filter rather than be
inserted into a buffer or discarded.

  A filter function runs onlywhile Emacs is waiting.

  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 to with the output.

  The output to the function may come in any sized chunks.  A Unix
command that produces the same output twice in a row may send it as
one string of 200 characters one time, and five strings 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.

@example
(defun keep-output (process output)
   (setq kept (cons output kept)))
     @result{} keep-output
(setq kept nil)
     @result{} nil
(set-process-filter (get-process "shell") 'keep-output)
     @result{} keep-output
(process-send-string "shell" "ls ~/other\n")
     @result{} nil
kept
     @result{} ("lewis@@slug[8] % "
"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
")

@findex pop-to-buffer @r{example}
@findex process-mark @r{example}
;; @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)
      (goto-char (point-max))
      (insert str)
      (set-marker (process-mark proc) (point-max))
      (select-window cur)))
@end example
@end defun

@defun process-filter process
  This function returns the filter function of @var{process}, or @code{nil}
if has none.
@end defun

@node Process Buffers, Process Sentinels, Process Filters, Receiving Information from Processes
@subsection Process Buffers

  The buffer that a process is associated with is where the standard
output from that process will be inserted (if the process does not have
a filter function).  Output is always inserted at the
@code{process-mark} (@pxref{Process Information}), which is then updated
to point to the end of the text just inserted.  Often, the
@code{process-mark} will be at the end of the buffer.

@defun set-process-buffer process buffer
  This function sets the buffer associated with @var{process} to
@var{buffer}.  If @var{buffer} is @code{nil}, then the process will
not be associated with any buffer at all.
@end defun

@defun process-buffer process
  This function returns the buffer @var{process} is associated with.

@example
(process-buffer (get-process "shell"))
     @result{} #<buffer *shell*>
@end example
@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.) Normally, you should avoid having more than one
process with the same buffer.

@example
(get-buffer-process "*shell*")
     @result{} #<process shell>
@end example

If the process's buffer is killed, the actual child process is killed
with a @code{SIGHUP} signal (@pxref{Sending Signals to Processes}).
@end defun

@node Process Sentinels,  , Process Buffers, Receiving Information from Processes
@subsection Process Sentinels

  A @dfn{process sentinel} is a function that is called whenever the
associated process changes status.  This includes anything that
terminates, stops, or continues the process; and the @dfn{process
sentinel} is called if the process exits on its own.  The sentinel is
called with 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:

@ignore
@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 ignore

A sentinel is called for any signal that Emacs finds out about (anything
fatal or that stops the process).  A sentinel is also called if Emacs
sends a @code{SIGCONT} signal to a process.

@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.

@example
(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
(kill-process (get-process "shell"))
     @result{} Process: #<process shell> had the event `killed'
     @result{} #<process shell>
@end example
@end defun

@defun process-sentinel process
  This function returns the sentinel of @var{process}, or @code{nil} if it
has none.
@end defun

@node Subprocess Functions for VMS, TCP, Receiving Information from Processes, Processes
@section Subprocess Functions for VMS

The ordinary subprocess functions do not work on VMS.  Instead, these
are available.

@defun default-subprocess-input-handler
  This function is the default input handler for input from spawned
subprocesses.
@end defun

@defun send-command-to-subprocess name command
  This function sends the string @var{command} to a VMS subprocess named
@var{name}.
@end defun

@defun spawn-subprocess
  This function spawns an asynchronous VMS subprocess for command
processing.
@end defun

@defun stop-subprocess process-name
  This function stops a VMS subprocess named @var{name}.
@end defun

@node TCP,  , Subprocess Functions for VMS, Processes
@section TCP

  This is how you can open a network connection to any program or server
that might be listening.  This much like communication with a subprocess
except that the process is not a chile of Emacs and it must already
exist.  The connection is represented by a process object, just like an
ordinary subprocess.  You can distinguish connections from subprocesses
using @code{process-status}.

Input and output work as for subprocesses; @code{delete-process} closes
the connection.

@defun open-network-stream name buffer host service
  This function opens a TCP connection for a service to a host.  It returns
a subprocess-object to represent the connection.

  The @var{name} argument is the name for the `process'.  It is modified
if necessary to make it unique.  

  The @var{buffer-or-name} argument is the buffer to associate with the
connection.  Output from the connection goes at end of the buffer,
unless you specify an output stream or filter function to handle the
output.  @var{buffer-or-name} may be also @code{nil}, which means that
the connection is not associated with any buffer

@var{service} is name of the service desired, or an integer specifying a
port number to connect to.
@end defun
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦b7f472403⟧ TextFile

Derivation

TextFile
