@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 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
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
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
code conversion and the end of line conversion---that is, one like
@code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
+@c Let's keep the index entries that were there for
+@c set-process-filter-multibyte and process-filter-multibyte-p,
@cindex filter multibyte flag, of process
@cindex process filter multibyte flag
When Emacs calls a process filter function, it provides the process
output as a multibyte string or as a unibyte string according to the
-process's filter multibyte flag. If the flag is non-@code{nil}, Emacs
-decodes the output according to the process output coding system to
-produce a multibyte string, and passes that to the process. If the
-flag is @code{nil}, Emacs puts the output into a unibyte string, with
-no decoding, and passes that.
-
- When you create a process, the filter multibyte flag takes its
-initial value from @code{default-enable-multibyte-characters}. If you
-want to change the flag later on, use
-@code{set-process-filter-multibyte}.
-
-@defun set-process-filter-multibyte process multibyte
-This function sets the filter multibyte flag of @var{process}
-to @var{multibyte}.
-@end defun
-
-@defun process-filter-multibyte-p process
-This function returns the filter multibyte flag of @var{process}.
-@end defun
+process's filter coding system. Emacs
+decodes the output according to the process output coding system,
+which usually produces a multibyte string, except for coding systems
+such as @code{binary} and @code{raw-text}
@node Accepting Output
@subsection Accepting Output from Processes
@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 system-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
@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