X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/40f185ca85f2129ec33446791be2999d714f35ff..3355f04dd806aa84cf09d7890d69971802a4bbb6:/doc/lispref/processes.texi diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 28e41a0997..ae3246f0d2 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -1,7 +1,7 @@ @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 @@ -29,10 +29,14 @@ signals, obtain status information, receive output from the process, or 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. @@ -46,6 +50,7 @@ This function returns @code{t} if @var{object} is a process, * 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. @@ -53,13 +58,14 @@ This function returns @code{t} if @var{object} is a process, * 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}, @@ -188,6 +194,43 @@ a shell command: @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 @@ -443,6 +486,21 @@ This function executes @var{command} (a string) as a shell command, 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 @@ -676,6 +734,49 @@ were given to the program. @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 @@ -690,8 +791,8 @@ This function returns the name of @var{process}. @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: @@ -722,10 +823,6 @@ if @var{process-name} is not the name of an existing process. @smallexample @group -(process-status "shell") - @result{} run -@end group -@group (process-status (get-buffer "*shell*")) @result{} run @end group @@ -742,6 +839,12 @@ For a network connection, @code{process-status} returns one of the symbols 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 @@ -978,7 +1081,7 @@ This function sends a signal to process @var{process}. The argument 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 @@ -1285,7 +1388,10 @@ converts the unibyte output to multibyte using 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 @@ -1297,29 +1403,16 @@ possible, specify a coding system that determines both the character 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 @@ -1529,6 +1622,190 @@ is like this: @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 @@ -1559,8 +1836,8 @@ The argument @var{regexp} is a regular expression that should match 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. @@ -1606,11 +1883,14 @@ server process, or @code{:type 'datagram} to create a datagram 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}. @@ -1644,42 +1924,6 @@ The arguments @var{host} and @var{service} specify where to connect to; 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 @@ -2112,6 +2356,199 @@ If the vector does not include the port number, @var{p}, or if @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