@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 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/processes
@node Processes, Display, Abbrevs, Top
* Sentinels:: Sentinels run when process run-status changes.
* Query Before Exit:: Whether to query if exiting will kill a process.
* System Processes:: Accessing other processes running on your system.
-* Transaction Queues:: Transaction-based communication with subprocesses.
+* Transaction Queues:: Transaction-based communication with subprocesses.
* Network:: Opening network connections.
* Network Servers:: Network servers let Emacs accept net connections.
* Datagrams:: UDP network connections.
* Low-Level Network:: Lower-level but more general function
to create connections and servers.
-* Misc Network:: Additional relevant functions for network connections.
+* Misc Network:: Additional relevant functions for net connections.
* Serial Ports:: Communicating with serial ports.
* Byte Packing:: Using bindat to pack and unpack binary data.
@end menu
@end defun
@cindex quoting and unquoting shell command line
- The following two functions help creating shell commands from
-individual argument strings and taking shell command lines apart into
-individual arguments.
+ The following two functions are useful for creating shell commands
+from individual argument strings, and taking shell command lines apart
+into individual arguments.
@defun split-string-and-unquote string &optional separators
This function splits @var{string} into substrings at matches for the
regular expression @var{separators}, like @code{split-string} does
-(@pxref{Creating Strings}), but it additionally removes quoting from
-the substrings. It then makes a list of the substrings and returns
-it.
+(@pxref{Creating Strings}); in addition, it removes quoting from the
+substrings. It then makes a list of the substrings and returns it.
-If @var{separators} is omitted or nil, it defaults to @code{"\\s-+"},
-which is a regular expression that matches one or more characters with
-whitespace syntax (@pxref{Syntax Class Table}).
+If @var{separators} is omitted or @code{nil}, it defaults to
+@code{"\\s-+"}, which is a regular expression that matches one or more
+characters with whitespace syntax (@pxref{Syntax Class Table}).
-The quoting this function supports is of 2 styles: by enclosing a
-whole string in double quotes @code{"@dots{}"}, or by quoting
-individual characters with a backslash escape @samp{\}. The latter is
-also used in Lisp strings, so this function can handle those as well.
+This function performs two types of quoting: enclosing a whole string
+in double quotes @code{"@dots{}"}, and quoting individual characters
+with a backslash escape @samp{\}. The latter is also used in Lisp
+strings, so this function can handle those as well.
@end defun
@defun combine-and-quote-strings list-of-strings &optional separator
This function concatenates @var{list-of-strings} into a single string,
-quoting each string in the list that needs quoting as it goes. It
-also sticks the @var{separator} string in between each pair of strings
-in the result, and returns that result. If @var{separator} is omitted
-or @code{nil}, it defaults to a blank @code{" "}.
+quoting each string as necessary. It also sticks the @var{separator}
+string between each pair of strings; if @var{separator} is omitted or
+@code{nil}, it defaults to @code{" "}. The return value is the
+resulting string.
The strings in @var{list-of-strings} that need quoting are those that
include @var{separator} as their substring. Quoting a string encloses
file names.
@end defun
+@defvar process-file-side-effects
+This variable indicates, whether a call of @code{process-file} changes
+remote files.
+
+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.
+
+This variable should never be changed by @code{setq}. Instead of, it
+shall be set only by let-binding.
+@end defvar
+
@defun call-process-region start end program &optional delete destination display &rest args
This function sends the text from @var{start} to @var{end} as
standard input to a process running @var{program}. It deletes the text
does nothing and returns @code{nil}.
@end defun
-@defun start-process-shell-command name buffer-or-name command &rest command-args
+@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, and @var{command-args} are the arguments for the shell
-command. The variable @code{shell-file-name} specifies which shell to
+command name. The variable @code{shell-file-name} specifies which shell to
use.
The point of running a program through the shell, rather than directly
Arguments}.
@end defun
-@defun start-file-process-shell-command name buffer-or-name command &rest command-args
+@defun start-file-process-shell-command name buffer-or-name command
This function is like @code{start-process-shell-command}, but uses
@code{start-file-process} internally. By this, @var{command} can be
executed also on remote hosts, depending on @code{default-directory}.
@defun process-status process-name
This function returns the status of @var{process-name} as a symbol.
-The argument @var{process-name} must be a process, a buffer, a
-process name (string) or a buffer name (string).
+The argument @var{process-name} must be a process, a buffer, or a
+process name (a string).
The possible values for an actual subprocess are:
@smallexample
@group
-(process-status "shell")
- @result{} run
-@end group
-@group
(process-status (get-buffer "*shell*"))
@result{} run
@end group
This function returns the terminal name that @var{process} is using for
its communication with Emacs---or @code{nil} if it is using pipes
instead of a terminal (see @code{process-connection-type} in
-@ref{Asynchronous Processes}).
+@ref{Asynchronous Processes}). If @var{process} represents a program
+running on a remote host, the terminal name used by that program on
+the remote host is provided as process property @code{remote-tty}.
@end defun
@defun process-coding-system process
@end smallexample
@end defun
-@defun process-running-child-p process
-This function will tell you whether a subprocess has given control of
+@defun process-running-child-p &optional process
+This function will tell you whether a @var{process} has given control of
its terminal to its own child process. The value is @code{t} if this is
true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
that this is not so.
stopped previously.
@end defun
-@c Emacs 19 feature
@defun signal-process process signal
This function sends a signal to process @var{process}. The argument
@var{signal} specifies which signal to send; it should be an integer.
updated to point to the end of the text just inserted. Usually, but not
always, the @code{process-mark} is at the end of the buffer.
+@findex process-kill-buffer-query-function
+ Killing the associated buffer of a process also kills the process.
+Emacs asks for confirmation first, if the process's
+@code{process-query-on-exit-flag} is non-@code{nil} (@pxref{Query
+Before Exit}). This confirmation is done by the function
+@code{process-kill-buffer-query-function}, which is run from
+@code{kill-buffer-query-functions} (@pxref{Killing Buffers}).
+
@defun process-buffer process
This function returns the associated buffer of the process
@var{process}.
filter. Such filter functions need to use @code{set-buffer} in order to
be sure to insert in that buffer. To avoid setting the current buffer
semipermanently, these filter functions must save and restore the
-current buffer. They should also update the process marker, and in some
-cases update the value of point. Here is how to do these things:
+current buffer. They should also check whether the buffer is still
+alive, update the process marker, and in some cases update the value
+of point. Here is how to do these things:
@smallexample
@group
(defun ordinary-insertion-filter (proc string)
- (with-current-buffer (process-buffer proc)
- (let ((moving (= (point) (process-mark proc))))
+ (when (buffer-live-p (process-buffer proc))
+ (with-current-buffer (process-buffer proc)
+ (let ((moving (= (point) (process-mark proc))))
@end group
@group
- (save-excursion
- ;; @r{Insert the text, advancing the process marker.}
- (goto-char (process-mark proc))
- (insert string)
- (set-marker (process-mark proc) (point)))
- (if moving (goto-char (process-mark proc))))))
+ (save-excursion
+ ;; @r{Insert the text, advancing the process marker.}
+ (goto-char (process-mark proc))
+ (insert string)
+ (set-marker (process-mark proc) (point)))
+ (if moving (goto-char (process-mark proc)))))))
@end group
@end smallexample
match data. Now Emacs does this automatically for filter functions;
they never need to do it explicitly. @xref{Match Data}.
- A filter function that writes the output into the buffer of the
-process should check whether the buffer is still alive. If it tries to
-insert into a dead buffer, it will get an error. The expression
-@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
-if the buffer is dead.
-
The output to the function may come in chunks of any size. A program
that produces the same output twice in a row may send it as one batch of
200 characters one time, and five batches of 40 characters the next. If
the filter looks for certain text strings in the subprocess output, make
sure to handle the case where one of these strings is split across two
-or more batches of output.
+or more batches of output; one way to do this is to insert the
+received text into a temporary buffer, which can then be searched.
@defun set-process-filter process filter
This function gives @var{process} the filter function @var{filter}. If
system to use (@pxref{Process Information}). Otherwise, the coding
system comes from @code{coding-system-for-read}, if that is
non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
-Coding Systems}).
+Coding Systems}). If the text output by a process contains null
+bytes, Emacs by default uses @code{no-conversion} for it; see
+@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
+control this behavior.
@strong{Warning:} Coding systems such as @code{undecided} which
determine the coding system from the data do not work entirely
time.
@end defun
-@defun system-process-attributes pid
+@defun process-attributes pid
This function returns an alist of attributes for the process specified
by its process ID @var{pid}. Each association in the alist is of the
form @code{(@var{key} . @var{value})}, where @var{key} designates the
processing system calls. The corresponding @var{value} is in the same
format as for @code{utime}.
+@item time
+The sum of @code{utime} and @code{stime}. The corresponding
+@var{value} is in the same format as for @code{utime}.
+
@item cutime
@itemx cstime
-Like @code{utime} and @code{stime}, but includes the times of all the
-child processes of the given process.
+@itemx ctime
+Like @code{utime}, @code{stime}, and @code{time}, but include the
+times of all the child processes of the given process.
@item pri
The numerical priority of the process.
text at the end of the entire answer, but nothing before; that's how
@code{tq-enqueue} determines where the answer ends.
-If the argument @var{delay-question} is non-nil, delay sending this
-question until the process has finished replying to any previous
+If the argument @var{delay-question} is non-@code{nil}, delay sending
+this question until the process has finished replying to any previous
questions. This produces more reliable results with some processes.
The return value of @code{tq-enqueue} itself is not meaningful.
@item :type @var{type}
Specify the communication type. A value of @code{nil} specifies a
stream connection (the default); @code{datagram} specifies a datagram
-connection. Both connections and servers can be of either type.
+connection; @code{seqpacket} specifies a ``sequenced packet stream''
+connection. Both connections and servers can be of these types.
@item :server @var{server-flag}
If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
@item :filter @var{filter}
Initialize the process filter to @var{filter}.
-@item :filter-multibyte @var{bool}
-If @var{bool} is non-@code{nil}, strings given to the process filter
-are multibyte, otherwise they are unibyte. If you don't specify this
-keyword at all, the default is that the strings are multibyte if
-@code{default-enable-multibyte-characters} is non-@code{nil}.
-
@item :sentinel @var{sentinel}
Initialize the process sentinel to @var{sentinel}.
that port.
@end table
-@defun set-network-process-option process option value
+@defun set-network-process-option process option value &optional no-error
This function sets or modifies a network option for network process
@var{process}. See @code{make-network-process} for details of options
-@var{option} and their corresponding values @var{value}.
+@var{option} and their corresponding values @var{value}. If
+@var{no-error} is non-@code{nil}, this function returns @code{nil}
+instead of signaling an error if @var{option} is not a supported
+option. If the function successfully completes, it returns @code{t}.
The current setting of an option is available via the
@code{process-contact} function.
@section Communicating with Serial Ports
@cindex @file{/dev/tty}
@cindex @file{COM1}
+@cindex serial connections
Emacs can communicate with serial ports. For interactive use,
@kbd{M-x serial-term} opens a terminal window. In a Lisp program,
A serial connection is represented by a process object which can be
used similar to a subprocess or network process. You can send and
receive data and configure the serial port. A serial process object
-has no process ID, and you can't send signals to it.
+has no process ID, you can't send signals to it, and the status codes
+are different from other types of processes.
@code{delete-process} on the process object or @code{kill-buffer} on
the process buffer close the connection, but this does not affect the
device connected to the serial port.
The function @code{process-type} returns the symbol @code{serial}
-for a process object representing a serial port.
+for a process object representing a serial port connection.
Serial ports are available on GNU/Linux, Unix, and Windows systems.
-@defun serial-term port speed
+@deffn Command serial-term port speed
Start a terminal-emulator for a serial port in a new buffer.
-@var{port} is the path or name of the serial port. For example, this
-could be @file{/dev/ttyS0} on Unix. On Windows, this could be
-@file{COM1}, or @file{\\.\COM10} (double the backslashes in strings).
+@var{port} is the name of the serial port to which to connect. For
+example, this could be @file{/dev/ttyS0} on Unix. On Windows, this
+could be @file{COM1}, or @file{\\.\COM10} (double the backslashes in
+Lisp strings).
@var{speed} is the speed of the serial port in bits per second. 9600
-is a common value. The buffer is in Term mode; see @code{term-mode}
-for the commands to use in that buffer. You can change the speed and
-the configuration in the mode line menu. @end defun
+is a common value. The buffer is in Term mode; see @ref{Term Mode,,,
+emacs, The GNU Emacs Manual}, for the commands to use in that buffer.
+You can change the speed and the configuration in the mode line menu.
+@end deffn
@defun make-serial-process &rest args
-@code{make-serial-process} creates a process and a buffer. Arguments
-are specified as keyword/argument pairs. The following arguments are
-defined:
+This function creates a process and a buffer. Arguments are specified
+as keyword/argument pairs. Here's the list of the meaningful keywords:
@table @code
-@item :port port
-@var{port} (mandatory) is the path or name of the serial port.
-For example, this could be @file{/dev/ttyS0} on Unix. On Windows,
-this could be @file{COM1}, or @file{\\.\COM10} for ports higher than
-@file{COM9} (double the backslashes in strings).
-
-@item :speed speed
-@var{speed} (mandatory) is handled by @code{serial-process-configure},
-which is called by @code{make-serial-process}.
-
-@item :name name
-@var{name} is the name of the process. If @var{name} is not given, the
-value of @var{port} is used.
-
-@item :buffer buffer
-@var{buffer} is the buffer (or buffer-name) to associate with the
-process. Process output goes at the end of that buffer, unless you
-specify an output stream or filter function to handle the output. If
-@var{buffer} is not given, the value of @var{name} is used.
-
-@item :coding coding
+@item :port @var{port}@r{ (mandatory)}
+This is the name of the serial port. On Unix and GNU systems, this is
+a file name such as @file{/dev/ttyS0}. On Windows, this could be
+@file{COM1}, or @file{\\.\COM10} for ports higher than @file{COM9}
+(double the backslashes in Lisp strings).
+
+@item :speed @var{speed}@r{ (mandatory)}
+The speed of the serial port in bits per second. This function calls
+@code{serial-process-configure} to handle the speed.
+
+@item :name @var{name}
+The name of the process. If @var{name} is not given, @var{port} will
+serve as the process name as well.
+
+@item :buffer @var{buffer}
+The buffer to associate with the process. The value could be either a
+buffer or a string that names a buffer. Process output goes at the
+end of that buffer, unless you specify an output stream or filter
+function to handle the output. If @var{buffer} is not given, the
+process buffer's name is taken from the value of the @code{:name}
+keyword.
+
+@item :coding @var{coding}
If @var{coding} is a symbol, it specifies the coding system used for
both reading and writing for this process. If @var{coding} is a cons
@code{(decoding . encoding)}, @var{decoding} is used for reading, and
-@var{encoding} is used for writing.
+@var{encoding} is used for writing. If not specified, the default is
+to determine the coding systems from data itself.
-@item :noquery bool
-When exiting Emacs, query the user if @var{bool} is @code{nil} and the
-process is running. If @var{bool} is not given, query before exiting.
+@item :noquery @var{query-flag}
+Initialize the process query flag to @var{query-flag}. @xref{Query
+Before Exit}. The flags defaults to @code{nil} if unspecified.
-@item :stop bool
+@item :stop @var{bool}
Start process in the @code{stopped} state if @var{bool} is
non-@code{nil}. In the stopped state, a serial process does not
accept incoming data, but you can send outgoing data. The stopped
state is cleared by @code{continue-process} and set by
@code{stop-process}.
-@item :filter filter
+@item :filter @var{filter}
Install @var{filter} as the process filter.
-@item :sentinel sentinel
+@item :sentinel @var{sentinel}
Install @var{sentinel} as the process sentinel.
-@item :plist plist
+@item :plist @var{plist}
Install @var{plist} as the initial plist of the process.
@item :speed
(make-serial-process :port "COM1" :speed 115200 :stopbits 2)
-(make-serial-process :port "\\\\.\\COM13" :speed 1200 :bytesize 7 :parity 'odd)
+(make-serial-process :port "\\\\.\\COM13" :speed 1200
+ :bytesize 7 :parity 'odd)
-(make-serial-process :port "/dev/tty.BlueConsole-SPP-1" :speed nil)
+(make-serial-process :port "/dev/tty.BlueConsole-SPP-1"
+ :speed nil)
@end example
@end defun
@defun serial-process-configure &rest args
-@cindex baud
-@cindex bytesize
-@cindex parity
-@cindex stopbits
-@cindex flowcontrol
-
-Configure a serial port. Arguments are specified as keyword/argument
-pairs. Attributes that are not given are re-initialized from the
-process's current configuration (available via the function
-@code{process-contact}) or set to reasonable default values. The
-following arguments are defined:
+@cindex baud, in serial connections
+@cindex bytesize, in serial connections
+@cindex parity, in serial connections
+@cindex stopbits, in serial connections
+@cindex flowcontrol, in serial connections
+
+This functions configures a serial port connection. Arguments are
+specified as keyword/argument pairs. Attributes that are not given
+are re-initialized from the process's current configuration (available
+via the function @code{process-contact}) or set to reasonable default
+values. The following arguments are defined:
@table @code
-@item :process process
-@itemx :name name
-@itemx :buffer buffer
-@itemx :port port
+@item :process @var{process}
+@itemx :name @var{name}
+@itemx :buffer @var{buffer}
+@itemx :port @var{port}
Any of these arguments can be given to identify the process that is to
be configured. If none of these arguments is given, the current
buffer's process is used.
@item :speed @var{speed}
-@var{speed} is the speed of the serial port in bits per second, also
-called baud rate. Any value can be given for @var{speed}, but most
-serial ports work only at a few defined values between 1200 and
-115200, with 9600 being the most common value. If @var{speed} is
-@code{nil}, the serial port is not configured any further, i.e., all
-other arguments are ignored. This may be useful for special serial
-ports such as Bluetooth-to-serial converters which can only be
-configured through AT commands. A value of @code{nil} for @var{speed}
-can be used only when passed through @code{make-serial-process} or
-@code{serial-term}.
+The speed of the serial port in bits per second, a.k.a.@: @dfn{baud
+rate}. The value can be any number, but most serial ports work only
+at a few defined values between 1200 and 115200, with 9600 being the
+most common value. If @var{speed} is @code{nil}, the function ignores
+all other arguments and does not configure the port. This may be
+useful for special serial ports such as Bluetooth-to-serial converters
+which can only be configured through AT commands sent through the
+connection. The value of @code{nil} for @var{speed} is valid only for
+connections that were already opened by a previous call to
+@code{make-serial-process} or @code{serial-term}.
@item :bytesize @var{bytesize}
-@var{bytesize} is the number of bits per byte, which can be 7 or 8.
-If @var{bytesize} is not given or @code{nil}, a value of 8 is used.
+The number of bits per byte, which can be 7 or 8. If @var{bytesize}
+is not given or @code{nil}, it defaults to 8.
@item :parity @var{parity}
-@var{parity} can be @code{nil} (don't use parity), the symbol
+The value can be @code{nil} (don't use parity), the symbol
@code{odd} (use odd parity), or the symbol @code{even} (use even
-parity). If @var{parity} is not given, no parity is used.
+parity). If @var{parity} is not given, it defaults to no parity.
@item :stopbits @var{stopbits}
-@var{stopbits} is the number of stopbits used to terminate a byte
-transmission. @var{stopbits} can be 1 or 2. If @var{stopbits} is not
-given or @code{nil}, 1 stopbit is used.
+The number of stopbits used to terminate a transmission
+of each byte. @var{stopbits} can be 1 or 2. If @var{stopbits} is not
+given or @code{nil}, it defaults to 1.
@item :flowcontrol @var{flowcontrol}
-@var{flowcontrol} determines the type of flowcontrol to be used, which
-is either @code{nil} (don't use flowcontrol), the symbol @code{hw}
-(use RTS/CTS hardware flowcontrol), or the symbol @code{sw} (use
-XON/XOFF software flowcontrol). If @var{flowcontrol} is not given, no
-flowcontrol is used.
+The type of flow control to use for this connection, which is either
+@code{nil} (don't use flow control), the symbol @code{hw} (use RTS/CTS
+hardware flow control), or the symbol @code{sw} (use XON/XOFF software
+flow control). If @var{flowcontrol} is not given, it defaults to no
+flow control.
@end table
@code{serial-process-configure} is called by @code{make-serial-process} for the
@example
(serial-process-configure :process "/dev/ttyS0" :speed 1200)
-(serial-process-configure :buffer "COM1" :stopbits 1 :parity 'odd :flowcontrol 'hw)
+(serial-process-configure :buffer "COM1" :stopbits 1
+ :parity 'odd :flowcontrol 'hw)
(serial-process-configure :port "\\\\.\\COM13" :bytesize 7)
@end example