comparison lispref/processes.texi @ 21682:90da2489c498

*** empty log message ***

21681:11eafe90b842

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/processes
@node Processes, System Interface, Abbrevs, Top
@chapter Processes
@cindex child process
@cindex parent process
@cindex subprocess
@cindex process

@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

The value of @code{exec-path} is used by @code{call-process} and
@code{start-process} when the @var{program} argument is not an absolute
file name.
@end defopt

@node Synchronous Processes
@section Creating a Synchronous Process
@cindex synchronous subprocess

  After a @dfn{synchronous process} is created, Emacs waits for the

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.  Now they return an indication of how the process terminated.

  The output from a synchronous subprocess is generally decoded using a
coding system, much like text read from a file.  The input sent to a
subprocess by @code{call-process-region} is encoded using a coding
system, much like text written into a file.  @xref{Coding Systems}.

@defun call-process program &optional infile destination display &rest args
This function calls @var{program} in a separate process and waits for
it to finish.

@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 the 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}

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

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

@tindex shell-command-to-string
@defun shell-command-to-string command
This function executes @var{command} (a string) as a shell command,
then returns the command's output as a string.
@end defun

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

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.  The variable @code{shell-file-name} specifies which shell to
use.
@end defun

@defvar process-connection-type
@cindex pipes
@cindex @sc{pty}s

@end smallexample

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

In Emacs version 18, the status of a network connection was @code{run}
if open, and @code{exit} if closed.
@end defun

@defun process-exit-status process
This function returns the exit status of @var{process} or the signal
number that killed it.  (Use the result of @code{process-status} to

This function returns a cons cell describing the coding systems in use
for decoding output from @var{process} and for encoding input to
@var{process} (@pxref{Coding Systems}).  The value has this form:

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

@tindex set-process-coding-system
@defun set-process-coding-system process decoding-system encoding-system

@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, outside of Emacs)\, 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

21682:90da2489c498

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/processes
@node Processes, Display, Abbrevs, Top
@chapter Processes
@cindex child process
@cindex parent process
@cindex subprocess
@cindex process

@end defun

@menu
* Subprocess Creation::      Functions that start subprocesses.
* Synchronous Processes::    Details of using synchronous subprocesses.
* Asynchronous Processes::   Starting up an asynchronous subprocess.
* Deleting Processes::       Eliminating an asynchronous subprocess.
* Process Information::      Accessing run-status and other attributes.
* Input to Processes::       Sending input to an asynchronous subprocess.
* Signals to Processes::     Stopping, continuing or interrupting

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 Shell Arguments
@section Shell Arguments

  Lisp programs sometimes need to run a shell and give it a command
which contains file names that were specified by the user.  These
programs ought to be able to support any valid file name.  But the shell
gives special treatment to certain characters, and if these characters
occur in the file name, they will confuse the shell.  To handle these
characters, use the function @code{shell-quote-argument}:

@defun shell-quote-argument argument
This function returns a string which represents, in shell syntax,
an argument whose actual contents are @var{argument}.  It should
work reliably to concatenate the return value into a shell command
and then pass it to a shell for execution.

Precisely what this function does depends on your operating system.  The
function is designed to work with the usual shell syntax; if you use an
unusual shell, you will need to redefine this function.  On MS-DOS, the
function returns @var{argument} unchanged; while this is not really
correct, it is the best one can do, since the MS-DOS shell has no
quoting features.

@example
;; @r{This example shows the behavior on GNU and Unix systems.}
(shell-quote-argument "foo > bar")
     @result{} "foo\\ \\>\\ bar"
@end example

Here's an example of using @code{shell-quote-argument} to construct
a shell command:

@example
(concat "diff -c "
        (shell-quote-argument oldfile)
        " "
        (shell-quote-argument newfile))
@end example
@end defun

@node Synchronous Processes
@section Creating a Synchronous Process
@cindex synchronous subprocess

  After a @dfn{synchronous process} is created, Emacs waits for the

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 return an indication of how the
process terminated.

  The output from a synchronous subprocess is generally decoded using a
coding system, much like text read from a file.  The input sent to a
subprocess by @code{call-process-region} is encoded using a coding
system, much like text written into a file.  @xref{Coding Systems}.
On Microsoft operating systems, additional variables control
the conversion for end-of-line (@pxref{MS-DOS Subprocesses}).

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

@item a buffer
Insert the output in that buffer, before point.  This includes both the
standard output stream and the standard error stream of the process.

@item a string
Insert the output in a buffer with that name, before point.

@item @code{t}
Insert the output in the current buffer, before point.

@item @code{nil}

@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}.
If @var{error-destination} is @code{nil}, that means to discard the
error output, @code{t} means mix it with the ordinary output, and a
string specifies a file name to redirect error output into.

You can't directly specify a buffer to put the error output in; that is
too difficult to implement.  But you can achieve this result by sending
the error output to a temporary file and then inserting the file into a
buffer.

---------- Buffer: bar ----------
@end group
@end smallexample

Here is a good example of the use of @code{call-process}, which used to
be found in the definition of @code{insert-directory}:

@smallexample
@group
(call-process insert-directory-program nil t nil @var{switches}
              (if full-directory-p
                  (concat (file-name-as-directory file) ".")
                file))
@end group
@end smallexample

@tindex shell-command-to-string
@defun shell-command-to-string command
This function executes @var{command} (a string) as a shell command,
then returns the command's output as a string.
@end defun

@node Asynchronous Processes
@section Creating an Asynchronous Process
@cindex asynchronous subprocess

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.  The variable @code{shell-file-name} specifies which shell to
use.

The point of running a program through the shell, rather than directly
with @code{start-process}, is so that you can employ shell features such
as wildcards in the arguments.  It follows that if you include an
arbitrary user-specified filename in the command, you should quote it
with @code{shell-quote-argument} first, so that any special shell
characters in the file name do @emph{not} have their special shell
meanings.  @xref{Shell Arguments}.
@end defun

@defvar process-connection-type
@cindex pipes
@cindex @sc{pty}s

@end smallexample

For a network connection, @code{process-status} returns one of the symbols
@code{open} or @code{closed}.  The latter means that the other side
closed the connection, or Emacs did @code{delete-process}.
@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

This function returns a cons cell describing the coding systems in use
for decoding output from @var{process} and for encoding input to
@var{process} (@pxref{Coding Systems}).  The value has this form:

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

@tindex set-process-coding-system
@defun set-process-coding-system process decoding-system encoding-system

@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