@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/processes
system, much like text written into a file. @xref{Coding Systems}.
@defun call-process program &optional infile destination display &rest args
-This function calls @var{program} in a separate process and waits for
-it to finish.
+This function calls @var{program} and waits for it to finish.
-The standard input for the process comes from file @var{infile} if
+The standard input for the new process comes from file @var{infile} if
@var{infile} is not @code{nil}, and from the null device otherwise.
The argument @var{destination} says where to put the process output.
Here are the possibilities:
MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
work there.
+@item @code{(:file @var{file-name})}
+Send the output to the file name specified, overwriting it if it
+already exists.
+
@item @code{(@var{real-destination} @var{error-destination})}
Keep the standard output stream separate from the standard error stream;
deal with the ordinary output as specified by @var{real-destination},
Per default, this variable is always set to @code{t}, meaning that a
call of @code{process-file} could potentially change any file on a
remote host. When set to @code{nil}, a file handler could optimize
-its behaviour with respect to remote file attributes caching.
+its behavior with respect to remote file attributes caching.
This variable should never be changed by @code{setq}. Instead of, it
shall be set only by let-binding.
@end defun
@defun call-process-shell-command command &optional infile destination display &rest args
-This function executes the shell command @var{command} synchronously
-in a separate process. The final arguments @var{args} are additional
-arguments to add at the end of @var{command}. The other arguments
-are handled as in @code{call-process}.
+This function executes the shell command @var{command} synchronously.
+The final arguments @var{args} are additional arguments to add at the
+end of @var{command}. The other arguments are handled as in
+@code{call-process}.
@end defun
@defun process-file-shell-command command &optional infile destination display &rest args
@end defun
@defun process-lines program &rest args
-This function runs @var{program} in a separate process, waits for it
-to finish, and returns its output as a list of strings. Each string
-in the list holds a single line of text output by the program; the
-end-of-line characters are stripped from each line. The arguments
-beyond @var{program}, @var{args}, are strings that specify
-command-line arguments with which to run the program.
+This function runs @var{program}, waits for it to finish, and returns
+its output as a list of strings. Each string in the list holds a
+single line of text output by the program; the end-of-line characters
+are stripped from each line. The arguments beyond @var{program},
+@var{args}, are strings that specify command-line arguments with which
+to run the program.
If @var{program} exits with a non-zero exit status, this function
signals an error.
it finally deletes any process whose status was @samp{Exited} or
@samp{Signaled}. It returns @code{nil}.
+The processes are shown in a buffer named @samp{*Process List*}, whose
+major mode is named Process Menu mode.
+
If @var{query-only} is non-@code{nil} then it lists only processes
whose query flag is non-@code{nil}. @xref{Query Before Exit}.
@end deffn
closed the connection, or Emacs did @code{delete-process}.
@end defun
+@defun process-live-p process
+This function returns nin-@code{nil} if @var{process} is alive. A
+process is considered alive if its status is @code{run}, @code{open},
+@code{listen}, @code{connect} or @code{stop}.
+@end defun
+
@defun process-type process
This function returns the symbol @code{network} for a network
connection or server, @code{serial} for a serial port connection, or
The number of threads in the process.
@item start
-The time the process was started, in the @w{@code{(@var{high}
-@var{low} @var{microsec})}} format used by @code{current-time} and
-@code{file-attributes}.
+The time when the process was started, in the same
+@w{@code{(@var{high} @var{low} @var{microsec})}} format used by
+@code{current-time} and @code{file-attributes}.
@item etime
The time elapsed since the process started, in the @w{@code{(@var{high}
@code{process-command} to determine whether a network connection or
server is stopped; a non-@code{nil} value means yes.
-@defun open-network-stream name buffer-or-name host service
-This function opens a TCP connection, and returns a process object
-that represents the connection.
+@cindex network connection, encrypted
+@cindex encrypted network connections
+@cindex TLS network connections
+@cindex STARTTLS network connections
+@defun open-network-stream name buffer-or-name host service &rest parameters
+This function opens a TCP connection, with optional encryption, and
+returns a process object that represents the connection.
The @var{name} argument specifies the name for the process object. It
is modified as necessary to make it unique.
The arguments @var{host} and @var{service} specify where to connect to;
@var{host} is the host name (a string), and @var{service} is the name of
a defined network service (a string) or a port number (an integer).
+
+@c FIXME? Is this too lengthy for the printed manual?
+The remaining arguments @var{parameters} are keyword/argument pairs
+that are mainly relevant to encrypted connections:
+
+@table @code
+
+@item :nowait @var{boolean}
+If non-@code{nil}, try to make an asynchronous connection.
+
+@item :type @var{type}
+The type of connection. Options are:
+
+@table @code
+@item plain
+An ordinary, unencrypted connection.
+@item tls
+@itemx ssl
+A TLS (``Transport Layer Security'') connection.
+@item nil
+@itemx network
+Start with a plain connection, and if parameters @samp{:success}
+and @samp{:capability-command} are supplied, try to upgrade to an encrypted
+connection via STARTTLS. If that fails, retain the unencrypted connection.
+@item starttls
+As for @code{nil}, but if STARTTLS fails drop the connection.
+@item shell
+A shell connection.
+@end table
+
+@item :always-query-capabilities @var{boolean}
+If non-@code{nil}, always ask for the server's capabilities, even when
+doing a @samp{plain} connection.
+
+@item :capability-command @var{capability-command}
+Command string to query the host capabilities.
+
+@item :end-of-command @var{regexp}
+@itemx :end-of-capability @var{regexp}
+Regular expression matching the end of a command, or the end of the
+command @var{capability-command}. The latter defaults to the former.
+
+@item :starttls-function @var{function}
+Function of one argument (the response to @var{capability-command}),
+which returns either @code{nil}, or the command to activate STARTTLS
+if supported.
+
+@item :success @var{regexp}
+Regular expression matching a successful STARTTLS negotiation.
+
+@item :use-starttls-if-possible @var{boolean}
+If non-@code{nil}, do opportunistic STARTTLS upgrades even if Emacs
+doesn't have built-in TLS support.
+
+@item :client-certificate @var{list-or-t}
+Either a list of the form @code{(@var{key-file} @var{cert-file})},
+naming the certificate key file and certificate file itself, or
+@code{t}, meaning to query @code{auth-source} for this information
+(@pxref{Top,,auth-source, auth, Emacs auth-source Library}).
+Only used for TLS or STARTTLS.
+
+@item :return-list @var{cons-or-nil}
+The return value of this function. If omitted or @code{nil}, return a
+process object. Otherwise, a cons of the form @code{(@var{process-object}
+. @var{plist})}, where @var{plist} has keywords:
+
+@table @code
+@item :greeting @var{string-or-nil}
+If non-@code{nil}, the greeting string returned by the host.
+@item :capabilities @var{string-or-nil}
+If non-@code{nil}, the host's capability string.
+@item :type @var{symbol}
+The connection type: @samp{plain} or @samp{tls}.
+@end table
+
+@end table
+
@end defun
@node Network Servers
buffer for the purpose. The buffer name is the server's buffer name
or process name, concatenated with the client identification string.
-The server's process buffer value is never used directly by Emacs, but
-it is passed to the log function, which can log connections by
-inserting text there.
+The server's process buffer value is never used directly, but the log
+function can retrieve it and use it to log connections by inserting
+text there.
@item
The communication type and the process filter and sentinel are
@itemx :parity
@itemx :stopbits
@itemx :flowcontrol
-These arguments are handled by @code{serial-process-configure}, which
-is called by @code{make-serial-process}.
+These are handled by @code{serial-process-configure}, which is called
+by @code{make-serial-process}.
@end table
The original argument list, possibly modified by later configuration,
is available via the function @code{process-contact}.
-Examples:
+Here is an example:
@example
(make-serial-process :port "/dev/ttyS0" :speed 9600)
-
-(make-serial-process :port "COM1" :speed 115200 :stopbits 2)
-
-(make-serial-process :port "\\\\.\\COM13" :speed 1200
- :bytesize 7 :parity 'odd)
-
-(make-serial-process :port "/dev/tty.BlueConsole-SPP-1"
- :speed nil)
@end example
@end defun
flow control.
@end table
-@code{serial-process-configure} is called by @code{make-serial-process} for the
-initial configuration of the serial port.
-
-Examples:
-
-@example
-(serial-process-configure :process "/dev/ttyS0" :speed 1200)
-
-(serial-process-configure :buffer "COM1" :stopbits 1
- :parity 'odd :flowcontrol 'hw)
-
-(serial-process-configure :port "\\\\.\\COM13" :bytesize 7)
-@end example
+@code{serial-process-configure} is called by
+@code{make-serial-process} for the initial configuration of the serial
+port.
@end defun
@node Byte Packing