@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 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.
+* 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.
* Low-Level Network:: Lower-level but more general function
to create connections and servers.
* Misc Network:: Additional relevant functions for network 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 shell command line
+ The following two functions help 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.
+
+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.
+@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{" "}.
+
+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.
+@end defun
+
@node Synchronous Processes
@section Creating a Synchronous Process
@cindex synchronous subprocess
then returns the command's output as a string.
@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.
+
+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
@end smallexample
@end defun
+@defun process-contact process &optional key
+
+This function returns information about how a network or serial
+process was set up. For a network process, when @var{key} is
+@code{nil}, it returns @code{(@var{hostname} @var{service})} which
+specifies what you connected to. For a serial process, when @var{key}
+is @code{nil}, it returns @code{(@var{port} @var{speed})}. For an
+ordinary child process, this function always returns @code{t}.
+
+If @var{key} is @code{t}, the value is the complete status information
+for the connection, server, or serial port; that is, the list of
+keywords and values specified in @code{make-network-process} or
+@code{make-serial-process}, except that some of the values represent
+the current status instead of what you specified.
+
+For a network process:
+
+@table @code
+@item :buffer
+The associated value is the process buffer.
+@item :filter
+The associated value is the process filter function.
+@item :sentinel
+The associated value is the process sentinel function.
+@item :remote
+In a connection, the address in internal format of the remote peer.
+@item :local
+The local address, in internal format.
+@item :service
+In a server, if you specified @code{t} for @var{service},
+this value is the actual port number.
+@end table
+
+@code{:local} and @code{:remote} are included even if they were not
+specified explicitly in @code{make-network-process}.
+
+For a serial process, see @code{make-serial-process} and
+@code{serial-process-configure} for a list of keys.
+
+If @var{key} is a keyword, the function returns the value corresponding
+to that keyword.
+@end defun
+
@defun process-id process
This function returns the @acronym{PID} of @var{process}. This is an
integer that distinguishes the process @var{process} from all other
@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
closed the connection, or Emacs did @code{delete-process}.
@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
+@code{real} for a real subprocess.
+@end defun
+
@defun process-exit-status process
This function returns the exit status of @var{process} or the signal
number that killed it. (Use the result of @code{process-status} to
@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
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.
connection. @xref{Low-Level Network}, for details. You can also use
the @code{open-network-stream} function described below.
- You can distinguish process objects representing network connections
-and servers from those representing subprocesses with the
-@code{process-status} function. The possible status values for
-network connections are @code{open}, @code{closed}, @code{connect},
-and @code{failed}. For a network server, the status is always
+ To distinguish the different types of processes, the
+@code{process-type} function returns the symbol @code{network} for a
+network connection or server, @code{serial} for a serial port
+connection, or @code{real} for a real subprocess.
+
+ The @code{process-status} function returns @code{open},
+@code{closed}, @code{connect}, and @code{failed} for network
+connections. For a network server, the status is always
@code{listen}. None of those values is possible for a real
subprocess. @xref{Process Information}.
a defined network service (a string) or a port number (an integer).
@end defun
-@defun process-contact process &optional key
-This function returns information about how a network process was set
-up. For a connection, when @var{key} is @code{nil}, it returns
-@code{(@var{hostname} @var{service})} which specifies what you
-connected to.
-
-If @var{key} is @code{t}, the value is the complete status information
-for the connection or server; that is, the list of keywords and values
-specified in @code{make-network-process}, except that some of the
-values represent the current status instead of what you specified:
-
-@table @code
-@item :buffer
-The associated value is the process buffer.
-@item :filter
-The associated value is the process filter function.
-@item :sentinel
-The associated value is the process sentinel function.
-@item :remote
-In a connection, the address in internal format of the remote peer.
-@item :local
-The local address, in internal format.
-@item :service
-In a server, if you specified @code{t} for @var{service},
-this value is the actual port number.
-@end table
-
-@code{:local} and @code{:remote} are included even if they were not
-specified explicitly in @code{make-network-process}.
-
-If @var{key} is a keyword, the function returns the value corresponding
-to that keyword.
-
-For an ordinary child process, this function always returns @code{t}.
-@end defun
-
@node Network Servers
@section Network Servers
@cindex network servers
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.
@code{:@var{p}} suffix.
@end defun
+@node Serial Ports
+@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,
+@code{make-serial-process} creates a process object.
+
+ The serial port can be configured at run-time, without having to
+close and re-open it. The function @code{serial-process-configure}
+lets you change the speed, bytesize, and other parameters. In a
+terminal window created by @code{serial-term}, you can click on the
+mode line for configuration.
+
+ 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, 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 connection.
+
+ Serial ports are available on GNU/Linux, Unix, and Windows systems.
+
+@deffn Command serial-term port speed
+Start a terminal-emulator for a serial port in a new buffer.
+@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 @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
+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 @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. If not specified, the default is
+to determine the coding systems from data itself.
+
+@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 @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 @var{filter}
+Install @var{filter} as the process filter.
+
+@item :sentinel @var{sentinel}
+Install @var{sentinel} as the process sentinel.
+
+@item :plist @var{plist}
+Install @var{plist} as the initial plist of the process.
+
+@item :speed
+@itemx :bytesize
+@itemx :parity
+@itemx :stopbits
+@itemx :flowcontrol
+These arguments 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:
+
+@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
+
+@defun serial-process-configure &rest args
+@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 @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}
+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}
+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}
+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, it defaults to no parity.
+
+@item :stopbits @var{stopbits}
+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}
+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
+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
+@end defun
+
@node Byte Packing
@section Packing and Unpacking Byte Arrays
@cindex byte packing and unpacking
HCoop / bpt / emacs.git / blobdiff