mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-01-03 11:33:37 +00:00
Code Issues Releases Activity

Improve and clarify documentation of subprocesses

Browse Source 
* doc/lispref/processes.texi (Subprocess Creation, Shell Arguments):
Mention 'make-process' rather than 'start-process'.  Update wrt
standard destinations of standard output/error streams and due to
different formats of arguments accepted by 'make-process'.
(Processes): Mention process objects that represent connections.
(Synchronous Processes): Minor clarifications.
(Asynchronous Processes): Describe 'make-process' and
'make-pipe-process' before 'start-process'.  Update and expand the
documentation.
(Deleting Processes, Process Information, Input to Processes)
(Signals to Processes, Query Before Exit, Network): Update and
expand the documentation, especially wrt process objects that
represent connections.
(Output from Processes): Mention the possibility of separating
stderr via 'make-process'.
(Filter Functions): Mention that stderr by default arrives at the
filter function together with stdout.  (Bug#24287)

* src/process.c (Fprocess_id, Fprocess_command)
(Fprocess_contact, Fprocess_type, Fstop_process): Doc fixes for
process objects that represent connections.
This commit is contained in:
Eli Zaretskii 2016-08-24 17:36:28 +03:00
parent 89eb09f6a1
commit 88a5052579
2 changed files with 389 additions and 286 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

649
doc/lispref/processes.texi
View File

@ -27,9 +27,18 @@ 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.
In addition to processes that run programs, Lisp programs can open
connections of several types to devices or processes running on the
same machine or on other machines. The supported connection types
are: TCP and UDP network connections, serial port connections, and
pipe connections. Each such connection is also represented by a
process object.
@defun processp object
This function returns @code{t} if @var{object} represents an Emacs
subprocess, @code{nil} otherwise.
process object, @code{nil} otherwise. The process object can
represent a subprocess running a program or a connection of any
supported type.
@end defun
In addition to subprocesses of the current Emacs session, you can
@ -67,7 +76,7 @@ Processes}.
@cindex process creation
There are three primitives that create a new subprocess in which to run
a program. One of them, @code{start-process}, creates an asynchronous
a program. One of them, @code{make-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
@ -82,15 +91,14 @@ fashion, their common arguments are described here.
@cindex execute program
@cindex @env{PATH} environment variable
@cindex @env{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 @env{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
In all cases, the functions specify 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 @env{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}.
@ -106,27 +114,36 @@ system-dependent.
@end defopt
@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 a separate argument, @var{args}, to provide those, as
described below.
name of the program file; it may not contain any command-line
arguments. You must use a separate argument, @var{args}, to provide
those, as described below.
Each of the subprocess-creating functions has a @var{buffer-or-name}
argument that 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
be @code{nil}, which says to discard the output, unless a custom 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.
For synchronous processes, you can send the output to a file instead
of a buffer.
argument that specifies where the 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 be
@code{nil}, which says to discard the output, unless a custom 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. For synchronous processes, you can send the output to a
file instead of a buffer (and the corresponding argument is therefore
more appropriately called @var{destination}). By default, both
standard output and standard error streams go to the same destination,
but all the 3 primitives allow optionally to direct the standard error
stream to a different destination.
@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.
All three of the subprocess-creating functions allow to specify
command-line arguments for the process to run. For @code{call-process}
and @code{call-process-region}, these come in the form of a
@code{&rest} argument, @var{args}. For @code{make-process}, both the
program to run and its command-line arguments are specified as a list
of strings. The command-line arguments must all be strings, and they
are supplied to the program as separate argument strings. Wildcard
characters and other shell constructs have no special meanings in
these strings, since the strings are passed directly to the specified
program.
@cindex environment variables, subprocesses
The subprocess inherits its environment from Emacs, but you can
@ -147,6 +164,7 @@ 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}).
@xref{Locating Files, executable-find}, for the details of this search.
@cindex program directories
The value of @code{exec-path} is used by @code{call-process} and
@ -210,11 +228,11 @@ a shell command:
The following two functions are useful for combining a list of
individual command-line argument strings into a single string, and
taking a string apart into a list of individual command-line
arguments. These functions are mainly intended for
converting user input in the minibuffer, a Lisp string, into a list of
string arguments to be passed to @code{call-process} or
@code{start-process}, or for converting such lists of arguments into
a single Lisp string to be presented in the minibuffer or echo area.
arguments. These functions are mainly intended for converting user
input in the minibuffer, a Lisp string, into a list of string
arguments to be passed to @code{make-process}, @code{call-process} or
@code{start-process}, or for converting such lists of arguments into a
single Lisp string to be presented in the minibuffer or echo area.
Note that if a shell is involved (e.g., if using
@code{call-process-shell-command}), arguments should still be
protected by @code{shell-quote-argument};
@ -331,7 +349,7 @@ 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 when the subprocess finishes.
@end table
If @var{display} is non-@code{nil}, then @code{call-process} redisplays
@ -346,13 +364,15 @@ results become visible on the screen only when Emacs redisplays that
buffer in the normal course of events.
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program.
line arguments for the program. Each string is passed to
@var{program} as a separate argument.
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.
@code{call-process} returns a string describing the signal. If you
told @code{call-process} not to wait, it returns @code{nil}.
In the examples below, the buffer @samp{foo} is current.
@ -510,10 +530,10 @@ inputinput@point{}
@defun call-process-shell-command command &optional infile destination display
This function executes the shell command @var{command} synchronously.
The arguments are handled as in @code{call-process}. An old calling
convention allowed passing any number of additional arguments after
@var{display}, which were concatenated to @var{command}; this is still
supported, but strongly discouraged.
The other arguments are handled as in @code{call-process}. An old
calling convention allowed passing any number of additional arguments
after @var{display}, which were concatenated to @var{command}; this is
still supported, but strongly discouraged.
@end defun
@defun process-file-shell-command command &optional infile destination display
@ -565,33 +585,169 @@ from the process only while waiting for input or for a time delay.
@cindex pipe
An asynchronous process is controlled either via a @dfn{pty}
(pseudo-terminal) or a @dfn{pipe}. The choice of pty or pipe is made
when creating the process, based on the value of the variable
@code{process-connection-type} (see below). Ptys are usually
preferable for processes visible to the user, as in Shell mode,
because they allow for job control (@kbd{C-c}, @kbd{C-z}, etc.)@:
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, and because
they are immune to stray character injections that ptys introduce for
large (around 500 byte) messages. Also, the total number of ptys is
limited on many systems and it is good not to waste them.
when creating the process, by default based on the value of the
variable @code{process-connection-type} (see below). If available,
ptys are usually preferable for processes visible to the user, as in
Shell mode, because they allow for job control (@kbd{C-c}, @kbd{C-z},
etc.)@: between the process and its children, and because interactive
programs treat ptys as terminal devices, whereas pipes don't support
these features. However, for subprocesses used by Lisp programs for
internal purposes, it is often better to use a pipe, because pipes are
more efficient, and because they are immune to stray character
injections that ptys introduce for large (around 500 byte) messages.
Also, the total number of ptys is limited on many systems and it is
good not to waste them.
@defun make-process &rest args
This function is the basic low-level primitive for starting
asynchronous subprocesses. It returns a process object representing
the subprocess. Compared to the more high-level @code{start-process},
described below, it takes keyword arguments, is more flexible, and
allows to specify process filters and sentinels in a single call.
The arguments @var{args} are a list of keyword/argument pairs.
Omitting a keyword is always equivalent to specifying it with value
@code{nil}. Here are the meaningful keywords:
@table @asis
@item :name @var{name}
Use the string @var{name} as the process name; if a process with this
name already exists, then @var{name} is modified (by appending
@samp{<1>}, etc.)@: to be unique.
@item :buffer @var{buffer}
Use @var{buffer} as the process buffer. If the value is @code{nil},
the subprocess is not associated with any buffer.
@item :command @var{command}
Use @var{command} as the command line of the process. The value
should be a list starting with the program's executable file name,
followed by strings to give to the program as its arguments. If
the first element of the list is @code{nil}, Emacs opens a new
pseudoterminal (pty) and associates its input and output with
@var{buffer}, without actually running any program; the rest of the
list elements are ignored in that case.
@item :coding @var{coding}
If @var{coding} is a symbol, it specifies the coding system to be
used for both reading and writing of data from and to the
connection. If @var{coding} is a cons cell
@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
will be used for reading and @var{encoding} for writing. The coding
system used for encoding the data written to the program is also used
for encoding the command-line arguments (but not the program itself,
whose file name is encoded as any other file name; @pxref{Encoding and
I/O, file-name-coding-system}).
If @var{coding} is @code{nil}, the default rules for finding the
coding system will apply. @xref{Default Coding Systems}.
@item :connection-type @var{TYPE}
Initialize the type of device used to communicate with the subprocess.
Possible values are @code{pty} to use a pty, @code{pipe} to use a
pipe, or @code{nil} to use the default derived from the value of the
@code{process-connection-type} variable. This parameter and the value
of @code{process-connection-type} are ignored if a non-@code{nil}
value is specified for the @code{:stderr} parameter; in that case, the
type will always be @code{pipe}.
@item :noquery @var{query-flag}
Initialize the process query flag to @var{query-flag}.
@xref{Query Before Exit}.
@item :stop @var{stopped}
If @var{stopped} is non-@code{nil}, start the process in the
stopped state.
@item :filter @var{filter}
Initialize the process filter to @var{filter}. If not specified, a
default filter will be provided, which can be overridden later.
@xref{Filter Functions}.
@item :sentinel @var{sentinel}
Initialize the process sentinel to @var{sentinel}. If not specified,
a default sentinel will be used, which can be overridden later.
@xref{Sentinels}.
@item :stderr @var{stderr}
Associate @var{stderr} with the standard error of the process. A
non-@code{nil} value should be either a buffer or a pipe process
created with @code{make-pipe-process}, described below.
@end table
The original argument list, modified with the actual connection
information, is available via the @code{process-contact} function.
@end defun
@defun make-pipe-process &rest args
This function creates a bidirectional pipe which can be attached to a
child process. This is useful with the @code{:stderr} keyword of
@code{make-process}. The function returns a process object.
The arguments @var{args} are a list of keyword/argument pairs.
Omitting a keyword is always equivalent to specifying it with value
@code{nil}.
Here are the meaningful keywords:
@table @asis
@item :name @var{name}
Use the string @var{name} as the process name. As with
@code{make-process}, it is modified if necessary to make it unique.
@item :buffer @var{buffer}
Use @var{buffer} as the process buffer.
@item :coding @var{coding}
If @var{coding} is a symbol, it specifies the coding system to be
used for both reading and writing of data from and to the
connection. If @var{coding} is a cons cell
@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
will be used for reading and @var{encoding} for writing.
If @var{coding} is @code{nil}, the default rules for finding the
coding system will apply. @xref{Default Coding Systems}.
@item :noquery @var{query-flag}
Initialize the process query flag to @var{query-flag}.
@xref{Query Before Exit}.
@item :stop @var{stopped}
If @var{stopped} is non-@code{nil}, start the process in the
stopped state.
@item :filter @var{filter}
Initialize the process filter to @var{filter}. If not specified, a
default filter will be provided, which can be changed later.
@xref{Filter Functions}.
@item :sentinel @var{sentinel}
Initialize the process sentinel to @var{sentinel}. If not specified,
a default sentinel will be used, which can be changed later.
@xref{Sentinels}.
@end table
The original argument list, modified with the actual connection
information, is available via the @code{process-contact} function.
@end defun
@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 appending @samp{<1>},
etc.)@: to be unique. The buffer @var{buffer-or-name} is the buffer to
associate with the process.
This function is a higher-level wrapper around @code{make-process},
exposing an interface that is similar to @code{call-process}. It
creates a new asynchronous subprocess and starts the specified
@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; as with @code{make-process}, it is
modified if necessary to make it unique. The buffer
@var{buffer-or-name} is the buffer to associate with the process.
If @var{program} is @code{nil}, Emacs opens a new pseudoterminal (pty)
and associates its input and output with @var{buffer-or-name}, without
creating a subprocess. In that case, the remaining arguments
@var{args} are ignored.
The remaining arguments, @var{args}, are strings that specify command
line arguments for the subprocess.
The rest of @var{args} are strings that specify command line arguments
for the subprocess.
In the example below, the first process is started and runs (rather,
sleeps) for 100 seconds (the output buffer @samp{foo} is created
@ -633,14 +789,14 @@ subprocess running @var{program} in it, and returns its process
object.
The difference from @code{start-process} is that this function may
invoked a file handler based on the value of @code{default-directory}.
invoke a file handler based on the value of @code{default-directory}.
This handler ought to run @var{program}, perhaps on the local host,
perhaps on a remote host that corresponds to @code{default-directory}.
In the latter case, the local part of @code{default-directory} becomes
the working directory of the process.
This function does not try to invoke file name handlers for
@var{program} or for the @var{program-args}.
@var{program} or for the rest of @var{args}.
Depending on the implementation of the file handler, it might not be
possible to apply @code{process-filter} or @code{process-sentinel} to
@ -654,19 +810,20 @@ this function does nothing and returns @code{nil}.
@end defun
@defun start-process-shell-command name buffer-or-name command
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. The variable @code{shell-file-name} specifies which shell to
use.
This function is like @code{start-process}, except that it uses a
shell to execute the specified @var{command}. The argument
@var{command} is a shell command string. 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 any
arbitrary user-specified arguments in the command, you should quote them
with @code{shell-quote-argument} first, so that any special shell
characters do @emph{not} have their special shell meanings. @xref{Shell
Arguments}. Of course, when executing commands based on user input
you should also consider the security implications.
with @code{make-process} or @code{start-process}, is so that you can
employ shell features such as wildcards in the arguments. It follows
that if you include any arbitrary user-specified arguments in the
command, you should quote them with @code{shell-quote-argument} first,
so that any special shell characters do @emph{not} have their special
shell meanings. @xref{Shell Arguments}. Of course, when executing
commands based on user input you should also consider the security
implications.
@end defun
@defun start-file-process-shell-command name buffer-or-name command
@ -681,9 +838,14 @@ asynchronous subprocesses. If it is non-@code{nil}, then ptys are
used, when available. Otherwise, pipes are used.
The value of @code{process-connection-type} takes effect 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}.
@code{make-process} or @code{start-process} is called. So you can
specify how to communicate with one subprocess by binding the variable
around the call to these functions.
Note that the value of this variable is ignored when
@code{make-process} is called with a non-@code{nil} value of the
@code{:stderr} parameter; in that case, Emacs will communicate with
the process using pipes.
@smallexample
@group
@ -697,117 +859,6 @@ use the function @code{process-tty-name} (@pxref{Process
Information}).
@end defvar
@defun make-process &rest args
This function is like @code{start-process}, but takes keyword arguments.
The arguments @var{args} are a list of keyword/argument pairs.
Omitting a keyword is always equivalent to specifying it with value
@code{nil}. Here are the meaningful keywords:
@table @asis
@item :name @var{name}
Use the string @var{name} as the process name. It is modified if
necessary to make it unique.
@item :buffer @var{buffer}
Use @var{buffer} as the process buffer.
@item :command @var{command}
Use @var{command} as the command line of the process. @var{command}
is a list starting with the program's executable file name, followed
by strings to give to program as arguments.
@item :coding @var{coding}
If @var{coding} is a symbol, it specifies the coding system to be
used for both reading and writing of data from and to the
connection. If @var{coding} is a cons cell
@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
will be used for reading and @var{encoding} for writing.
If @var{coding} is @code{nil}, the default rules for finding the
coding system will apply. @xref{Default Coding Systems}.
@item :connection-type @var{TYPE}
Initialize the type of device used to communicate with the subprocess.
Possible values are @code{pty} to use a pty, @code{pipe} to use a
pipe, or @code{nil} to use the default derived from the value of
the @code{process-connection-type} variable.
@item :noquery @var{query-flag}
Initialize the process query flag to @var{query-flag}.
@xref{Query Before Exit}.
@item :stop @var{stopped}
If @var{stopped} is non-@code{nil}, start the process in the
stopped state.
@item :filter @var{filter}
Initialize the process filter to @var{filter}. If not specified, a
default filter will be provided. @xref{Filter Functions}.
@item :sentinel @var{sentinel}
Initialize the process sentinel to @var{sentinel}. If not specified,
a default sentinel will be used. @xref{Sentinels}.
@item :stderr @var{stderr}
Associate @var{stderr} with the standard error of the process.
@var{stderr} is either a buffer or a pipe process created with
@code{make-pipe-process}.
@end table
The original argument list, modified with the actual connection
information, is available via the @code{process-contact} function.
@end defun
@defun make-pipe-process &rest args
This function creates a bidirectional pipe which can be attached to a
child process (currently only useful with the @code{:stderr} keyword
of @code{make-process}).
The arguments @var{args} are a list of keyword/argument pairs.
Omitting a keyword is always equivalent to specifying it with value
@code{nil}, except for @code{:coding}.
Here are the meaningful keywords:
@table @asis
@item :name @var{name}
Use the string @var{name} as the process name. It is modified if
necessary to make it unique.
@item :buffer @var{buffer}
Use @var{buffer} as the process buffer.
@item :coding @var{coding}
If @var{coding} is a symbol, it specifies the coding system to be
used for both reading and writing of data from and to the
connection. If @var{coding} is a cons cell
@w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
will be used for reading and @var{encoding} for writing.
If @var{coding} is @code{nil}, the default rules for finding the
coding system will apply. @xref{Default Coding Systems}.
@item :noquery @var{query-flag}
Initialize the process query flag to @var{query-flag}.
@xref{Query Before Exit}.
@item :stop @var{stopped}
If @var{stopped} is non-@code{nil}, start the process in the
stopped state.
@item :filter @var{filter}
Initialize the process filter to @var{filter}. If not specified, a
default filter will be provided. @xref{Filter Functions}.
@item :sentinel @var{sentinel}
Initialize the process sentinel to @var{sentinel}. If not specified,
a default sentinel will be used. @xref{Sentinels}.
@end table
The original argument list, modified with the actual connection
information, is available via the @code{process-contact} function.
@end defun
@node Deleting Processes
@section Deleting Processes
@cindex deleting processes
@ -837,14 +888,19 @@ they exit.
@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 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).
signal if the process was running a program. 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 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).
If the process object represents a network, serial, or pipe
connection, its status changes to @code{closed}; otherwise, it changes
to @code{signal}, unless the process already exited. @xref{Process
Information, process-status}.
@smallexample
@group
@ -886,7 +942,8 @@ This function returns a list of all processes that have not been deleted.
@defun get-process name
This function returns the process named @var{name} (a string), or
@code{nil} if there is none.
@code{nil} if there is none. The argument @var{name} can also be a
process object, in which case it is returned.
@smallexample
@group
@ -900,7 +957,9 @@ This function returns the process named @var{name} (a string), or
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.
were given to the program. For a network, serial, or pipe connection,
this is either @code{nil}, which means the process is running or
@code{t} (process is stopped).
@smallexample
@group
@ -911,18 +970,19 @@ were given to the program.
@end defun
@defun process-contact process &optional key
This function returns information about how a network or serial
process was set up. When @var{key} is @code{nil}, it returns
@code{(@var{hostname} @var{service})} for a network process, and
@code{(@var{port} @var{speed})} for a serial process.
For an ordinary child process, this function always returns @code{t}.
This function returns information about how a network, a serial, or a
pipe connection was set up. When @var{key} is @code{nil}, it returns
@code{(@var{hostname} @var{service})} for a network connection,
@code{(@var{port} @var{speed})} for a serial connection, and @code{t}
for a pipe connection. For an ordinary child process, this function
always returns @code{t} when called with a @code{nil} @var{key}.
If @var{key} is @code{t}, the value is the complete status information
for the connection, server, or serial port; that is, the list of
keywords and values specified in @code{make-network-process} or
@code{make-serial-process}, except that some of the values represent
the current status instead of what you specified.
for the connection, server, serial port, or pipe; that is, the list of
keywords and values specified in @code{make-network-process},
@code{make-serial-process}, or @code{make-pipe-process}, except that
some of the values represent the current status instead of what you
specified.
For a network process, the values include (see
@code{make-network-process} for a complete list):
@ -947,8 +1007,9 @@ this value is the actual port number.
@code{:local} and @code{:remote} are included even if they were not
specified explicitly in @code{make-network-process}.
For a serial process, see @code{make-serial-process} and
@code{serial-process-configure} for a list of keys.
For a serial connection, see @code{make-serial-process} and
@code{serial-process-configure} for the list of keys. For a pipe
connection, see @code{make-pipe-process} for the list of keys.
If @var{key} is a keyword, the function returns the value corresponding
to that keyword.
@ -956,10 +1017,12 @@ to that keyword.
@defun process-id process
This function returns the @acronym{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
@acronym{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.
integral number that distinguishes the process @var{process} from all
other processes running on the same computer at the current time. The
@acronym{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. For network, serial, and pipe connections, this
function returns @code{nil}.
@end defun
@defun process-name process
@ -983,11 +1046,11 @@ 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.
for a network, serial, or pipe 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.
for a network, serial, or pipe 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 connect
for a non-blocking connection that is waiting to complete.
@item failed
@ -1005,9 +1068,11 @@ if @var{process-name} is not the name of an existing process.
@end group
@end smallexample
For a network connection, @code{process-status} returns one of the symbols
@code{open} or @code{closed}. The latter means that the other side
closed the connection, or Emacs did @code{delete-process}.
For a network, serial, or pipe connection, @code{process-status}
returns one of the symbols @code{open}, @code{stop}, or @code{closed}.
The latter means that the other side closed the connection, or Emacs
did @code{delete-process}. The value @code{stop} means that
@code{stop-process} was called on the connection.
@end defun
@defun process-live-p process
@ -1018,24 +1083,29 @@ process is considered alive if its status is @code{run}, @code{open},
@defun process-type process
This function returns the symbol @code{network} for a network
connection or server, @code{serial} for a serial port connection, or
@code{real} for a real subprocess.
connection or server, @code{serial} for a serial port connection,
@code{pipe} for a pipe connection, or @code{real} for a subprocess
created for running a program.
@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.
terminated, the value is 0. For network, serial, and pipe connections
that are already closed, the value is either 0 or 256, depending on
whether the connection was closed normally or abnormally.
@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
instead of a pty (see @code{process-connection-type} in
@ref{Asynchronous Processes}). If @var{process} represents a program
running on a remote host, the terminal name used by that program on
the remote host is provided as process property @code{remote-tty}.
the remote host is provided as process property @code{remote-tty}. If
@var{process} represents a network, serial, or pipe connection, the
value is @code{nil}.
@end defun
@defun process-coding-system process
@ -1079,8 +1149,10 @@ This function sets the process plist of @var{process} to @var{plist}.
Asynchronous subprocesses receive input when it is sent to them by
Emacs, which is done with the functions in this section. You must
specify the process to send input to, and the input data to send. The
data appears on the standard input of the subprocess.
specify the process to send input to, and the input data to send. If
the subprocess runs a program, the data appears on the standard input
of that program; for connections, the data is sent to the connected
device or program.
@c FIXME which?
Some operating systems have limited space for buffered input in a
@ -1143,12 +1215,14 @@ The function returns @var{process}.
@end defun
@defun process-running-child-p &optional process
This function will tell you whether a @var{process} has given control
of its terminal to its own child process. If this is true, the
function returns the numeric ID of the foreground process group of
@var{process}; it returns @code{nil} if Emacs can be certain that this
is not so. The value is @code{t} if Emacs cannot tell whether this is
true.
This function will tell you whether a @var{process}, which must not be
a connection but a real subprocess, has given control of its terminal
to a child process of its own. If this is true, the function returns
the numeric ID of the foreground process group of @var{process}; it
returns @code{nil} if Emacs can be certain that this is not so. The
value is @code{t} if Emacs cannot tell whether this is true. This
function signals an error if @var{process} is a network, serial, or
pipe connection, or is the subprocess is not active.
@end defun
@node Signals to Processes
@ -1181,17 +1255,22 @@ user ``hung up the phone'', i.e., disconnected.)
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.
stands for the process associated with the current buffer. Except
with @code{stop-process} and @code{continue-process}, an error is
signaled if @var{process} does not identify an active process, or if
it represents a network, serial, or pipe connection.
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
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.
subjob. If @var{current-group} 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. If
@var{current-group} is @code{lambda}, the signal is sent to the
process-group that owns the terminal, but only if it is not 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
@ -1222,21 +1301,29 @@ 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
This function stops the specified @var{process}. If it is a real
subprocess running a program, it sends the signal @code{SIGTSTP} to
that subprocess. If @var{process} represents a network, serial, or
pipe connection, this function inhibits handling of the incoming data
from the connection; for a network server, this means not accepting
new connections. Use @code{continue-process} to resume normal
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.
(usually @kbd{C-z}) normally sends the @code{SIGTSTP} signal to a
subprocess. 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.
This function resumes execution of the process @var{process}. If it
is a real subprocess running a program, it sends the signal
@code{SIGCONT} to that subprocess; this presumes that @var{process}
was stopped previously. If @var{process} represents a network,
serial, or pipe connection, this function resumes handling of the
incoming data from the connection. For serial connections, data that
arrived during the time the process was stopped might be lost.
@end defun
@deffn Command signal-process process signal
@ -1254,12 +1341,28 @@ children of Emacs. @xref{System Processes}.
@cindex process output
@cindex output from processes
The output that a subprocess writes to its standard output stream
is passed to a function called the @dfn{filter function}. The default
filter function simply inserts the output into a buffer, which is
called the associated buffer of the process (@pxref{Process
Buffers}). If the process has no buffer then the default filter
discards the output.
The output that an asynchronous subprocess writes to its standard
output stream is passed to a function called the @dfn{filter
function}. The default filter function simply inserts the output into
a buffer, which is called the associated buffer of the process
(@pxref{Process Buffers}). If the process has no buffer then the
default filter discards the output.
If the subprocess writes to its standard error stream, by default
the error output is also passed to the process filter function. If
Emacs uses a pseudo-TTY (pty) for communication with the subprocess,
then it is impossible to separate the standard output and standard
error streams of the subprocess, because a pseudo-TTY has only one
output channel. In that case, if you want to keep the output to those
streams separate, you should redirect one of them to a file---for
example, by using an appropriate shell command via
@code{start-process-shell-command} or a similar function.
Alternatively, you could use the @code{:stderr} parameter with a
non-@code{nil} value in a call to @code{make-process}
(@pxref{Asynchronous Processes, make-process}) to make the destination
of the error output separate from the standard output; in that case,
Emacs will use pipes for communicating with the subprocess.
When a subprocess terminates, Emacs reads any pending output,
then stops reading output from that subprocess. Therefore, if the
@ -1286,13 +1389,6 @@ from such processes, thus allowing them to produce more output before
Emacs tries to read it.
@end defvar
It is impossible to separate the standard output and standard error
streams of the subprocess, because Emacs normally spawns the subprocess
inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If
you want to keep the output to those streams separate, you should
redirect one of them to a file---for example, by using an appropriate
shell command.
@menu
* Process Buffers:: By default, output is put in a buffer.
* Filter Functions:: Filter functions accept output from the process.
@ -1327,7 +1423,7 @@ Before Exit}). This confirmation is done by the function
@code{kill-buffer-query-functions} (@pxref{Killing Buffers}).
@defun process-buffer process
This function returns the associated buffer of the process
This function returns the associated buffer of the specified
@var{process}.
@smallexample
@ -1449,6 +1545,11 @@ standard output from the associated process. @emph{All} output from
that process is passed to the filter. The default filter simply
outputs directly to the process buffer.
By default, the error output from the process, if any, is also
passed to the filter function, unless the destination for the standard
error stream of the process was separated from the standard output
when the process was created (@pxref{Output from Processes}).
The filter function can only be called when Emacs is waiting for
something, because process output arrives only at such times. Emacs
waits when reading terminal input (see the function
@ -1472,8 +1573,8 @@ cases, the right way to do this is with the macro
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}, errors are not caught.
This makes it possible to use the Lisp debugger to debug the
filter function. @xref{Debugger}.
This makes it possible to use the Lisp debugger to debug filter
functions. @xref{Debugger}.
Many filter functions sometimes (or always) insert the output in the
process's buffer, mimicking the actions of the default filter.
@ -1511,8 +1612,8 @@ text arrives, you could insert a line like the following just before the
@end smallexample
To force point to the end of the new output, no matter where it was
previously, eliminate the variable @code{moving} and call
@code{goto-char} unconditionally.
previously, eliminate the variable @code{moving} from the example and
call @code{goto-char} unconditionally.
@ignore
In earlier Emacs versions, every filter function that did regular
@ -1835,10 +1936,11 @@ was not.
@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
When Emacs exits, it terminates all its subprocesses. For
subprocesses that run a program, it sends them the @code{SIGHUP}
signal; connections are simply closed. 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.
@ -2132,13 +2234,14 @@ the @code{open-network-stream} function described below.
To distinguish the different types of processes, the
@code{process-type} function returns the symbol @code{network} for a
network connection or server, @code{serial} for a serial port
connection, or @code{real} for a real subprocess.
connection, @code{pipe} for a pipe connection, or @code{real} for a
real subprocess.
The @code{process-status} function returns @code{open},
@code{closed}, @code{connect}, or @code{failed} for network
connections. For a network server, the status is always
@code{listen}. None of those values is possible for a real
subprocess. @xref{Process Information}.
@code{closed}, @code{connect}, @code{stop}, or @code{failed} for
network connections. For a network server, the status is always
@code{listen}. Except for @code{stop}, none of those values is
possible for a real subprocess. @xref{Process Information}.
You can stop and resume operation of a network process by calling
@code{stop-process} and @code{continue-process}. For a server

26
src/process.c
View File

@ -928,7 +928,7 @@ If PROCESS has not yet exited or died, return 0. */)
DEFUN ("process-id", Fprocess_id, Sprocess_id, 1, 1, 0,
doc: /* Return the process id of PROCESS.
This is the pid of the external process which PROCESS uses or talks to.
For a network connection, this value is nil. */)
For a network, serial, and pipe connections, this value is nil. */)
(register Lisp_Object process)
{
pid_t pid;
@ -952,8 +952,8 @@ DEFUN ("process-command", Fprocess_command, Sprocess_command, 1, 1, 0,
doc: /* Return the command that was executed to start 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.
For a network or serial process, this is nil (process is running) or t
\(process is stopped). */)
For a network or serial or pipe connection, this is nil (process is running)
or t (process is stopped). */)
(register Lisp_Object process)
{
CHECK_PROCESS (process);
@ -1181,13 +1181,13 @@ DEFUN ("process-query-on-exit-flag",
DEFUN ("process-contact", Fprocess_contact, Sprocess_contact,
1, 2, 0,
doc: /* Return the contact info of PROCESS; t for a real child.
For a network or serial connection, the value depends on the optional
KEY arg. If KEY is nil, value is a cons cell of the form (HOST
SERVICE) for a network connection or (PORT SPEED) for a serial
connection. If KEY is t, the complete contact information for the
connection is returned, else the specific value for the keyword KEY is
returned. See `make-network-process' or `make-serial-process' for a
list of keywords. */)
For a network or serial or pipe connection, the value depends on the
optional KEY arg. If KEY is nil, value is a cons cell of the form
\(HOST SERVICE) for a network connection or (PORT SPEED) for a serial
connection; it is t for a pipe connection. If KEY is t, the complete
contact information for the connection is returned, else the specific
value for the keyword KEY is returned. See `make-network-process',
\`make-serial-process', or `make-pipe-process' for the list of keywords. */)
(register Lisp_Object process, Lisp_Object key)
{
Lisp_Object contact;
@ -1254,7 +1254,7 @@ a socket connection. */)
DEFUN ("process-type", Fprocess_type, Sprocess_type, 1, 1, 0,
doc: /* Return the connection type of PROCESS.
The value is either the symbol `real', `network', or `serial'.
The value is either the symbol `real', `network', `serial', or `pipe'.
PROCESS may be a process, a buffer, the name of a process or buffer, or
nil, indicating the current buffer's process. */)
(Lisp_Object process)
@ -6156,8 +6156,8 @@ See function `interrupt-process' for more details on usage. */)
DEFUN ("stop-process", Fstop_process, Sstop_process, 0, 2, 0,
doc: /* Stop process PROCESS. May be process or name of one.
See function `interrupt-process' for more details on usage.
If PROCESS is a network or serial process, inhibit handling of incoming
traffic. */)
If PROCESS is a network or serial or pipe connection, inhibit handling
of incoming traffic. */)
(Lisp_Object process, Lisp_Object current_group)
{
if (PROCESSP (process) && (NETCONN_P (process) || SERIALCONN_P (process)