procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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
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 signals, obtain status information, receive output from the process, or
send input to it. 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 @defun processp object
This function returns @code{t} if @var{object} represents an Emacs 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 @end defun
In addition to subprocesses of the current Emacs session, you can In addition to subprocesses of the current Emacs session, you can
@ -67,7 +76,7 @@ Processes}.
@cindex process creation @cindex process creation
There are three primitives that create a new subprocess in which to run 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}). process and returns a process object (@pxref{Asynchronous Processes}).
The other two, @code{call-process} and @code{call-process-region}, The other two, @code{call-process} and @code{call-process-region},
create a synchronous process and do not return a process object 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 execute program
@cindex @env{PATH} environment variable @cindex @env{PATH} environment variable
@cindex @env{HOME} environment variable @cindex @env{HOME} environment variable
In all cases, the function's @var{program} argument specifies the In all cases, the functions specify the program to be run. An error
program to be run. An error is signaled if the file is not found or is signaled if the file is not found or cannot be executed. If the
cannot be executed. If the file name is relative, the variable file name is relative, the variable @code{exec-path} contains a list
@code{exec-path} contains a list of directories to search. Emacs of directories to search. Emacs initializes @code{exec-path} when it
initializes @code{exec-path} when it starts up, based on the value of starts up, based on the value of the environment variable @env{PATH}.
the environment variable @env{PATH}. The standard file name The standard file name constructs, @samp{~}, @samp{.}, and @samp{..},
constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as are interpreted as usual in @code{exec-path}, but environment variable
usual in @code{exec-path}, but environment variable substitutions substitutions (@samp{$HOME}, etc.)@: are not recognized; use
(@samp{$HOME}, etc.)@: are not recognized; use
@code{substitute-in-file-name} to perform them (@pxref{File Name @code{substitute-in-file-name} to perform them (@pxref{File Name
Expansion}). @code{nil} in this list refers to Expansion}). @code{nil} in this list refers to
@code{default-directory}. @code{default-directory}.
@ -106,27 +114,36 @@ system-dependent.
@end defopt @end defopt
@strong{Please note:} The argument @var{program} contains only the @strong{Please note:} The argument @var{program} contains only the
name of the program; it may not contain any command-line arguments. You name of the program file; it may not contain any command-line
must use a separate argument, @var{args}, to provide those, as arguments. You must use a separate argument, @var{args}, to provide
described below. those, as described below.
Each of the subprocess-creating functions has a @var{buffer-or-name} Each of the subprocess-creating functions has a @var{buffer-or-name}
argument that specifies where the standard output from the program will argument that specifies where the output from the program will go. It
go. It should be a buffer or a buffer name; if it is a buffer name, should be a buffer or a buffer name; if it is a buffer name, that will
that will create the buffer if it does not already exist. It can also create the buffer if it does not already exist. It can also be
be @code{nil}, which says to discard the output, unless a custom filter function @code{nil}, which says to discard the output, unless a custom filter
handles it. (@xref{Filter Functions}, and @ref{Read and Print}.) function handles it. (@xref{Filter Functions}, and @ref{Read and
Normally, you should avoid having multiple processes send output to the Print}.) Normally, you should avoid having multiple processes send
same buffer because their output would be intermixed randomly. output to the same buffer because their output would be intermixed
For synchronous processes, you can send the output to a file instead randomly. For synchronous processes, you can send the output to a
of a buffer. 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 @cindex program arguments
All three of the subprocess-creating functions have a @code{&rest} All three of the subprocess-creating functions allow to specify
argument, @var{args}. The @var{args} must all be strings, and they are command-line arguments for the process to run. For @code{call-process}
supplied to @var{program} as separate command line arguments. Wildcard and @code{call-process-region}, these come in the form of a
characters and other shell constructs have no special meanings in these @code{&rest} argument, @var{args}. For @code{make-process}, both the
strings, since the strings are passed directly to the specified program. 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 @cindex environment variables, subprocesses
The subprocess inherits its environment from Emacs, but you can 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 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 (i.e., a string), or @code{nil}, which stands for the default
directory (which is the value of @code{default-directory}). directory (which is the value of @code{default-directory}).
@xref{Locating Files, executable-find}, for the details of this search.
@cindex program directories @cindex program directories
The value of @code{exec-path} is used by @code{call-process} and 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 The following two functions are useful for combining a list of
individual command-line argument strings into a single string, and individual command-line argument strings into a single string, and
taking a string apart into a list of individual command-line taking a string apart into a list of individual command-line
arguments. These functions are mainly intended for arguments. These functions are mainly intended for converting user
converting user input in the minibuffer, a Lisp string, into a list of input in the minibuffer, a Lisp string, into a list of string
string arguments to be passed to @code{call-process} or arguments to be passed to @code{make-process}, @code{call-process} or
@code{start-process}, or for converting such lists of arguments into @code{start-process}, or for converting such lists of arguments into a
a single Lisp string to be presented in the minibuffer or echo area. single Lisp string to be presented in the minibuffer or echo area.
Note that if a shell is involved (e.g., if using Note that if a shell is involved (e.g., if using
@code{call-process-shell-command}), arguments should still be @code{call-process-shell-command}), arguments should still be
protected by @code{shell-quote-argument}; 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 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 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 the error output to a temporary file and then inserting the file into a
buffer. buffer when the subprocess finishes.
@end table @end table
If @var{display} is non-@code{nil}, then @code{call-process} redisplays 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. buffer in the normal course of events.
The remaining arguments, @var{args}, are strings that specify command 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 The value returned by @code{call-process} (unless you told it not to
wait) indicates the reason for process termination. A number gives the wait) indicates the reason for process termination. A number gives the
exit status of the subprocess; 0 means success, and any other value exit status of the subprocess; 0 means success, and any other value
means failure. If the process terminated with a signal, 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. 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 @defun call-process-shell-command command &optional infile destination display
This function executes the shell command @var{command} synchronously. This function executes the shell command @var{command} synchronously.
The arguments are handled as in @code{call-process}. An old calling The other arguments are handled as in @code{call-process}. An old
convention allowed passing any number of additional arguments after calling convention allowed passing any number of additional arguments
@var{display}, which were concatenated to @var{command}; this is still after @var{display}, which were concatenated to @var{command}; this is
supported, but strongly discouraged. still supported, but strongly discouraged.
@end defun @end defun
@defun process-file-shell-command command &optional infile destination display @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 @cindex pipe
An asynchronous process is controlled either via a @dfn{pty} An asynchronous process is controlled either via a @dfn{pty}
(pseudo-terminal) or a @dfn{pipe}. The choice of pty or pipe is made (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 when creating the process, by default based on the value of the
@code{process-connection-type} (see below). Ptys are usually variable @code{process-connection-type} (see below). If available,
preferable for processes visible to the user, as in Shell mode, ptys are usually preferable for processes visible to the user, as in
because they allow for job control (@kbd{C-c}, @kbd{C-z}, etc.)@: Shell mode, because they allow for job control (@kbd{C-c}, @kbd{C-z},
between the process and its children, whereas pipes do not. For etc.)@: between the process and its children, and because interactive
subprocesses used for internal purposes by programs, it is often programs treat ptys as terminal devices, whereas pipes don't support
better to use a pipe, because they are more efficient, and because these features. However, for subprocesses used by Lisp programs for
they are immune to stray character injections that ptys introduce for internal purposes, it is often better to use a pipe, because pipes are
large (around 500 byte) messages. Also, the total number of ptys is more efficient, and because they are immune to stray character
limited on many systems and it is good not to waste them. 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 @defun start-process name buffer-or-name program &rest args
This function creates a new asynchronous subprocess and starts the This function is a higher-level wrapper around @code{make-process},
program @var{program} running in it. It returns a process object that exposing an interface that is similar to @code{call-process}. It
stands for the new subprocess in Lisp. The argument @var{name} creates a new asynchronous subprocess and starts the specified
specifies the name for the process object; if a process with this name @var{program} running in it. It returns a process object that stands
already exists, then @var{name} is modified (by appending @samp{<1>}, for the new subprocess in Lisp. The argument @var{name} specifies the
etc.)@: to be unique. The buffer @var{buffer-or-name} is the buffer to name for the process object; as with @code{make-process}, it is
associate with the process. 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) If @var{program} is @code{nil}, Emacs opens a new pseudoterminal (pty)
and associates its input and output with @var{buffer-or-name}, without and associates its input and output with @var{buffer-or-name}, without
creating a subprocess. In that case, the remaining arguments creating a subprocess. In that case, the remaining arguments
@var{args} are ignored. @var{args} are ignored.
The remaining arguments, @var{args}, are strings that specify command The rest of @var{args} are strings that specify command line arguments
line arguments for the subprocess. for the subprocess.
In the example below, the first process is started and runs (rather, In the example below, the first process is started and runs (rather,
sleeps) for 100 seconds (the output buffer @samp{foo} is created 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. object.
The difference from @code{start-process} is that this function may 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, This handler ought to run @var{program}, perhaps on the local host,
perhaps on a remote host that corresponds to @code{default-directory}. perhaps on a remote host that corresponds to @code{default-directory}.
In the latter case, the local part of @code{default-directory} becomes In the latter case, the local part of @code{default-directory} becomes
the working directory of the process. the working directory of the process.
This function does not try to invoke file name handlers for 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 Depending on the implementation of the file handler, it might not be
possible to apply @code{process-filter} or @code{process-sentinel} to 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 @end defun
@defun start-process-shell-command name buffer-or-name command @defun start-process-shell-command name buffer-or-name command
This function is like @code{start-process}, except that it uses a shell This function is like @code{start-process}, except that it uses a
to execute the specified command. The argument @var{command} is a shell shell to execute the specified @var{command}. The argument
command name. The variable @code{shell-file-name} specifies which shell to @var{command} is a shell command string. The variable
use. @code{shell-file-name} specifies which shell to use.
The point of running a program through the shell, rather than directly 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 with @code{make-process} or @code{start-process}, is so that you can
as wildcards in the arguments. It follows that if you include any employ shell features such as wildcards in the arguments. It follows
arbitrary user-specified arguments in the command, you should quote them that if you include any arbitrary user-specified arguments in the
with @code{shell-quote-argument} first, so that any special shell command, you should quote them with @code{shell-quote-argument} first,
characters do @emph{not} have their special shell meanings. @xref{Shell so that any special shell characters do @emph{not} have their special
Arguments}. Of course, when executing commands based on user input shell meanings. @xref{Shell Arguments}. Of course, when executing
you should also consider the security implications. commands based on user input you should also consider the security
implications.
@end defun @end defun
@defun start-file-process-shell-command name buffer-or-name command @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. used, when available. Otherwise, pipes are used.
The value of @code{process-connection-type} takes effect when The value of @code{process-connection-type} takes effect when
@code{start-process} is called. So you can specify how to communicate @code{make-process} or @code{start-process} is called. So you can
with one subprocess by binding the variable around the call to specify how to communicate with one subprocess by binding the variable
@code{start-process}. 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 @smallexample
@group @group
@ -697,117 +859,6 @@ use the function @code{process-tty-name} (@pxref{Process
Information}). Information}).
@end defvar @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 @node Deleting Processes
@section Deleting Processes @section Deleting Processes
@cindex deleting processes @cindex deleting processes
@ -837,14 +888,19 @@ they exit.
@defun delete-process process @defun delete-process process
This function deletes a process, killing it with a @code{SIGKILL} This function deletes a process, killing it with a @code{SIGKILL}
signal. The argument may be a process, the name of a process, a signal if the process was running a program. The argument may be a
buffer, or the name of a buffer. (A buffer or buffer-name stands for process, the name of a process, a buffer, or the name of a buffer. (A
the process that @code{get-buffer-process} returns.) Calling buffer or buffer-name stands for the process that
@code{delete-process} on a running process terminates it, updates the @code{get-buffer-process} returns.) Calling @code{delete-process} on
process status, and runs the sentinel immediately. If the a running process terminates it, updates the process status, and runs
process has already terminated, calling @code{delete-process} has no the sentinel immediately. If the process has already terminated,
effect on its status, or on the running of its sentinel (which will calling @code{delete-process} has no effect on its status, or on the
happen sooner or later). 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 @smallexample
@group @group
@ -886,7 +942,8 @@ This function returns a list of all processes that have not been deleted.
@defun get-process name @defun get-process name
This function returns the process named @var{name} (a string), or 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 @smallexample
@group @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 This function returns the command that was executed to start
@var{process}. This is a list of strings, the first string being the @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 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 @smallexample
@group @group
@ -911,18 +970,19 @@ were given to the program.
@end defun @end defun
@defun process-contact process &optional key @defun process-contact process &optional key
This function returns information about how a network, a serial, or a
This function returns information about how a network or serial pipe connection was set up. When @var{key} is @code{nil}, it returns
process was set up. When @var{key} is @code{nil}, it returns @code{(@var{hostname} @var{service})} for a network connection,
@code{(@var{hostname} @var{service})} for a network process, and @code{(@var{port} @var{speed})} for a serial connection, and @code{t}
@code{(@var{port} @var{speed})} for a serial process. for a pipe connection. For an ordinary child process, this function
For an ordinary child process, this function always returns @code{t}. 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 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 for the connection, server, serial port, or pipe; that is, the list of
keywords and values specified in @code{make-network-process} or keywords and values specified in @code{make-network-process},
@code{make-serial-process}, except that some of the values represent @code{make-serial-process}, or @code{make-pipe-process}, except that
the current status instead of what you specified. some of the values represent the current status instead of what you
specified.
For a network process, the values include (see For a network process, the values include (see
@code{make-network-process} for a complete list): @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 @code{:local} and @code{:remote} are included even if they were not
specified explicitly in @code{make-network-process}. specified explicitly in @code{make-network-process}.
For a serial process, see @code{make-serial-process} and For a serial connection, see @code{make-serial-process} and
@code{serial-process-configure} for a list of keys. @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 If @var{key} is a keyword, the function returns the value corresponding
to that keyword. to that keyword.
@ -956,10 +1017,12 @@ to that keyword.
@defun process-id process @defun process-id process
This function returns the @acronym{PID} of @var{process}. This is an This function returns the @acronym{PID} of @var{process}. This is an
integer that distinguishes the process @var{process} from all other integral number that distinguishes the process @var{process} from all
processes running on the same computer at the current time. The 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 @acronym{PID} of a process is chosen by the operating system kernel
process is started and remains constant as long as the process exists. 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 @end defun
@defun process-name process @defun process-name process
@ -983,11 +1046,11 @@ for a process that has exited.
@item signal @item signal
for a process that has received a fatal signal. for a process that has received a fatal signal.
@item open @item open
for a network connection that is open. for a network, serial, or pipe connection that is open.
@item closed @item closed
for a network connection that is closed. Once a connection for a network, serial, or pipe connection that is closed. Once a
is closed, you cannot reopen it, though you might be able to open connection is closed, you cannot reopen it, though you might be able
a new connection to the same place. to open a new connection to the same place.
@item connect @item connect
for a non-blocking connection that is waiting to complete. for a non-blocking connection that is waiting to complete.
@item failed @item failed
@ -1005,9 +1068,11 @@ if @var{process-name} is not the name of an existing process.
@end group @end group
@end smallexample @end smallexample
For a network connection, @code{process-status} returns one of the symbols For a network, serial, or pipe connection, @code{process-status}
@code{open} or @code{closed}. The latter means that the other side returns one of the symbols @code{open}, @code{stop}, or @code{closed}.
closed the connection, or Emacs did @code{delete-process}. 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 @end defun
@defun process-live-p process @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 @defun process-type process
This function returns the symbol @code{network} for a network This function returns the symbol @code{network} for a network
connection or server, @code{serial} for a serial port connection, or connection or server, @code{serial} for a serial port connection,
@code{real} for a real subprocess. @code{pipe} for a pipe connection, or @code{real} for a subprocess
created for running a program.
@end defun @end defun
@defun process-exit-status process @defun process-exit-status process
This function returns the exit status of @var{process} or the signal This function returns the exit status of @var{process} or the signal
number that killed it. (Use the result of @code{process-status} to number that killed it. (Use the result of @code{process-status} to
determine which of those it is.) If @var{process} has not yet 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 @end defun
@defun process-tty-name process @defun process-tty-name process
This function returns the terminal name that @var{process} is using for This function returns the terminal name that @var{process} is using for
its communication with Emacs---or @code{nil} if it is using pipes 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 @ref{Asynchronous Processes}). If @var{process} represents a program
running on a remote host, the terminal name used by that program on 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 @end defun
@defun process-coding-system process @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 Asynchronous subprocesses receive input when it is sent to them by
Emacs, which is done with the functions in this section. You must 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 specify the process to send input to, and the input data to send. If
data appears on the standard input of the subprocess. 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? @c FIXME which?
Some operating systems have limited space for buffered input in a Some operating systems have limited space for buffered input in a
@ -1143,12 +1215,14 @@ The function returns @var{process}.
@end defun @end defun
@defun process-running-child-p &optional process @defun process-running-child-p &optional process
This function will tell you whether a @var{process} has given control This function will tell you whether a @var{process}, which must not be
of its terminal to its own child process. If this is true, the a connection but a real subprocess, has given control of its terminal
function returns the numeric ID of the foreground process group of to a child process of its own. If this is true, the function returns
@var{process}; it returns @code{nil} if Emacs can be certain that this the numeric ID of the foreground process group of @var{process}; it
is not so. The value is @code{t} if Emacs cannot tell whether this is returns @code{nil} if Emacs can be certain that this is not so. The
true. 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 @end defun
@node Signals to Processes @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 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 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 a process through @code{get-buffer-process}. @code{nil}
stands for the process associated with the current buffer. An error stands for the process associated with the current buffer. Except
is signaled if @var{process} does not identify a process. 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 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 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 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 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 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 subjob. If @var{current-group} is @code{nil}, the signal is
the immediate subprocess of Emacs. If the subprocess is a job-control sent to the process group of the immediate subprocess of Emacs. If
shell, this is the shell itself. 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 The flag @var{current-group} has no effect when a pipe is used to
communicate with the subprocess, because the operating system does not communicate with the subprocess, because the operating system does not
@ -1222,21 +1301,29 @@ Emacs.
@end defun @end defun
@defun stop-process &optional process current-group @defun stop-process &optional process current-group
This function stops the process @var{process} by sending the This function stops the specified @var{process}. If it is a real
signal @code{SIGTSTP}. Use @code{continue-process} to resume its 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. execution.
Outside of Emacs, on systems with job control, the stop character Outside of Emacs, on systems with job control, the stop character
(usually @kbd{C-z}) normally sends this signal. When (usually @kbd{C-z}) normally sends the @code{SIGTSTP} signal to a
@var{current-group} is non-@code{nil}, you can think of this function as subprocess. When @var{current-group} is non-@code{nil}, you can think
typing @kbd{C-z} on the terminal Emacs uses to communicate with the of this function as typing @kbd{C-z} on the terminal Emacs uses to
subprocess. communicate with the subprocess.
@end defun @end defun
@defun continue-process &optional process current-group @defun continue-process &optional process current-group
This function resumes execution of the process @var{process} by sending This function resumes execution of the process @var{process}. If it
it the signal @code{SIGCONT}. This presumes that @var{process} was is a real subprocess running a program, it sends the signal
stopped previously. @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 @end defun
@deffn Command signal-process process signal @deffn Command signal-process process signal
@ -1254,12 +1341,28 @@ children of Emacs. @xref{System Processes}.
@cindex process output @cindex process output
@cindex output from processes @cindex output from processes
The output that a subprocess writes to its standard output stream The output that an asynchronous subprocess writes to its standard
is passed to a function called the @dfn{filter function}. The default output stream is passed to a function called the @dfn{filter
filter function simply inserts the output into a buffer, which is function}. The default filter function simply inserts the output into
called the associated buffer of the process (@pxref{Process a buffer, which is called the associated buffer of the process
Buffers}). If the process has no buffer then the default filter (@pxref{Process Buffers}). If the process has no buffer then the
discards the output. 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, When a subprocess terminates, Emacs reads any pending output,
then stops reading output from that subprocess. Therefore, if the 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. Emacs tries to read it.
@end defvar @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 @menu
* Process Buffers:: By default, output is put in a buffer. * Process Buffers:: By default, output is put in a buffer.
* Filter Functions:: Filter functions accept output from the process. * 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}). @code{kill-buffer-query-functions} (@pxref{Killing Buffers}).
@defun process-buffer process @defun process-buffer process
This function returns the associated buffer of the process This function returns the associated buffer of the specified
@var{process}. @var{process}.
@smallexample @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 that process is passed to the filter. The default filter simply
outputs directly to the process buffer. 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 The filter function can only be called when Emacs is waiting for
something, because process output arrives only at such times. Emacs something, because process output arrives only at such times. Emacs
waits when reading terminal input (see the function 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 caught automatically, so that it doesn't stop the execution of whatever
program was running when the filter function was started. However, if program was running when the filter function was started. However, if
@code{debug-on-error} is non-@code{nil}, errors are not caught. @code{debug-on-error} is non-@code{nil}, errors are not caught.
This makes it possible to use the Lisp debugger to debug the This makes it possible to use the Lisp debugger to debug filter
filter function. @xref{Debugger}. functions. @xref{Debugger}.
Many filter functions sometimes (or always) insert the output in the Many filter functions sometimes (or always) insert the output in the
process's buffer, mimicking the actions of the default filter. 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 @end smallexample
To force point to the end of the new output, no matter where it was To force point to the end of the new output, no matter where it was
previously, eliminate the variable @code{moving} and call previously, eliminate the variable @code{moving} from the example and
@code{goto-char} unconditionally. call @code{goto-char} unconditionally.
@ignore @ignore
In earlier Emacs versions, every filter function that did regular In earlier Emacs versions, every filter function that did regular
@ -1835,10 +1936,11 @@ was not.
@node Query Before Exit @node Query Before Exit
@section Querying Before Exit @section Querying Before Exit
When Emacs exits, it terminates all its subprocesses by sending them When Emacs exits, it terminates all its subprocesses. For
the @code{SIGHUP} signal. Because subprocesses may be doing subprocesses that run a program, it sends them the @code{SIGHUP}
valuable work, Emacs normally asks the user to confirm that it is ok signal; connections are simply closed. Because subprocesses may be
to terminate them. Each process has a query flag, which, if 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 non-@code{nil}, says that Emacs should ask for confirmation before
exiting and thus killing that process. The default for the query flag exiting and thus killing that process. The default for the query flag
is @code{t}, meaning @emph{do} query. 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 To distinguish the different types of processes, the
@code{process-type} function returns the symbol @code{network} for a @code{process-type} function returns the symbol @code{network} for a
network connection or server, @code{serial} for a serial port 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}, The @code{process-status} function returns @code{open},
@code{closed}, @code{connect}, or @code{failed} for network @code{closed}, @code{connect}, @code{stop}, or @code{failed} for
connections. For a network server, the status is always network connections. For a network server, the status is always
@code{listen}. None of those values is possible for a real @code{listen}. Except for @code{stop}, none of those values is
subprocess. @xref{Process Information}. possible for a real subprocess. @xref{Process Information}.
You can stop and resume operation of a network process by calling You can stop and resume operation of a network process by calling
@code{stop-process} and @code{continue-process}. For a server @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, DEFUN ("process-id", Fprocess_id, Sprocess_id, 1, 1, 0,
doc: /* Return the process id of PROCESS. doc: /* Return the process id of PROCESS.
This is the pid of the external process which PROCESS uses or talks to. 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) (register Lisp_Object process)
{ {
pid_t pid; 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. doc: /* Return the command that was executed to start PROCESS.
This is a list of strings, the first string being the program executed 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. 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 For a network or serial or pipe connection, this is nil (process is running)
\(process is stopped). */) or t (process is stopped). */)
(register Lisp_Object process) (register Lisp_Object process)
{ {
CHECK_PROCESS (process); CHECK_PROCESS (process);
@ -1181,13 +1181,13 @@ DEFUN ("process-query-on-exit-flag",
DEFUN ("process-contact", Fprocess_contact, Sprocess_contact, DEFUN ("process-contact", Fprocess_contact, Sprocess_contact,
1, 2, 0, 1, 2, 0,
doc: /* Return the contact info of PROCESS; t for a real child. doc: /* Return the contact info of PROCESS; t for a real child.
For a network or serial connection, the value depends on the optional For a network or serial or pipe connection, the value depends on the
KEY arg. If KEY is nil, value is a cons cell of the form (HOST optional KEY arg. If KEY is nil, value is a cons cell of the form
SERVICE) for a network connection or (PORT SPEED) for a serial \(HOST SERVICE) for a network connection or (PORT SPEED) for a serial
connection. If KEY is t, the complete contact information for the connection; it is t for a pipe connection. If KEY is t, the complete
connection is returned, else the specific value for the keyword KEY is contact information for the connection is returned, else the specific
returned. See `make-network-process' or `make-serial-process' for a value for the keyword KEY is returned. See `make-network-process',
list of keywords. */) \`make-serial-process', or `make-pipe-process' for the list of keywords. */)
(register Lisp_Object process, Lisp_Object key) (register Lisp_Object process, Lisp_Object key)
{ {
Lisp_Object contact; Lisp_Object contact;
@ -1254,7 +1254,7 @@ a socket connection. */)
DEFUN ("process-type", Fprocess_type, Sprocess_type, 1, 1, 0, DEFUN ("process-type", Fprocess_type, Sprocess_type, 1, 1, 0,
doc: /* Return the connection type of PROCESS. 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 PROCESS may be a process, a buffer, the name of a process or buffer, or
nil, indicating the current buffer's process. */) nil, indicating the current buffer's process. */)
(Lisp_Object 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, DEFUN ("stop-process", Fstop_process, Sstop_process, 0, 2, 0,
doc: /* Stop process PROCESS. May be process or name of one. doc: /* Stop process PROCESS. May be process or name of one.
See function `interrupt-process' for more details on usage. See function `interrupt-process' for more details on usage.
If PROCESS is a network or serial process, inhibit handling of incoming If PROCESS is a network or serial or pipe connection, inhibit handling
traffic. */) of incoming traffic. */)
(Lisp_Object process, Lisp_Object current_group) (Lisp_Object process, Lisp_Object current_group)
{ {
if (PROCESSP (process) && (NETCONN_P (process) || SERIALCONN_P (process) if (PROCESSP (process) && (NETCONN_P (process) || SERIALCONN_P (process)