@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 Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@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 example
@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.
+@cindex quoting and unquoting command-line arguments
+@cindex minibuffer input, and command-line arguments
+@cindex @code{call-process}, command-line arguments from minibuffer
+@cindex @code{start-process}, command-line arguments from minibuffer
+ 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 to be used 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 the converting such lists of arguments in
+a single Lisp string to be presented in the minibuffer or echo area.
@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 @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 supports 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
it in double quotes @code{"@dots{}"}. In the simplest case, if you
-are consing a shell command from the individual command-line
-arguments, every argument that includes embedded blanks will be
-quoted.
+are consing a command from the individual command-line arguments,
+every argument that includes embedded blanks will be quoted.
@end defun
@node Synchronous 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:
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
@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.
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}.
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.
@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.
(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
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. You can use the value of @code{nil} for @var{speed} only
-for connections that are already open by a previous call to
+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}
@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
(bindat-get-field decoded 'item 1 'id)
@result{} "BCDEFG"
@end lisp
-
-@ignore
- arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
-@end ignore
HCoop / bpt / emacs.git / blobdiff