@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
send input to it.
@defun processp object
-This function returns @code{t} if @var{object} is a process,
-@code{nil} otherwise.
+This function returns @code{t} if @var{object} represents an Emacs
+subprocess, @code{nil} otherwise.
@end defun
+ In addition to subprocesses of the current Emacs session, you can
+also access other processes running on your machine. @xref{System
+Processes}.
+
@menu
* Subprocess Creation:: Functions that start subprocesses.
* Shell Arguments:: Quoting an argument to pass it to a shell.
* Output from Processes:: Collecting output from an asynchronous subprocess.
* Sentinels:: Sentinels run when process run-status changes.
* Query Before Exit:: Whether to query if exiting will kill a process.
-* Transaction Queues:: Transaction-based communication with subprocesses.
+* System Processes:: Accessing other processes running on your system.
+* 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
@node Subprocess Creation
@section Functions that Create Subprocesses
- There are three functions that create a new subprocess in which to run
+ There are three primitives that create a new subprocess in which to run
a program. One of them, @code{start-process}, creates an asynchronous
process and returns a process object (@pxref{Asynchronous Processes}).
The other two, @code{call-process} and @code{call-process-region},
@end example
@end defun
+@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}); 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}).
+
+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 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 command from the individual command-line arguments,
+every argument that includes embedded blanks will be quoted.
+@end defun
+
@node Synchronous Processes
@section Creating a Synchronous Process
@cindex synchronous subprocess
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
then returns the command's output as a string.
@end defun
+@defun process-lines program &rest args
+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.
+
+This function works by calling @code{call-process}, so program output
+is decoded in the same way as for @code{call-process}.
+@end defun
+
@node Asynchronous Processes
@section Creating an Asynchronous Process
@cindex asynchronous subprocess
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.
The @var{process} argument can be a system process @acronym{ID}; that
allows you to send signals to processes that are not children of
-Emacs.
+Emacs. @xref{System Processes}.
@end defun
@node Output from Processes
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
@end smallexample
@end defun
+@node System Processes
+@section Accessing Other Processes
+@cindex system processes
+
+ In addition to accessing and manipulating processes that are
+subprocesses of the current Emacs session, Emacs Lisp programs can
+also access other processes running on the same machine. We call
+these @dfn{system processes}, to distinguish between them and Emacs
+subprocesses.
+
+ Emacs provides several primitives for accessing system processes.
+Not all platforms support these primitives; on those which don't,
+these primitives return @code{nil}.
+
+@defun list-system-processes
+This function returns a list of all the processes running on the
+system. Each process is identified by its @acronym{PID}, a numerical
+process ID that is assigned by the OS and distinguishes the process
+from all the other processes running on the same machine at the same
+time.
+@end defun
+
+@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
+attribute and @var{value} is the value of that attribute. The various
+attribute @var{key}'s that this function can return are listed below.
+Not all platforms support all of these attributes; if an attribute is
+not supported, its association will not appear in the returned alist.
+Values that are numbers can be either integer or floating-point,
+depending on the magnitude of the value.
+
+@table @code
+@item euid
+The effective user ID of the user who invoked the process. The
+corresponding @var{value} is a number. If the process was invoked by
+the same user who runs the current Emacs session, the value is
+identical to what @code{user-uid} returns (@pxref{User
+Identification}).
+
+@item user
+User name corresponding to the process's effective user ID, a string.
+
+@item egid
+The group ID of the effective user ID, a number.
+
+@item group
+Group name corresponding to the effective user's group ID, a string.
+
+@item comm
+The name of the command that runs in the process. This is a string
+that usually specifies the name of the executable file of the process,
+without the leading directories. However, some special system
+processes can report strings that do not correspond to an executable
+file of a program.
+
+@item state
+The state code of the process. This is a short string that encodes
+the scheduling state of the process. Here's a list of the most
+frequently seen codes:
+
+@table @code
+@item "D"
+uninterruptible sleep (usually I/O)
+@item "R"
+running
+@item "S"
+interruptible sleep (waiting for some event)
+@item "T"
+stopped, e.g., by a job control signal
+@item "Z"
+``zombie'': a process that terminated, but was not reaped by its parent
+@end table
+
+@noindent
+For the full list of the possible states, see the manual page of the
+@command{ps} command.
+
+@item ppid
+The process ID of the parent process, a number.
+
+@item pgrp
+The process group ID of the process, a number.
+
+@item sess
+The session ID of the process. This is a number that is the process
+ID of the process's @dfn{session leader}.
+
+@item ttname
+A string that is the name of the process's controlling terminal. On
+Unix and GNU systems, this is normally the file name of the
+corresponding terminal device, such as @file{/dev/pts65}.
+
+@item tpgid
+The numerical process group ID of the foreground process group that
+uses the process's terminal.
+
+@item minflt
+The number of minor page faults caused by the process since its
+beginning. (Minor page faults are those that don't involve reading
+from disk.)
+
+@item majflt
+The number of major page faults caused by the process since its
+beginning. (Major page faults require a disk to be read, and are thus
+more expensive than minor page faults.)
+
+@item cminflt
+@itemx cmajflt
+Like @code{minflt} and @code{majflt}, but include the number of page
+faults for all the child processes of the given process.
+
+@item utime
+Time spent by the process in the user context, for running the
+application's code. The corresponding @var{value} is in the
+@w{@code{(@var{high} @var{low} @var{microsec})}} format, the same
+format used by functions @code{current-time} (@pxref{Time of Day,
+current-time}) and @code{file-attributes} (@pxref{File Attributes}).
+
+@item stime
+Time spent by the process in the system (kernel) context, for
+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
+@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 nice
+The @dfn{nice value} of the process, a number. (Processes with smaller
+nice values get scheduled more favorably.)
+
+@item thcount
+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}.
+
+@item etime
+The time elapsed since the process started, in the @w{@code{(@var{high}
+@var{low} @var{microsec})}} format.
+
+@item vsize
+The virtual memory size of the process, measured in kilobytes.
+
+@item rss
+The size of the process's @dfn{resident set}, the number of kilobytes
+occupied by the process in the machine's physical memory.
+
+@item pcpu
+The percentage of the CPU time used by the process since it started.
+The corresponding @var{value} is a floating-point number between 0 and
+100.
+
+@item pmem
+The percentage of the total physical memory installed on the machine
+used by the process's resident set. The value is a floating-point
+number between 0 and 100.
+
+@item args
+The command-line with which the process was invoked. This is a string
+in which individual command-line arguments are separated by blanks;
+whitespace characters that are embedded in the arguments are quoted as
+appropriate for the system's shell: escaped by backslash characters on
+GNU and Unix, and enclosed in double quote characters on Windows.
+Thus, this command-line string can be directly used in primitives such
+as @code{shell-command}.
+@end table
+
+@end defun
+
+
@node Transaction Queues
@section Transaction Queues
@cindex transaction queue
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
(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