@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Processes
Precisely what this function does depends on your operating system. The
function is designed to work with the syntax of your system's standard
shell; if you use an unusual shell, you will need to redefine this
-function.
+function. @xref{Security Considerations}.
@example
;; @r{This example shows the behavior on GNU and Unix systems.}
Insert the output in that buffer, before point. This includes both the
standard output stream and the standard error stream of the process.
-@item a string
+@item a buffer name (a string)
Insert the output in a buffer with that name, before point.
@item @code{t}
stopped state.
@item :filter @var{filter}
-Initialize the process filter to @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}.
+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.
stopped state.
@item :filter @var{filter}
-Initialize the process filter to @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}.
+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
@item :buffer
The associated value is the process buffer.
@item :filter
-The associated value is the process filter function.
+The associated value is the process filter function. @xref{Filter
+Functions}.
@item :sentinel
-The associated value is the process sentinel function.
+The associated value is the process sentinel function. @xref{Sentinels}.
@item :remote
In a connection, the address in internal format of the remote peer.
@item :local
@cindex filter function
@cindex process filter
+@cindex default filter function of a process
A process @dfn{filter function} is a function that receives the
standard output from the associated process. @emph{All} output from
that process is passed to the filter. The default filter simply
arguments: the process for which the event occurred, and a string
describing the type of event.
+@cindex default sentinel function of a process
+ If no sentinel function was specified for a process, it will use the
+default sentinel function, which inserts a message in the process's
+buffer with the process name and the string describing the event.
+
The string describing the event looks like one of the following:
-@c FIXME? Also "killed\n" - see example below?
@itemize @bullet
@item
@code{"finished\n"}.
@item
-@code{"exited abnormally with code @var{exitcode}\n"}.
+@code{"deleted\n"}.
+
+@item
+@code{"exited abnormally with code @var{exitcode} (core dumped)\n"}.
+The ``core dumped'' part is optional, and only appears if the process
+dumped core.
+
+@item
+@code{"failed with code @var{fail-code}\n"}.
+
+@item
+@code{"@var{signal-description} (core dumped)\n"}. The
+@var{signal-description} is a system-dependent textual description of
+a signal, e.g., @code{"killed"} for @code{SIGKILL}. The ``core
+dumped'' part is optional, and only appears if the process dumped
+core.
+
+@item
+@code{"open from @var{host-name}\n"}.
@item
-@code{"@var{name-of-signal}\n"}.
+@code{"open\n"}.
@item
-@code{"@var{name-of-signal} (core dumped)\n"}.
+@code{"connection broken by remote peer\n"}.
@end itemize
A sentinel runs only while Emacs is waiting (e.g., for terminal
@item (:type datagram)
Non-@code{nil} if datagrams are supported.
@item (:family local)
-Non-@code{nil} if local (a.k.a.@: UNIX domain) sockets are supported.
+Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported.
@item (:family ipv6)
Non-@code{nil} if IPv6 is supported.
@item (:service t)
A field's @dfn{type} describes the size (in bytes) of the object
that the field represents and, in the case of multibyte fields, how
the bytes are ordered within the field. The two possible orderings
-are big endian (also known as network byte ordering) and
-little endian. For instance, the number @code{#x23cd} (decimal
+are @dfn{big endian} (also known as ``network byte ordering'') and
+@dfn{little endian}. For instance, the number @code{#x23cd} (decimal
9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
and in little endian, @code{#xcd} @code{#x23}. Here are the possible
type values: