Commit 88a50525 authored by Eli Zaretskii's avatar Eli Zaretskii
Browse files

Improve and clarify documentation of subprocesses

* 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.
parent 89eb09f6
......@@ -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
</