comparison lispref/processes.texi @ 90114:e4694597cbf4

Revision: [e-mail]--gnu-2005/emacs--unicode--0--patch-21 Merge from emacs--cvs-trunk--0 Patches applied: * [e-mail]--gnu-2005/emacs--cvs-trunk--0 (patch 129-149) - Update from CVS - Merge from gnus--rel--5.10 - (make-text-button): Default button type if not specified - quick-install-emacs: Use mkdir --verbose only when requested * [e-mail]--gnu-2005/gnus--rel--5.10 (patch 31-33) - Merge from emacs--cvs-trunk--0 - Update from CVS

90113:a50413a4ba8b

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}).

  Executing a program can also try adding suffixes to the specified
name:

@defvar exec-suffixes
This variable is a list of suffixes (strings) to try adding to the
specified program file name.  The list should include @code{""} if you
want the name to be tried exactly as specified.  The default value is
system-dependent.
@end defvar

  Each of the subprocess-creating functions has a @var{buffer-or-name}
argument which specifies where the standard output from the program will
go.  It should be a buffer or a buffer name; if it is a buffer name,
that will create the buffer if it does not already exist.  It can also

@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 have no special meanings in these
strings, since the whole strings are passed directly to the specified
program.

  @strong{Please note:} The argument @var{program} contains only the
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

  @dfn{Deleting a process} disconnects Emacs immediately from the
subprocess.  Processes are deleted automatically after they terminate,
but not necessarily right away.  You can delete a process explicitly
at any time.  If you delete a terminated process explicitly before it
is deleted automatically, no harm results.  Deletion of a running
process sends a signal to terminate it (and its child processes if
any), and calls the process sentinel if it has one.

  @code{get-buffer-process} and @code{process-list} do not remember a
deleted process, but the process object itself continues to exist as
long as other Lisp objects point to it.  All the Lisp primitives that
work on process objects accept deleted processes, but those that do
I/O or send signals will report an error.  The process mark continues
to point to the same place as before, usually into a buffer where
output from the process was being inserted.

@defopt delete-exited-processes
This variable controls automatic deletion of processes that have
terminated (due to calling @code{exit} or to a signal).  If it is
@code{nil}, then they continue to exist until the user runs
@code{list-processes}.  Otherwise, they are deleted immediately after
they exit.
@end defopt

@defun delete-process name
This function deletes the process associated with @var{name}, killing
it with a @code{SIGKILL} signal.  The argument @var{name} may be a
process, the name of a process, a buffer, or the name of a buffer.
Calling @code{delete-process} on a running process terminates it,
updates the process status, and runs the sentinel (if any) immediately.
If the process has already terminated, calling @code{delete-process}
has no effect on its status, or on the running of its sentinel (which
will happen sooner or later).

@smallexample
@group
(delete-process "*shell*")
     @result{} nil

@example
(@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
@end example
@end defun

@defun set-process-coding-system process decoding-system encoding-system
This function specifies the coding systems to use for subsequent output
from and input to @var{process}.  It will use @var{decoding-system} to
decode subprocess output, and @var{encoding-system} to encode subprocess
input.
@end defun

wait a short while, accepting output from subprocesses, and then try
again.  This gives the subprocess a chance to read more of its pending
input and make space in the buffer.  It also allows filters, sentinels
and timers to run---so take account of that in writing your code.

@defun process-send-string process-name string
This function sends @var{process-name} the contents of @var{string} as
standard input.  The argument @var{process-name} must be a process or
the name of a process.  If it is @code{nil}, the current buffer's
process is used.

  The function returns @code{nil}.

@smallexample
@group

---------- Buffer: *shell* ----------
@end group
@end smallexample
@end defun

@defun process-send-region process-name start end
This function sends the text in the region defined by @var{start} and
@var{end} as standard input to @var{process-name}, which is a process or
a process name.  (If it is @code{nil}, the current buffer's process is
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 defun

@defun process-send-eof &optional process-name
  This function makes @var{process-name} see an end-of-file in its
input.  The @acronym{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 @acronym{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"

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 that Emacs uses to communicate with the subprocess.  If

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.

Outside of Emacs, on systems with job control, the ``stop character''
(usually @kbd{C-z}) normally sends this signal.  When
@var{current-group} is non-@code{nil}, you can think of this function as
``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
subprocess.
@end defun

@defun continue-process &optional process-name current-group
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 process signal
This function sends a signal to process @var{process}.  The argument
@var{signal} specifies which signal to send; it should be an integer.

You can specify the target process by its process @acronym{ID}; that allows
you to send signals to processes that are not children of Emacs.
@end defun

@node Output from Processes
@section Receiving Output from Processes
@cindex process output

  When Emacs writes process output directly into a multibyte buffer,
it decodes the output according to the process output coding system.
If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
converts the unibyte output to multibyte using
@code{string-to-multibyte}, inserts the resulting multibyte text.

  You can use @code{set-process-coding-system} to specify which coding
system to use (@pxref{Process Information}).  Otherwise, the coding
system comes from @code{coding-system-for-read}, if that is
non-@code{nil}; or else from the defaulting mechanism (@pxref{Default

@node Query Before Exit
@section Querying Before Exit

  When Emacs exits, it terminates all its subprocesses by sending them
the @code{SIGHUP} signal.  Because some subprocesses are doing
valuable work, Emacs normally asks the user to confirm that it is ok
to terminate them.  Each process has a query flag which, if
non-@code{nil}, says that Emacs should ask for confirmation before
exiting and thus killing that process.  The default for the query flag
is @code{t}, meaning @emph{do} query.

90114:e4694597cbf4

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}).  @code{nil} in this list refers to
@code{default-directory}.

  Executing a program can also try adding suffixes to the specified
name:

@defvar exec-suffixes
This variable is a list of suffixes (strings) to try adding to the
specified program file name.  The list should include @code{""} if you
want the name to be tried exactly as specified.  The default value is
system-dependent.
@end defvar

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

  Each of the subprocess-creating functions has a @var{buffer-or-name}
argument which specifies where the standard output from the program will
go.  It should be a buffer or a buffer name; if it is a buffer name,
that will create the buffer if it does not already exist.  It can also

@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 have no special meanings in these
strings, since the strings are passed directly to the specified program.

  The subprocess gets its current directory from the value of
@code{default-directory} (@pxref{File Name Expansion}).

@cindex environment variables, subprocesses

  @dfn{Deleting a process} disconnects Emacs immediately from the
subprocess.  Processes are deleted automatically after they terminate,
but not necessarily right away.  You can delete a process explicitly
at any time.  If you delete a terminated process explicitly before it
is deleted automatically, no harm results.  Deleting a running
process sends a signal to terminate it (and its child processes if
any), and calls the process sentinel if it has one.  @xref{Sentinels}.

  When a process is deleted, the process object itself continues to
exist as long as other Lisp objects point to it.  All the Lisp
primitives that work on process objects accept deleted processes, but
those that do I/O or send signals will report an error.  The process
mark continues to point to the same place as before, usually into a
buffer where output from the process was being inserted.

@defopt delete-exited-processes
This variable controls automatic deletion of processes that have
terminated (due to calling @code{exit} or to a signal).  If it is
@code{nil}, then they continue to exist until the user runs
@code{list-processes}.  Otherwise, they are deleted immediately after
they exit.
@end defopt

@defun delete-process process
This function deletes a process, killing it with a @code{SIGKILL}
signal.  The argument may be a process, the name of a process, a
buffer, or the name of a buffer.  (A buffer or buffer-name stands for
the process that @code{get-buffer-process} returns.)  Calling
@code{delete-process} on a running process terminates it, updates the
process status, and runs the sentinel (if any) immediately.  If the
process has already terminated, calling @code{delete-process} has no
effect on its status, or on the running of its sentinel (which will
happen sooner or later).

@smallexample
@group
(delete-process "*shell*")
     @result{} nil

@example
(@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
@end example
@end defun

@defun set-process-coding-system process &optional decoding-system encoding-system
This function specifies the coding systems to use for subsequent output
from and input to @var{process}.  It will use @var{decoding-system} to
decode subprocess output, and @var{encoding-system} to encode subprocess
input.
@end defun

wait a short while, accepting output from subprocesses, and then try
again.  This gives the subprocess a chance to read more of its pending
input and make space in the buffer.  It also allows filters, sentinels
and timers to run---so take account of that in writing your code.

  In these functions, the @var{process} argument can be a process or
the name of a process, or a buffer or buffer name (which stands
for a process via @code{get-buffer-process}).  @code{nil} means
the current buffer's process.

@defun process-send-string process string
This function sends @var{process} the contents of @var{string} as
standard input.  If it is @code{nil}, the current buffer's process is used.

  The function returns @code{nil}.

@smallexample
@group

---------- Buffer: *shell* ----------
@end group
@end smallexample
@end defun

@defun process-send-region process start end
This function sends the text in the region defined by @var{start} and
@var{end} as standard input to @var{process}.

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 defun

@defun process-send-eof &optional process
This function makes @var{process} see an end-of-file in its
input.  The @acronym{EOF} comes after any text already sent to it.

The function returns @var{process}.

@smallexample
@group
(process-send-eof "shell")
     @result{} "shell"

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} must be either a process, a process
name, a buffer, a buffer name, or @code{nil}.  A buffer or buffer name
stands for a process through @code{get-buffer-process}.  @code{nil}
stands for the process associated with the current buffer.  An error
is signaled if @var{process} 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 that Emacs uses to communicate with the subprocess.  If

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 current-group
This function interrupts the process @var{process} 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 current-group
This function kills the process @var{process} 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 current-group
This function sends the signal @code{SIGQUIT} to the process
@var{process}.  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 current-group
This function stops the process @var{process} by sending the
signal @code{SIGTSTP}.  Use @code{continue-process} to resume its
execution.

Outside of Emacs, on systems with job control, the ``stop character''
(usually @kbd{C-z}) normally sends this signal.  When
@var{current-group} is non-@code{nil}, you can think of this function as
``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
subprocess.
@end defun

@defun continue-process &optional process current-group
This function resumes execution of the process @var{process} by sending
it the signal @code{SIGCONT}.  This presumes that @var{process} was
stopped previously.
@end defun

@c Emacs 19 feature
@defun signal-process process signal
This function sends a signal to process @var{process}.  The argument
@var{signal} specifies which signal to send; it should be an integer.

The @var{process} argument can be a system process @acronym{ID}; that
allows you to send signals to processes that are not children of
Emacs.
@end defun

@node Output from Processes
@section Receiving Output from Processes
@cindex process output

  When Emacs writes process output directly into a multibyte buffer,
it decodes the output according to the process output coding system.
If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
converts the unibyte output to multibyte using
@code{string-to-multibyte}, and inserts the resulting multibyte text.

  You can use @code{set-process-coding-system} to specify which coding
system to use (@pxref{Process Information}).  Otherwise, the coding
system comes from @code{coding-system-for-read}, if that is
non-@code{nil}; or else from the defaulting mechanism (@pxref{Default

@node Query Before Exit
@section Querying Before Exit

  When Emacs exits, it terminates all its subprocesses by sending them
the @code{SIGHUP} signal.  Because subprocesses may be doing
valuable work, Emacs normally asks the user to confirm that it is ok
to terminate them.  Each process has a query flag which, if
non-@code{nil}, says that Emacs should ask for confirmation before
exiting and thus killing that process.  The default for the query flag
is @code{t}, meaning @emph{do} query.