2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
5 @c See the file elisp.texi for copying conditions.
13 In the terminology of operating systems, a @dfn{process} is a space in
14 which a program can execute. Emacs runs in a process. Emacs Lisp
15 programs can invoke other programs in processes of their own. These are
16 called @dfn{subprocesses} or @dfn{child processes} of the Emacs process,
17 which is their @dfn{parent process}.
19 A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous},
20 depending on how it is created. When you create a synchronous
21 subprocess, the Lisp program waits for the subprocess to terminate
22 before continuing execution. When you create an asynchronous
23 subprocess, it can run in parallel with the Lisp program. This kind of
24 subprocess is represented within Emacs by a Lisp object which is also
25 called a ``process''. Lisp programs can use this object to communicate
26 with the subprocess or to control it. For example, you can send
27 signals, obtain status information, receive output from the process, or
30 @defun processp object
31 This function returns @code{t} if @var{object} represents an Emacs
32 subprocess, @code{nil} otherwise.
35 In addition to subprocesses of the current Emacs session, you can
36 also access other processes running on your machine. @xref{System
40 * Subprocess Creation:: Functions that start subprocesses.
41 * Shell Arguments:: Quoting an argument to pass it to a shell.
42 * Synchronous Processes:: Details of using synchronous subprocesses.
43 * Asynchronous Processes:: Starting up an asynchronous subprocess.
44 * Deleting Processes:: Eliminating an asynchronous subprocess.
45 * Process Information:: Accessing run-status and other attributes.
46 * Input to Processes:: Sending input to an asynchronous subprocess.
47 * Signals to Processes:: Stopping, continuing or interrupting
48 an asynchronous subprocess.
49 * Output from Processes:: Collecting output from an asynchronous subprocess.
50 * Sentinels:: Sentinels run when process run-status changes.
51 * Query Before Exit:: Whether to query if exiting will kill a process.
52 * System Processes:: Accessing other processes running on your system.
53 * Transaction Queues:: Transaction-based communication with subprocesses.
54 * Network:: Opening network connections.
55 * Network Servers:: Network servers let Emacs accept net connections.
56 * Datagrams:: UDP network connections.
57 * Low-Level Network:: Lower-level but more general function
58 to create connections and servers.
59 * Misc Network:: Additional relevant functions for net connections.
60 * Serial Ports:: Communicating with serial ports.
61 * Byte Packing:: Using bindat to pack and unpack binary data.
64 @node Subprocess Creation
65 @section Functions that Create Subprocesses
66 @cindex create subprocess
67 @cindex process creation
69 There are three primitives that create a new subprocess in which to run
70 a program. One of them, @code{start-process}, creates an asynchronous
71 process and returns a process object (@pxref{Asynchronous Processes}).
72 The other two, @code{call-process} and @code{call-process-region},
73 create a synchronous process and do not return a process object
74 (@pxref{Synchronous Processes}). There are various higher-level
75 functions that make use of these primitives to run particular types of
78 Synchronous and asynchronous processes are explained in the following
79 sections. Since the three functions are all called in a similar
80 fashion, their common arguments are described here.
82 @cindex execute program
83 @cindex @env{PATH} environment variable
84 @cindex @env{HOME} environment variable
85 In all cases, the function's @var{program} argument specifies the
86 program to be run. An error is signaled if the file is not found or
87 cannot be executed. If the file name is relative, the variable
88 @code{exec-path} contains a list of directories to search. Emacs
89 initializes @code{exec-path} when it starts up, based on the value of
90 the environment variable @env{PATH}. The standard file name
91 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as
92 usual in @code{exec-path}, but environment variable substitutions
93 (@samp{$HOME}, etc.)@: are not recognized; use
94 @code{substitute-in-file-name} to perform them (@pxref{File Name
95 Expansion}). @code{nil} in this list refers to
96 @code{default-directory}.
98 Executing a program can also try adding suffixes to the specified
101 @defopt exec-suffixes
102 This variable is a list of suffixes (strings) to try adding to the
103 specified program file name. The list should include @code{""} if you
104 want the name to be tried exactly as specified. The default value is
108 @strong{Please note:} The argument @var{program} contains only the
109 name of the program; it may not contain any command-line arguments. You
110 must use a separate argument, @var{args}, to provide those, as
113 Each of the subprocess-creating functions has a @var{buffer-or-name}
114 argument that specifies where the standard output from the program will
115 go. It should be a buffer or a buffer name; if it is a buffer name,
116 that will create the buffer if it does not already exist. It can also
117 be @code{nil}, which says to discard the output, unless a custom filter function
118 handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
119 Normally, you should avoid having multiple processes send output to the
120 same buffer because their output would be intermixed randomly.
121 For synchronous processes, you can send the output to a file instead
124 @cindex program arguments
125 All three of the subprocess-creating functions have a @code{&rest}
126 argument, @var{args}. The @var{args} must all be strings, and they are
127 supplied to @var{program} as separate command line arguments. Wildcard
128 characters and other shell constructs have no special meanings in these
129 strings, since the strings are passed directly to the specified program.
131 @cindex environment variables, subprocesses
132 The subprocess inherits its environment from Emacs, but you can
133 specify overrides for it with @code{process-environment}. @xref{System
134 Environment}. The subprocess gets its current directory from the
135 value of @code{default-directory}.
137 @defvar exec-directory
139 The value of this variable is a string, the name of a directory that
140 contains programs that come with GNU Emacs and are intended for Emacs
141 to invoke. The program @code{movemail} is an example of such a program;
142 Rmail uses it to fetch new mail from an inbox.
146 The value of this variable is a list of directories to search for
147 programs to run in subprocesses. Each element is either the name of a
148 directory (i.e., a string), or @code{nil}, which stands for the default
149 directory (which is the value of @code{default-directory}).
150 @cindex program directories
152 The value of @code{exec-path} is used by @code{call-process} and
153 @code{start-process} when the @var{program} argument is not an absolute
156 Generally, you should not modify @code{exec-path} directly. Instead,
157 ensure that your @env{PATH} environment variable is set appropriately
158 before starting Emacs. Trying to modify @code{exec-path}
159 independently of @env{PATH} can lead to confusing results.
162 @node Shell Arguments
163 @section Shell Arguments
164 @cindex arguments for shell commands
165 @cindex shell command arguments
167 Lisp programs sometimes need to run a shell and give it a command
168 that contains file names that were specified by the user. These
169 programs ought to be able to support any valid file name. But the shell
170 gives special treatment to certain characters, and if these characters
171 occur in the file name, they will confuse the shell. To handle these
172 characters, use the function @code{shell-quote-argument}:
174 @defun shell-quote-argument argument
175 This function returns a string that represents, in shell syntax,
176 an argument whose actual contents are @var{argument}. It should
177 work reliably to concatenate the return value into a shell command
178 and then pass it to a shell for execution.
180 Precisely what this function does depends on your operating system. The
181 function is designed to work with the syntax of your system's standard
182 shell; if you use an unusual shell, you will need to redefine this
183 function. @xref{Security Considerations}.
186 ;; @r{This example shows the behavior on GNU and Unix systems.}
187 (shell-quote-argument "foo > bar")
188 @result{} "foo\\ \\>\\ bar"
190 ;; @r{This example shows the behavior on MS-DOS and MS-Windows.}
191 (shell-quote-argument "foo > bar")
192 @result{} "\"foo > bar\""
195 Here's an example of using @code{shell-quote-argument} to construct
200 (shell-quote-argument oldfile)
202 (shell-quote-argument newfile))
206 @cindex quoting and unquoting command-line arguments
207 @cindex minibuffer input, and command-line arguments
208 @cindex @code{call-process}, command-line arguments from minibuffer
209 @cindex @code{start-process}, command-line arguments from minibuffer
210 The following two functions are useful for combining a list of
211 individual command-line argument strings into a single string, and
212 taking a string apart into a list of individual command-line
213 arguments. These functions are mainly intended for
214 converting user input in the minibuffer, a Lisp string, into a list of
215 string arguments to be passed to @code{call-process} or
216 @code{start-process}, or for converting such lists of arguments into
217 a single Lisp string to be presented in the minibuffer or echo area.
219 @defun split-string-and-unquote string &optional separators
220 This function splits @var{string} into substrings at matches for the
221 regular expression @var{separators}, like @code{split-string} does
222 (@pxref{Creating Strings}); in addition, it removes quoting from the
223 substrings. It then makes a list of the substrings and returns it.
225 If @var{separators} is omitted or @code{nil}, it defaults to
226 @code{"\\s-+"}, which is a regular expression that matches one or more
227 characters with whitespace syntax (@pxref{Syntax Class Table}).
229 This function supports two types of quoting: enclosing a whole string
230 in double quotes @code{"@dots{}"}, and quoting individual characters
231 with a backslash escape @samp{\}. The latter is also used in Lisp
232 strings, so this function can handle those as well.
235 @defun combine-and-quote-strings list-of-strings &optional separator
236 This function concatenates @var{list-of-strings} into a single string,
237 quoting each string as necessary. It also sticks the @var{separator}
238 string between each pair of strings; if @var{separator} is omitted or
239 @code{nil}, it defaults to @code{" "}. The return value is the
242 The strings in @var{list-of-strings} that need quoting are those that
243 include @var{separator} as their substring. Quoting a string encloses
244 it in double quotes @code{"@dots{}"}. In the simplest case, if you
245 are consing a command from the individual command-line arguments,
246 every argument that includes embedded blanks will be quoted.
249 @node Synchronous Processes
250 @section Creating a Synchronous Process
251 @cindex synchronous subprocess
253 After a @dfn{synchronous process} is created, Emacs waits for the
254 process to terminate before continuing. Starting Dired on GNU or
255 Unix@footnote{On other systems, Emacs uses a Lisp emulation of
256 @code{ls}; see @ref{Contents of Directories}.} is an example of this: it
257 runs @code{ls} in a synchronous process, then modifies the output
258 slightly. Because the process is synchronous, the entire directory
259 listing arrives in the buffer before Emacs tries to do anything with it.
261 While Emacs waits for the synchronous subprocess to terminate, the
262 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
263 the subprocess with a @code{SIGINT} signal; but it waits until the
264 subprocess actually terminates before quitting. If during that time the
265 user types another @kbd{C-g}, that kills the subprocess instantly with
266 @code{SIGKILL} and quits immediately (except on MS-DOS, where killing
267 other processes doesn't work). @xref{Quitting}.
269 The synchronous subprocess functions return an indication of how the
272 The output from a synchronous subprocess is generally decoded using a
273 coding system, much like text read from a file. The input sent to a
274 subprocess by @code{call-process-region} is encoded using a coding
275 system, much like text written into a file. @xref{Coding Systems}.
277 @defun call-process program &optional infile destination display &rest args
278 This function calls @var{program} and waits for it to finish.
280 The current working directory of the subprocess is
281 @code{default-directory}.
283 The standard input for the new process comes from file @var{infile} if
284 @var{infile} is not @code{nil}, and from the null device otherwise.
285 The argument @var{destination} says where to put the process output.
286 Here are the possibilities:
290 Insert the output in that buffer, before point. This includes both the
291 standard output stream and the standard error stream of the process.
293 @item a buffer name (a string)
294 Insert the output in a buffer with that name, before point.
297 Insert the output in the current buffer, before point.
303 Discard the output, and return @code{nil} immediately without waiting
304 for the subprocess to finish.
306 In this case, the process is not truly synchronous, since it can run in
307 parallel with Emacs; but you can think of it as synchronous in that
308 Emacs is essentially finished with the subprocess as soon as this
311 MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
314 @item @code{(:file @var{file-name})}
315 Send the output to the file name specified, overwriting it if it
318 @item @code{(@var{real-destination} @var{error-destination})}
319 Keep the standard output stream separate from the standard error stream;
320 deal with the ordinary output as specified by @var{real-destination},
321 and dispose of the error output according to @var{error-destination}.
322 If @var{error-destination} is @code{nil}, that means to discard the
323 error output, @code{t} means mix it with the ordinary output, and a
324 string specifies a file name to redirect error output into.
326 You can't directly specify a buffer to put the error output in; that is
327 too difficult to implement. But you can achieve this result by sending
328 the error output to a temporary file and then inserting the file into a
332 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
333 the buffer as output is inserted. (However, if the coding system chosen
334 for decoding output is @code{undecided}, meaning deduce the encoding
335 from the actual data, then redisplay sometimes cannot continue once
336 non-@acronym{ASCII} characters are encountered. There are fundamental
337 reasons why it is hard to fix this; see @ref{Output from Processes}.)
339 Otherwise the function @code{call-process} does no redisplay, and the
340 results become visible on the screen only when Emacs redisplays that
341 buffer in the normal course of events.
343 The remaining arguments, @var{args}, are strings that specify command
344 line arguments for the program.
346 The value returned by @code{call-process} (unless you told it not to
347 wait) indicates the reason for process termination. A number gives the
348 exit status of the subprocess; 0 means success, and any other value
349 means failure. If the process terminated with a signal,
350 @code{call-process} returns a string describing the signal.
352 In the examples below, the buffer @samp{foo} is current.
356 (call-process "pwd" nil t)
359 ---------- Buffer: foo ----------
361 ---------- Buffer: foo ----------
365 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
368 ---------- Buffer: bar ----------
369 lewis:x:1001:1001:Bil Lewis,,,,:/home/lewis:/bin/bash
371 ---------- Buffer: bar ----------
375 Here is an example of the use of @code{call-process}, as used to
376 be found in the definition of the @code{insert-directory} function:
380 (call-process insert-directory-program nil t nil switches
382 (concat (file-name-as-directory file) ".")
388 @defun process-file program &optional infile buffer display &rest args
389 This function processes files synchronously in a separate process. It
390 is similar to @code{call-process}, but may invoke a file handler based
391 on the value of the variable @code{default-directory}, which specifies
392 the current working directory of the subprocess.
394 The arguments are handled in almost the same way as for
395 @code{call-process}, with the following differences:
397 Some file handlers may not support all combinations and forms of the
398 arguments @var{infile}, @var{buffer}, and @var{display}. For example,
399 some file handlers might behave as if @var{display} were @code{nil},
400 regardless of the value actually passed. As another example, some
401 file handlers might not support separating standard output and error
402 output by way of the @var{buffer} argument.
404 If a file handler is invoked, it determines the program to run based
405 on the first argument @var{program}. For instance, suppose that a
406 handler for remote files is invoked. Then the path that is used for
407 searching for the program might be different from @code{exec-path}.
409 The second argument @var{infile} may invoke a file handler. The file
410 handler could be different from the handler chosen for the
411 @code{process-file} function itself. (For example,
412 @code{default-directory} could be on one remote host, and
413 @var{infile} on a different remote host. Or @code{default-directory}
414 could be non-special, whereas @var{infile} is on a remote host.)
416 If @var{buffer} is a list of the form @code{(@var{real-destination}
417 @var{error-destination})}, and @var{error-destination} names a file,
418 then the same remarks as for @var{infile} apply.
420 The remaining arguments (@var{args}) will be passed to the process
421 verbatim. Emacs is not involved in processing file names that are
422 present in @var{args}. To avoid confusion, it may be best to avoid
423 absolute file names in @var{args}, but rather to specify all file
424 names as relative to @code{default-directory}. The function
425 @code{file-relative-name} is useful for constructing such relative
429 @defvar process-file-side-effects
430 This variable indicates whether a call of @code{process-file} changes
433 By default, this variable is always set to @code{t}, meaning that a
434 call of @code{process-file} could potentially change any file on a
435 remote host. When set to @code{nil}, a file handler could optimize
436 its behavior with respect to remote file attribute caching.
438 You should only ever change this variable with a let-binding; never
442 @defun call-process-region start end program &optional delete destination display &rest args
443 This function sends the text from @var{start} to @var{end} as
444 standard input to a process running @var{program}. It deletes the text
445 sent if @var{delete} is non-@code{nil}; this is useful when
446 @var{destination} is @code{t}, to insert the output in the current
447 buffer in place of the input.
449 The arguments @var{destination} and @var{display} control what to do
450 with the output from the subprocess, and whether to update the display
451 as it comes in. For details, see the description of
452 @code{call-process}, above. If @var{destination} is the integer 0,
453 @code{call-process-region} discards the output and returns @code{nil}
454 immediately, without waiting for the subprocess to finish (this only
455 works if asynchronous subprocesses are supported; i.e., not on MS-DOS).
457 The remaining arguments, @var{args}, are strings that specify command
458 line arguments for the program.
460 The return value of @code{call-process-region} is just like that of
461 @code{call-process}: @code{nil} if you told it to return without
462 waiting; otherwise, a number or string which indicates how the
463 subprocess terminated.
465 In the following example, we use @code{call-process-region} to run the
466 @code{cat} utility, with standard input being the first five characters
467 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
468 standard input into its standard output. Since the argument
469 @var{destination} is @code{t}, this output is inserted in the current
474 ---------- Buffer: foo ----------
476 ---------- Buffer: foo ----------
480 (call-process-region 1 6 "cat" nil t)
483 ---------- Buffer: foo ----------
485 ---------- Buffer: foo ----------
489 For example, the @code{shell-command-on-region} command uses
490 @code{call-process-region} in a manner similar to this:
496 shell-file-name ; @r{name of program}
497 nil ; @r{do not delete region}
498 buffer ; @r{send output to @code{buffer}}
499 nil ; @r{no redisplay during output}
500 "-c" command) ; @r{arguments for the shell}
503 @c It actually uses shell-command-switch, but no need to mention that here.
506 @defun call-process-shell-command command &optional infile destination display
507 This function executes the shell command @var{command} synchronously.
508 The arguments are handled as in @code{call-process}. An old calling
509 convention allowed to pass any number of additional arguments after
510 @var{display}, which were concatenated to @var{command}; this is still
511 supported, but strongly discouraged.
514 @defun process-file-shell-command command &optional infile destination display
515 This function is like @code{call-process-shell-command}, but uses
516 @code{process-file} internally. Depending on @code{default-directory},
517 @var{command} can be executed also on remote hosts. An old calling
518 convention allowed to pass any number of additional arguments after
519 @var{display}, which were concatenated to @var{command}; this is still
520 supported, but strongly discouraged.
523 @defun shell-command-to-string command
524 This function executes @var{command} (a string) as a shell command,
525 then returns the command's output as a string.
528 @c There is also shell-command-on-region, but that is more of a user
529 @c command, not something to use in programs.
531 @defun process-lines program &rest args
532 This function runs @var{program}, waits for it to finish, and returns
533 its output as a list of strings. Each string in the list holds a
534 single line of text output by the program; the end-of-line characters
535 are stripped from each line. The arguments beyond @var{program},
536 @var{args}, are strings that specify command-line arguments with which
539 If @var{program} exits with a non-zero exit status, this function
542 This function works by calling @code{call-process}, so program output
543 is decoded in the same way as for @code{call-process}.
546 @node Asynchronous Processes
547 @section Creating an Asynchronous Process
548 @cindex asynchronous subprocess
550 In this section, we describe how to create an @dfn{asynchronous
551 process}. After an asynchronous process is created, it runs in
552 parallel with Emacs, and Emacs can communicate with it using the
553 functions described in the following sections (@pxref{Input to
554 Processes}, and @pxref{Output from Processes}). Note that process
555 communication is only partially asynchronous: Emacs sends data to the
556 process only when certain functions are called, and Emacs accepts data
557 from the process only while waiting for input or for a time delay.
561 An asynchronous process is controlled either via a @dfn{pty}
562 (pseudo-terminal) or a @dfn{pipe}. The choice of pty or pipe is made
563 when creating the process, based on the value of the variable
564 @code{process-connection-type} (see below). Ptys are usually
565 preferable for processes visible to the user, as in Shell mode,
566 because they allow for job control (@kbd{C-c}, @kbd{C-z}, etc.)@:
567 between the process and its children, whereas pipes do not. For
568 subprocesses used for internal purposes by programs, it is often
569 better to use a pipe, because they are more efficient, and because
570 they are immune to stray character injections that ptys introduce for
571 large (around 500 byte) messages. Also, the total number of ptys is
572 limited on many systems and it is good not to waste them.
574 @defun start-process name buffer-or-name program &rest args
575 This function creates a new asynchronous subprocess and starts the
576 program @var{program} running in it. It returns a process object that
577 stands for the new subprocess in Lisp. The argument @var{name}
578 specifies the name for the process object; if a process with this name
579 already exists, then @var{name} is modified (by appending @samp{<1>},
580 etc.)@: to be unique. The buffer @var{buffer-or-name} is the buffer to
581 associate with the process.
583 If @var{program} is @code{nil}, Emacs opens a new pseudoterminal (pty)
584 and associates its input and output with @var{buffer-or-name}, without
585 creating a subprocess. In that case, the remaining arguments
586 @var{args} are ignored.
588 The remaining arguments, @var{args}, are strings that specify command
589 line arguments for the subprocess.
591 In the example below, the first process is started and runs (rather,
592 sleeps) for 100 seconds (the output buffer @samp{foo} is created
593 immediately). Meanwhile, the second process is started, and
594 given the name @samp{my-process<1>} for the sake of uniqueness. It
595 inserts the directory listing at the end of the buffer @samp{foo},
596 before the first process finishes. Then it finishes, and a message to
597 that effect is inserted in the buffer. Much later, the first process
598 finishes, and another message is inserted in the buffer for it.
602 (start-process "my-process" "foo" "sleep" "100")
603 @result{} #<process my-process>
607 (start-process "my-process" "foo" "ls" "-l" "/bin")
608 @result{} #<process my-process<1>>
610 ---------- Buffer: foo ----------
612 -rwxr-xr-x 1 root root 971384 Mar 30 10:14 bash
613 -rwxr-xr-x 1 root root 146920 Jul 5 2011 bsd-csh
615 -rwxr-xr-x 1 root root 696880 Feb 28 15:55 zsh4
617 Process my-process<1> finished
619 Process my-process finished
620 ---------- Buffer: foo ----------
625 @defun start-file-process name buffer-or-name program &rest args
626 Like @code{start-process}, this function starts a new asynchronous
627 subprocess running @var{program} in it, and returns its process
630 The difference from @code{start-process} is that this function may
631 invoked a file handler based on the value of @code{default-directory}.
632 This handler ought to run @var{program}, perhaps on the local host,
633 perhaps on a remote host that corresponds to @code{default-directory}.
634 In the latter case, the local part of @code{default-directory} becomes
635 the working directory of the process.
637 This function does not try to invoke file name handlers for
638 @var{program} or for the @var{program-args}.
640 Depending on the implementation of the file handler, it might not be
641 possible to apply @code{process-filter} or @code{process-sentinel} to
642 the resulting process object. @xref{Filter Functions}, and @ref{Sentinels}.
644 @c FIXME Can we find a better example (i.e., a more modern function
645 @c that is actually documented).
646 Some file handlers may not support @code{start-file-process} (for
647 example the function @code{ange-ftp-hook-function}). In such cases,
648 this function does nothing and returns @code{nil}.
651 @defun start-process-shell-command name buffer-or-name command
652 This function is like @code{start-process}, except that it uses a shell
653 to execute the specified command. The argument @var{command} is a shell
654 command name. The variable @code{shell-file-name} specifies which shell to
657 The point of running a program through the shell, rather than directly
658 with @code{start-process}, is so that you can employ shell features such
659 as wildcards in the arguments. It follows that if you include any
660 arbitrary user-specified arguments in the command, you should quote them
661 with @code{shell-quote-argument} first, so that any special shell
662 characters do @emph{not} have their special shell meanings. @xref{Shell
663 Arguments}. Of course, when executing commands based on user input
664 you should also consider the security implications.
667 @defun start-file-process-shell-command name buffer-or-name command
668 This function is like @code{start-process-shell-command}, but uses
669 @code{start-file-process} internally. Because of this, @var{command}
670 can also be executed on remote hosts, depending on @code{default-directory}.
673 @defvar process-connection-type
674 This variable controls the type of device used to communicate with
675 asynchronous subprocesses. If it is non-@code{nil}, then ptys are
676 used, when available. Otherwise, pipes are used.
678 The value of @code{process-connection-type} takes effect when
679 @code{start-process} is called. So you can specify how to communicate
680 with one subprocess by binding the variable around the call to
681 @code{start-process}.
685 (let ((process-connection-type nil)) ; @r{use a pipe}
686 (start-process @dots{}))
690 To determine whether a given subprocess actually got a pipe or a pty,
691 use the function @code{process-tty-name} (@pxref{Process
695 @defun make-process &rest args
696 This function is like @code{start-process}, but takes keyword arguments.
698 The arguments @var{args} are a list of keyword/argument pairs.
699 Omitting a keyword is always equivalent to specifying it with value
700 @code{nil}. Here are the meaningful keywords:
703 @item :name @var{name}
704 Use the string @var{name} as the process name. It is modified if
705 necessary to make it unique.
707 @item :buffer @var{buffer}
708 Use @var{buffer} as the process buffer.
710 @item :command @var{command}
711 Use @var{command} as the command line of the process. @var{command}
712 is a list starting with the program's executable file name, followed
713 by strings to give to program as arguments.
715 @item :coding @var{coding}
716 If @var{coding} is a symbol, it specifies the coding system to be
717 used for both reading and writing of data from and to the
718 connection. If @var{coding} is a cons cell
719 @w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
720 will be used for reading and @var{encoding} for writing.
722 If @var{coding} is @code{nil}, the default rules for finding the
723 coding system will apply. @xref{Default Coding Systems}.
725 @item :connection-type @var{TYPE}
726 Initialize the type of device used to communicate with the subprocess.
727 Possible values are @code{pty} to use a pty, @code{pipe} to use a
728 pipe, or @code{nil} to use the default derived from the value of
729 the @code{process-connection-type} variable.
731 @item :noquery @var{query-flag}
732 Initialize the process query flag to @var{query-flag}.
733 @xref{Query Before Exit}.
735 @item :stop @var{stopped}
736 If @var{stopped} is non-@code{nil}, start the process in the
739 @item :filter @var{filter}
740 Initialize the process filter to @var{filter}. If not specified, a
741 default filter will be provided. @xref{Filter Functions}.
743 @item :sentinel @var{sentinel}
744 Initialize the process sentinel to @var{sentinel}. If not specified,
745 a default sentinel will be used. @xref{Sentinels}.
747 @item :stderr @var{stderr}
748 Associate @var{stderr} with the standard error of the process.
749 @var{stderr} is either a buffer or a pipe process created with
750 @code{make-pipe-process}.
753 The original argument list, modified with the actual connection
754 information, is available via the @code{process-contact} function.
757 @defun make-pipe-process &rest args
758 This function creates a bidirectional pipe which can be attached to a
759 child process (currently only useful with the @code{:stderr} keyword
760 of @code{make-process}).
762 The arguments @var{args} are a list of keyword/argument pairs.
763 Omitting a keyword is always equivalent to specifying it with value
764 @code{nil}, except for @code{:coding}.
765 Here are the meaningful keywords:
768 @item :name @var{name}
769 Use the string @var{name} as the process name. It is modified if
770 necessary to make it unique.
772 @item :buffer @var{buffer}
773 Use @var{buffer} as the process buffer.
775 @item :coding @var{coding}
776 If @var{coding} is a symbol, it specifies the coding system to be
777 used for both reading and writing of data from and to the
778 connection. If @var{coding} is a cons cell
779 @w{@code{(@var{decoding} . @var{encoding})}}, then @var{decoding}
780 will be used for reading and @var{encoding} for writing.
782 If @var{coding} is @code{nil}, the default rules for finding the
783 coding system will apply. @xref{Default Coding Systems}.
785 @item :noquery @var{query-flag}
786 Initialize the process query flag to @var{query-flag}.
787 @xref{Query Before Exit}.
789 @item :stop @var{stopped}
790 If @var{stopped} is non-@code{nil}, start the process in the
793 @item :filter @var{filter}
794 Initialize the process filter to @var{filter}. If not specified, a
795 default filter will be provided. @xref{Filter Functions}.
797 @item :sentinel @var{sentinel}
798 Initialize the process sentinel to @var{sentinel}. If not specified,
799 a default sentinel will be used. @xref{Sentinels}.
802 The original argument list, modified with the actual connection
803 information, is available via the @code{process-contact} function.
806 @node Deleting Processes
807 @section Deleting Processes
808 @cindex deleting processes
810 @dfn{Deleting a process} disconnects Emacs immediately from the
811 subprocess. Processes are deleted automatically after they terminate,
812 but not necessarily right away. You can delete a process explicitly
813 at any time. If you explicitly delete a terminated process before it
814 is deleted automatically, no harm results. Deleting a running
815 process sends a signal to terminate it (and its child processes, if
816 any), and calls the process sentinel. @xref{Sentinels}.
818 When a process is deleted, the process object itself continues to
819 exist as long as other Lisp objects point to it. All the Lisp
820 primitives that work on process objects accept deleted processes, but
821 those that do I/O or send signals will report an error. The process
822 mark continues to point to the same place as before, usually into a
823 buffer where output from the process was being inserted.
825 @defopt delete-exited-processes
826 This variable controls automatic deletion of processes that have
827 terminated (due to calling @code{exit} or to a signal). If it is
828 @code{nil}, then they continue to exist until the user runs
829 @code{list-processes}. Otherwise, they are deleted immediately after
833 @defun delete-process process
834 This function deletes a process, killing it with a @code{SIGKILL}
835 signal. The argument may be a process, the name of a process, a
836 buffer, or the name of a buffer. (A buffer or buffer-name stands for
837 the process that @code{get-buffer-process} returns.) Calling
838 @code{delete-process} on a running process terminates it, updates the
839 process status, and runs the sentinel immediately. If the
840 process has already terminated, calling @code{delete-process} has no
841 effect on its status, or on the running of its sentinel (which will
842 happen sooner or later).
846 (delete-process "*shell*")
852 @node Process Information
853 @section Process Information
854 @cindex process information
856 Several functions return information about processes.
858 @deffn Command list-processes &optional query-only buffer
859 This command displays a listing of all living processes. In addition,
860 it finally deletes any process whose status was @samp{Exited} or
861 @samp{Signaled}. It returns @code{nil}.
863 The processes are shown in a buffer named @file{*Process List*}
864 (unless you specify otherwise using the optional argument @var{buffer}),
865 whose major mode is Process Menu mode.
867 If @var{query-only} is non-@code{nil}, it only lists processes
868 whose query flag is non-@code{nil}. @xref{Query Before Exit}.
872 This function returns a list of all processes that have not been deleted.
877 @result{} (#<process display-time> #<process shell>)
882 @defun get-process name
883 This function returns the process named @var{name} (a string), or
884 @code{nil} if there is none.
888 (get-process "shell")
889 @result{} #<process shell>
894 @defun process-command process
895 This function returns the command that was executed to start
896 @var{process}. This is a list of strings, the first string being the
897 program executed and the rest of the strings being the arguments that
898 were given to the program.
902 (process-command (get-process "shell"))
903 @result{} ("bash" "-i")
908 @defun process-contact process &optional key
910 This function returns information about how a network or serial
911 process was set up. When @var{key} is @code{nil}, it returns
912 @code{(@var{hostname} @var{service})} for a network process, and
913 @code{(@var{port} @var{speed})} for a serial process.
914 For an ordinary child process, this function always returns @code{t}.
916 If @var{key} is @code{t}, the value is the complete status information
917 for the connection, server, or serial port; that is, the list of
918 keywords and values specified in @code{make-network-process} or
919 @code{make-serial-process}, except that some of the values represent
920 the current status instead of what you specified.
922 For a network process, the values include (see
923 @code{make-network-process} for a complete list):
927 The associated value is the process buffer.
929 The associated value is the process filter function. @xref{Filter
932 The associated value is the process sentinel function. @xref{Sentinels}.
934 In a connection, the address in internal format of the remote peer.
936 The local address, in internal format.
938 In a server, if you specified @code{t} for @var{service},
939 this value is the actual port number.
942 @code{:local} and @code{:remote} are included even if they were not
943 specified explicitly in @code{make-network-process}.
945 For a serial process, see @code{make-serial-process} and
946 @code{serial-process-configure} for a list of keys.
948 If @var{key} is a keyword, the function returns the value corresponding
952 @defun process-id process
953 This function returns the @acronym{PID} of @var{process}. This is an
954 integer that distinguishes the process @var{process} from all other
955 processes running on the same computer at the current time. The
956 @acronym{PID} of a process is chosen by the operating system kernel when the
957 process is started and remains constant as long as the process exists.
960 @defun process-name process
961 This function returns the name of @var{process}, as a string.
964 @defun process-status process-name
965 This function returns the status of @var{process-name} as a symbol.
966 The argument @var{process-name} must be a process, a buffer, or a
967 process name (a string).
969 The possible values for an actual subprocess are:
973 for a process that is running.
975 for a process that is stopped but continuable.
977 for a process that has exited.
979 for a process that has received a fatal signal.
981 for a network connection that is open.
983 for a network connection that is closed. Once a connection
984 is closed, you cannot reopen it, though you might be able to open
985 a new connection to the same place.
987 for a non-blocking connection that is waiting to complete.
989 for a non-blocking connection that has failed to complete.
991 for a network server that is listening.
993 if @var{process-name} is not the name of an existing process.
998 (process-status (get-buffer "*shell*"))
1003 For a network connection, @code{process-status} returns one of the symbols
1004 @code{open} or @code{closed}. The latter means that the other side
1005 closed the connection, or Emacs did @code{delete-process}.
1008 @defun process-live-p process
1009 This function returns non-@code{nil} if @var{process} is alive. A
1010 process is considered alive if its status is @code{run}, @code{open},
1011 @code{listen}, @code{connect} or @code{stop}.
1014 @defun process-type process
1015 This function returns the symbol @code{network} for a network
1016 connection or server, @code{serial} for a serial port connection, or
1017 @code{real} for a real subprocess.
1020 @defun process-exit-status process
1021 This function returns the exit status of @var{process} or the signal
1022 number that killed it. (Use the result of @code{process-status} to
1023 determine which of those it is.) If @var{process} has not yet
1024 terminated, the value is 0.
1027 @defun process-tty-name process
1028 This function returns the terminal name that @var{process} is using for
1029 its communication with Emacs---or @code{nil} if it is using pipes
1030 instead of a terminal (see @code{process-connection-type} in
1031 @ref{Asynchronous Processes}). If @var{process} represents a program
1032 running on a remote host, the terminal name used by that program on
1033 the remote host is provided as process property @code{remote-tty}.
1036 @defun process-coding-system process
1037 @anchor{Coding systems for a subprocess}
1038 This function returns a cons cell @code{(@var{decode} . @var{encode})},
1039 describing the coding systems in use for decoding output from, and
1040 encoding input to, @var{process} (@pxref{Coding Systems}).
1043 @defun set-process-coding-system process &optional decoding-system encoding-system
1044 This function specifies the coding systems to use for subsequent output
1045 from and input to @var{process}. It will use @var{decoding-system} to
1046 decode subprocess output, and @var{encoding-system} to encode subprocess
1050 Every process also has a property list that you can use to store
1051 miscellaneous values associated with the process.
1053 @defun process-get process propname
1054 This function returns the value of the @var{propname} property
1058 @defun process-put process propname value
1059 This function sets the value of the @var{propname} property
1060 of @var{process} to @var{value}.
1063 @defun process-plist process
1064 This function returns the process plist of @var{process}.
1067 @defun set-process-plist process plist
1068 This function sets the process plist of @var{process} to @var{plist}.
1071 @node Input to Processes
1072 @section Sending Input to Processes
1073 @cindex process input
1075 Asynchronous subprocesses receive input when it is sent to them by
1076 Emacs, which is done with the functions in this section. You must
1077 specify the process to send input to, and the input data to send. The
1078 data appears on the standard input of the subprocess.
1081 Some operating systems have limited space for buffered input in a
1082 pty. On these systems, Emacs sends an @acronym{EOF} periodically
1083 amidst the other characters, to force them through. For most
1084 programs, these @acronym{EOF}s do no harm.
1086 Subprocess input is normally encoded using a coding system before the
1087 subprocess receives it, much like text written into a file. You can use
1088 @code{set-process-coding-system} to specify which coding system to use
1089 (@pxref{Process Information}). Otherwise, the coding system comes from
1090 @code{coding-system-for-write}, if that is non-@code{nil}; or else from
1091 the defaulting mechanism (@pxref{Default Coding Systems}).
1093 Sometimes the system is unable to accept input for that process,
1094 because the input buffer is full. When this happens, the send functions
1095 wait a short while, accepting output from subprocesses, and then try
1096 again. This gives the subprocess a chance to read more of its pending
1097 input and make space in the buffer. It also allows filters, sentinels
1098 and timers to run---so take account of that in writing your code.
1100 In these functions, the @var{process} argument can be a process or
1101 the name of a process, or a buffer or buffer name (which stands
1102 for a process via @code{get-buffer-process}). @code{nil} means
1103 the current buffer's process.
1105 @defun process-send-string process string
1106 This function sends @var{process} the contents of @var{string} as
1107 standard input. It returns @code{nil}. For example, to make a
1108 Shell buffer list files:
1112 (process-send-string "shell<1>" "ls\n")
1118 @defun process-send-region process start end
1119 This function sends the text in the region defined by @var{start} and
1120 @var{end} as standard input to @var{process}.
1122 An error is signaled unless both @var{start} and @var{end} are
1123 integers or markers that indicate positions in the current buffer. (It
1124 is unimportant which number is larger.)
1127 @defun process-send-eof &optional process
1128 This function makes @var{process} see an end-of-file in its
1129 input. The @acronym{EOF} comes after any text already sent to it.
1130 The function returns @var{process}.
1134 (process-send-eof "shell")
1140 @defun process-running-child-p &optional process
1141 This function will tell you whether a @var{process} has given control of
1142 its terminal to its own child process. The value is @code{t} if this is
1143 true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
1144 that this is not so.
1147 @node Signals to Processes
1148 @section Sending Signals to Processes
1149 @cindex process signals
1150 @cindex sending signals
1153 @dfn{Sending a signal} to a subprocess is a way of interrupting its
1154 activities. There are several different signals, each with its own
1155 meaning. The set of signals and their names is defined by the operating
1156 system. For example, the signal @code{SIGINT} means that the user has
1157 typed @kbd{C-c}, or that some analogous thing has happened.
1159 Each signal has a standard effect on the subprocess. Most signals
1160 kill the subprocess, but some stop (or resume) execution instead. Most
1161 signals can optionally be handled by programs; if the program handles
1162 the signal, then we can say nothing in general about its effects.
1164 You can send signals explicitly by calling the functions in this
1165 section. Emacs also sends signals automatically at certain times:
1166 killing a buffer sends a @code{SIGHUP} signal to all its associated
1167 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
1168 processes. (@code{SIGHUP} is a signal that usually indicates that the
1169 user ``hung up the phone'', i.e., disconnected.)
1171 Each of the signal-sending functions takes two optional arguments:
1172 @var{process} and @var{current-group}.
1174 The argument @var{process} must be either a process, a process
1175 name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name
1176 stands for a process through @code{get-buffer-process}. @code{nil}
1177 stands for the process associated with the current buffer. An error
1178 is signaled if @var{process} does not identify a process.
1180 The argument @var{current-group} is a flag that makes a difference
1181 when you are running a job-control shell as an Emacs subprocess. If it
1182 is non-@code{nil}, then the signal is sent to the current process-group
1183 of the terminal that Emacs uses to communicate with the subprocess. If
1184 the process is a job-control shell, this means the shell's current
1185 subjob. If it is @code{nil}, the signal is sent to the process group of
1186 the immediate subprocess of Emacs. If the subprocess is a job-control
1187 shell, this is the shell itself.
1189 The flag @var{current-group} has no effect when a pipe is used to
1190 communicate with the subprocess, because the operating system does not
1191 support the distinction in the case of pipes. For the same reason,
1192 job-control shells won't work when a pipe is used. See
1193 @code{process-connection-type} in @ref{Asynchronous Processes}.
1195 @defun interrupt-process &optional process current-group
1196 This function interrupts the process @var{process} by sending the
1197 signal @code{SIGINT}. Outside of Emacs, typing the interrupt
1198 character (normally @kbd{C-c} on some systems, and @key{DEL} on
1199 others) sends this signal. When the argument @var{current-group} is
1200 non-@code{nil}, you can think of this function as typing @kbd{C-c}
1201 on the terminal by which Emacs talks to the subprocess.
1204 @defun kill-process &optional process current-group
1205 This function kills the process @var{process} by sending the
1206 signal @code{SIGKILL}. This signal kills the subprocess immediately,
1207 and cannot be handled by the subprocess.
1210 @defun quit-process &optional process current-group
1211 This function sends the signal @code{SIGQUIT} to the process
1212 @var{process}. This signal is the one sent by the quit
1213 character (usually @kbd{C-\}) when you are not inside
1217 @defun stop-process &optional process current-group
1218 This function stops the process @var{process} by sending the
1219 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
1222 Outside of Emacs, on systems with job control, the stop character
1223 (usually @kbd{C-z}) normally sends this signal. When
1224 @var{current-group} is non-@code{nil}, you can think of this function as
1225 typing @kbd{C-z} on the terminal Emacs uses to communicate with the
1229 @defun continue-process &optional process current-group
1230 This function resumes execution of the process @var{process} by sending
1231 it the signal @code{SIGCONT}. This presumes that @var{process} was
1235 @deffn Command signal-process process signal
1236 This function sends a signal to process @var{process}. The argument
1237 @var{signal} specifies which signal to send; it should be an integer,
1238 or a symbol whose name is a signal.
1240 The @var{process} argument can be a system process @acronym{ID} (an
1241 integer); that allows you to send signals to processes that are not
1242 children of Emacs. @xref{System Processes}.
1245 @node Output from Processes
1246 @section Receiving Output from Processes
1247 @cindex process output
1248 @cindex output from processes
1250 The output that a subprocess writes to its standard output stream
1251 is passed to a function called the @dfn{filter function}. The default
1252 filter function simply inserts the output into a buffer, which is
1253 called the associated buffer of the process (@pxref{Process
1254 Buffers}). If the process has no buffer then the default filter
1255 discards the output.
1257 When a subprocess terminates, Emacs reads any pending output,
1258 then stops reading output from that subprocess. Therefore, if the
1259 subprocess has children that are still live and still producing
1260 output, Emacs won't receive that output.
1262 Output from a subprocess can arrive only while Emacs is waiting: when
1263 reading terminal input (see the function @code{waiting-for-user-input-p}),
1264 in @code{sit-for} and @code{sleep-for} (@pxref{Waiting}), and in
1265 @code{accept-process-output} (@pxref{Accepting Output}). This
1266 minimizes the problem of timing errors that usually plague parallel
1267 programming. For example, you can safely create a process and only
1268 then specify its buffer or filter function; no output can arrive
1269 before you finish, if the code in between does not call any primitive
1272 @defvar process-adaptive-read-buffering
1273 On some systems, when Emacs reads the output from a subprocess, the
1274 output data is read in very small blocks, potentially resulting in
1275 very poor performance. This behavior can be remedied to some extent
1276 by setting the variable @code{process-adaptive-read-buffering} to a
1277 non-@code{nil} value (the default), as it will automatically delay reading
1278 from such processes, thus allowing them to produce more output before
1279 Emacs tries to read it.
1282 It is impossible to separate the standard output and standard error
1283 streams of the subprocess, because Emacs normally spawns the subprocess
1284 inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If
1285 you want to keep the output to those streams separate, you should
1286 redirect one of them to a file---for example, by using an appropriate
1290 * Process Buffers:: By default, output is put in a buffer.
1291 * Filter Functions:: Filter functions accept output from the process.
1292 * Decoding Output:: Filters can get unibyte or multibyte strings.
1293 * Accepting Output:: How to wait until process output arrives.
1296 @node Process Buffers
1297 @subsection Process Buffers
1299 A process can (and usually does) have an @dfn{associated buffer},
1300 which is an ordinary Emacs buffer that is used for two purposes: storing
1301 the output from the process, and deciding when to kill the process. You
1302 can also use the buffer to identify a process to operate on, since in
1303 normal practice only one process is associated with any given buffer.
1304 Many applications of processes also use the buffer for editing input to
1305 be sent to the process, but this is not built into Emacs Lisp.
1307 By default, process output is inserted in the associated buffer.
1308 (You can change this by defining a custom filter function,
1309 @pxref{Filter Functions}.) The position to insert the output is
1310 determined by the @code{process-mark}, which is then updated to point
1311 to the end of the text just inserted. Usually, but not always, the
1312 @code{process-mark} is at the end of the buffer.
1314 @findex process-kill-buffer-query-function
1315 Killing the associated buffer of a process also kills the process.
1316 Emacs asks for confirmation first, if the process's
1317 @code{process-query-on-exit-flag} is non-@code{nil} (@pxref{Query
1318 Before Exit}). This confirmation is done by the function
1319 @code{process-kill-buffer-query-function}, which is run from
1320 @code{kill-buffer-query-functions} (@pxref{Killing Buffers}).
1322 @defun process-buffer process
1323 This function returns the associated buffer of the process
1328 (process-buffer (get-process "shell"))
1329 @result{} #<buffer *shell*>
1334 @defun process-mark process
1335 This function returns the process marker for @var{process}, which is the
1336 marker that says where to insert output from the process.
1338 If @var{process} does not have a buffer, @code{process-mark} returns a
1339 marker that points nowhere.
1341 The default filter function uses this marker to decide where to
1342 insert process output, and updates it to point after the inserted text.
1343 That is why successive batches of output are inserted consecutively.
1345 Custom filter functions normally should use this marker in the same fashion.
1346 For an example of a filter function that uses @code{process-mark},
1347 @pxref{Process Filter Example}.
1349 When the user is expected to enter input in the process buffer for
1350 transmission to the process, the process marker separates the new input
1351 from previous output.
1354 @defun set-process-buffer process buffer
1355 This function sets the buffer associated with @var{process} to
1356 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
1357 associated with no buffer.
1360 @defun get-buffer-process buffer-or-name
1361 This function returns a nondeleted process associated with the buffer
1362 specified by @var{buffer-or-name}. If there are several processes
1363 associated with it, this function chooses one (currently, the one most
1364 recently created, but don't count on that). Deletion of a process
1365 (see @code{delete-process}) makes it ineligible for this function to
1368 It is usually a bad idea to have more than one process associated with
1373 (get-buffer-process "*shell*")
1374 @result{} #<process shell>
1378 Killing the process's buffer deletes the process, which kills the
1379 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
1382 @node Filter Functions
1383 @subsection Process Filter Functions
1384 @cindex filter function
1385 @cindex process filter
1387 @cindex default filter function of a process
1388 A process @dfn{filter function} is a function that receives the
1389 standard output from the associated process. @emph{All} output from
1390 that process is passed to the filter. The default filter simply
1391 outputs directly to the process buffer.
1393 The filter function can only be called when Emacs is waiting for
1394 something, because process output arrives only at such times. Emacs
1395 waits when reading terminal input (see the function
1396 @code{waiting-for-user-input-p}), in @code{sit-for} and
1397 @code{sleep-for} (@pxref{Waiting}), and in
1398 @code{accept-process-output} (@pxref{Accepting Output}).
1400 A filter function must accept two arguments: the associated process
1401 and a string, which is output just received from it. The function is
1402 then free to do whatever it chooses with the output.
1404 @c Note this text is duplicated in the sentinels section.
1405 Quitting is normally inhibited within a filter function---otherwise,
1406 the effect of typing @kbd{C-g} at command level or to quit a user
1407 command would be unpredictable. If you want to permit quitting inside
1408 a filter function, bind @code{inhibit-quit} to @code{nil}. In most
1409 cases, the right way to do this is with the macro
1410 @code{with-local-quit}. @xref{Quitting}.
1412 If an error happens during execution of a filter function, it is
1413 caught automatically, so that it doesn't stop the execution of whatever
1414 program was running when the filter function was started. However, if
1415 @code{debug-on-error} is non-@code{nil}, errors are not caught.
1416 This makes it possible to use the Lisp debugger to debug the
1417 filter function. @xref{Debugger}.
1419 Many filter functions sometimes (or always) insert the output in the
1420 process's buffer, mimicking the actions of the default filter.
1421 Such filter functions need to make sure that they save the
1422 current buffer, select the correct buffer (if different) before
1423 inserting output, and then restore the original buffer.
1424 They should also check whether the buffer is still alive, update the
1425 process marker, and in some cases update the value of point. Here is
1426 how to do these things:
1428 @anchor{Process Filter Example}
1431 (defun ordinary-insertion-filter (proc string)
1432 (when (buffer-live-p (process-buffer proc))
1433 (with-current-buffer (process-buffer proc)
1434 (let ((moving (= (point) (process-mark proc))))
1438 ;; @r{Insert the text, advancing the process marker.}
1439 (goto-char (process-mark proc))
1441 (set-marker (process-mark proc) (point)))
1442 (if moving (goto-char (process-mark proc)))))))
1446 To make the filter force the process buffer to be visible whenever new
1447 text arrives, you could insert a line like the following just before the
1448 @code{with-current-buffer} construct:
1451 (display-buffer (process-buffer proc))
1454 To force point to the end of the new output, no matter where it was
1455 previously, eliminate the variable @code{moving} and call
1456 @code{goto-char} unconditionally.
1459 In earlier Emacs versions, every filter function that did regular
1460 expression searching or matching had to explicitly save and restore the
1461 match data. Now Emacs does this automatically for filter functions;
1462 they never need to do it explicitly.
1464 Note that Emacs automatically saves and restores the match data
1465 while executing filter functions. @xref{Match Data}.
1467 The output to the filter may come in chunks of any size. A program
1468 that produces the same output twice in a row may send it as one batch of
1469 200 characters one time, and five batches of 40 characters the next. If
1470 the filter looks for certain text strings in the subprocess output, make
1471 sure to handle the case where one of these strings is split across two
1472 or more batches of output; one way to do this is to insert the
1473 received text into a temporary buffer, which can then be searched.
1475 @defun set-process-filter process filter
1476 This function gives @var{process} the filter function @var{filter}. If
1477 @var{filter} is @code{nil}, it gives the process the default filter,
1478 which inserts the process output into the process buffer.
1481 @defun process-filter process
1482 This function returns the filter function of @var{process}.
1485 In case the process's output needs to be passed to several filters, you can
1486 use @code{add-function} to combine an existing filter with a new one.
1487 @xref{Advising Functions}.
1489 Here is an example of the use of a filter function:
1493 (defun keep-output (process output)
1494 (setq kept (cons output kept)))
1495 @result{} keep-output
1502 (set-process-filter (get-process "shell") 'keep-output)
1503 @result{} keep-output
1506 (process-send-string "shell" "ls ~/other\n")
1509 @result{} ("lewis@@slug:$ "
1512 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
1513 address.txt backup.psf kolstad.psf
1514 backup.bib~ david.mss resume-Dec-86.mss~
1515 backup.err david.psf resume-Dec.psf
1516 backup.mss dland syllabus.mss
1518 "#backups.mss# backup.mss~ kolstad.mss
1523 @ignore @c The code in this example doesn't show the right way to do things.
1524 Here is another, more realistic example, which demonstrates how to use
1525 the process mark to do insertion in the same fashion as the default filter:
1529 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
1530 ;; @r{and make sure that buffer is shown in some window.}
1531 (defun my-process-filter (proc str)
1532 (let ((cur (selected-window))
1534 (pop-to-buffer my-shell-buffer)
1537 (goto-char (point-max))
1539 (set-marker (process-mark proc) (point-max))
1540 (select-window cur)))
1545 @node Decoding Output
1546 @subsection Decoding Process Output
1547 @cindex decode process output
1549 When Emacs writes process output directly into a multibyte buffer,
1550 it decodes the output according to the process output coding system.
1551 If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
1552 converts the unibyte output to multibyte using
1553 @code{string-to-multibyte}, and inserts the resulting multibyte text.
1555 You can use @code{set-process-coding-system} to specify which coding
1556 system to use (@pxref{Process Information}). Otherwise, the coding
1557 system comes from @code{coding-system-for-read}, if that is
1558 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
1559 Coding Systems}). If the text output by a process contains null
1560 bytes, Emacs by default uses @code{no-conversion} for it; see
1561 @ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
1562 control this behavior.
1564 @strong{Warning:} Coding systems such as @code{undecided}, which
1565 determine the coding system from the data, do not work entirely
1566 reliably with asynchronous subprocess output. This is because Emacs
1567 has to process asynchronous subprocess output in batches, as it
1568 arrives. Emacs must try to detect the proper coding system from one
1569 batch at a time, and this does not always work. Therefore, if at all
1570 possible, specify a coding system that determines both the character
1571 code conversion and the end of line conversion---that is, one like
1572 @code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
1574 @c Let's keep the index entries that were there for
1575 @c set-process-filter-multibyte and process-filter-multibyte-p,
1576 @cindex filter multibyte flag, of process
1577 @cindex process filter multibyte flag
1578 When Emacs calls a process filter function, it provides the process
1579 output as a multibyte string or as a unibyte string according to the
1580 process's filter coding system. Emacs
1581 decodes the output according to the process output coding system,
1582 which usually produces a multibyte string, except for coding systems
1583 such as @code{binary} and @code{raw-text}.
1585 @node Accepting Output
1586 @subsection Accepting Output from Processes
1587 @cindex accept input from processes
1589 Output from asynchronous subprocesses normally arrives only while
1590 Emacs is waiting for some sort of external event, such as elapsed time
1591 or terminal input. Occasionally it is useful in a Lisp program to
1592 explicitly permit output to arrive at a specific point, or even to wait
1593 until output arrives from a process.
1595 @defun accept-process-output &optional process seconds millisec just-this-one
1596 This function allows Emacs to read pending output from processes. The
1597 output is given to their filter functions. If @var{process} is
1598 non-@code{nil} then this function does not return until some output
1599 has been received from @var{process}.
1601 The arguments @var{seconds} and @var{millisec} let you specify timeout
1602 periods. The former specifies a period measured in seconds and the
1603 latter specifies one measured in milliseconds. The two time periods
1604 thus specified are added together, and @code{accept-process-output}
1605 returns after that much time, even if there is no
1608 The argument @var{millisec} is obsolete (and should not be used),
1609 because @var{seconds} can be floating point to specify
1610 waiting a fractional number of seconds. If @var{seconds} is 0, the
1611 function accepts whatever output is pending but does not wait.
1613 @c Emacs 22.1 feature
1614 If @var{process} is a process, and the argument @var{just-this-one} is
1615 non-@code{nil}, only output from that process is handled, suspending output
1616 from other processes until some output has been received from that
1617 process or the timeout expires. If @var{just-this-one} is an integer,
1618 also inhibit running timers. This feature is generally not
1619 recommended, but may be necessary for specific applications, such as
1622 The function @code{accept-process-output} returns non-@code{nil} if it
1623 got output from @var{process}, or from any process if @var{process} is
1624 @code{nil}. It returns @code{nil} if the timeout expired before output
1629 @section Sentinels: Detecting Process Status Changes
1630 @cindex process sentinel
1631 @cindex sentinel (of process)
1633 A @dfn{process sentinel} is a function that is called whenever the
1634 associated process changes status for any reason, including signals
1635 (whether sent by Emacs or caused by the process's own actions) that
1636 terminate, stop, or continue the process. The process sentinel is
1637 also called if the process exits. The sentinel receives two
1638 arguments: the process for which the event occurred, and a string
1639 describing the type of event.
1641 @cindex default sentinel function of a process
1642 If no sentinel function was specified for a process, it will use the
1643 default sentinel function, which inserts a message in the process's
1644 buffer with the process name and the string describing the event.
1646 The string describing the event looks like one of the following:
1650 @code{"finished\n"}.
1656 @code{"exited abnormally with code @var{exitcode} (core dumped)\n"}.
1657 The ``core dumped'' part is optional, and only appears if the process
1661 @code{"failed with code @var{fail-code}\n"}.
1664 @code{"@var{signal-description} (core dumped)\n"}. The
1665 @var{signal-description} is a system-dependent textual description of
1666 a signal, e.g., @code{"killed"} for @code{SIGKILL}. The ``core
1667 dumped'' part is optional, and only appears if the process dumped
1671 @code{"open from @var{host-name}\n"}.
1677 @code{"connection broken by remote peer\n"}.
1680 A sentinel runs only while Emacs is waiting (e.g., for terminal
1681 input, or for time to elapse, or for process output). This avoids the
1682 timing errors that could result from running sentinels at random places in
1683 the middle of other Lisp programs. A program can wait, so that
1684 sentinels will run, by calling @code{sit-for} or @code{sleep-for}
1685 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
1686 Output}). Emacs also allows sentinels to run when the command loop is
1687 reading input. @code{delete-process} calls the sentinel when it
1688 terminates a running process.
1690 Emacs does not keep a queue of multiple reasons to call the sentinel
1691 of one process; it records just the current status and the fact that
1692 there has been a change. Therefore two changes in status, coming in
1693 quick succession, can call the sentinel just once. However, process
1694 termination will always run the sentinel exactly once. This is
1695 because the process status can't change again after termination.
1697 Emacs explicitly checks for output from the process before running
1698 the process sentinel. Once the sentinel runs due to process
1699 termination, no further output can arrive from the process.
1701 A sentinel that writes the output into the buffer of the process
1702 should check whether the buffer is still alive. If it tries to insert
1703 into a dead buffer, it will get an error. If the buffer is dead,
1704 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
1706 @c Note this text is duplicated in the filter functions section.
1707 Quitting is normally inhibited within a sentinel---otherwise, the
1708 effect of typing @kbd{C-g} at command level or to quit a user command
1709 would be unpredictable. If you want to permit quitting inside a
1710 sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the
1711 right way to do this is with the macro @code{with-local-quit}.
1714 If an error happens during execution of a sentinel, it is caught
1715 automatically, so that it doesn't stop the execution of whatever
1716 programs was running when the sentinel was started. However, if
1717 @code{debug-on-error} is non-@code{nil}, errors are not caught.
1718 This makes it possible to use the Lisp debugger to debug the
1719 sentinel. @xref{Debugger}.
1721 While a sentinel is running, the process sentinel is temporarily
1722 set to @code{nil} so that the sentinel won't run recursively.
1723 For this reason it is not possible for a sentinel to specify
1727 In earlier Emacs versions, every sentinel that did regular expression
1728 searching or matching had to explicitly save and restore the match data.
1729 Now Emacs does this automatically for sentinels; they never need to do
1732 Note that Emacs automatically saves and restores the match data
1733 while executing sentinels. @xref{Match Data}.
1735 @defun set-process-sentinel process sentinel
1736 This function associates @var{sentinel} with @var{process}. If
1737 @var{sentinel} is @code{nil}, then the process will have the default
1738 sentinel, which inserts a message in the process's buffer when the
1739 process status changes.
1741 Changes in process sentinels take effect immediately---if the sentinel
1742 is slated to be run but has not been called yet, and you specify a new
1743 sentinel, the eventual call to the sentinel will use the new one.
1747 (defun msg-me (process event)
1749 (format "Process: %s had the event '%s'" process event)))
1750 (set-process-sentinel (get-process "shell") 'msg-me)
1754 (kill-process (get-process "shell"))
1755 @print{} Process: #<process shell> had the event 'killed'
1756 @result{} #<process shell>
1761 @defun process-sentinel process
1762 This function returns the sentinel of @var{process}.
1765 In case a process status changes need to be passed to several sentinels, you
1766 can use @code{add-function} to combine an existing sentinel with a new one.
1767 @xref{Advising Functions}.
1769 @defun waiting-for-user-input-p
1770 While a sentinel or filter function is running, this function returns
1771 non-@code{nil} if Emacs was waiting for keyboard input from the user at
1772 the time the sentinel or filter function was called, or @code{nil} if it
1776 @node Query Before Exit
1777 @section Querying Before Exit
1779 When Emacs exits, it terminates all its subprocesses by sending them
1780 the @code{SIGHUP} signal. Because subprocesses may be doing
1781 valuable work, Emacs normally asks the user to confirm that it is ok
1782 to terminate them. Each process has a query flag, which, if
1783 non-@code{nil}, says that Emacs should ask for confirmation before
1784 exiting and thus killing that process. The default for the query flag
1785 is @code{t}, meaning @emph{do} query.
1787 @defun process-query-on-exit-flag process
1788 This returns the query flag of @var{process}.
1791 @defun set-process-query-on-exit-flag process flag
1792 This function sets the query flag of @var{process} to @var{flag}. It
1795 Here is an example of using @code{set-process-query-on-exit-flag} on a
1796 shell process to avoid querying:
1800 (set-process-query-on-exit-flag (get-process "shell") nil)
1806 @node System Processes
1807 @section Accessing Other Processes
1808 @cindex system processes
1810 In addition to accessing and manipulating processes that are
1811 subprocesses of the current Emacs session, Emacs Lisp programs can
1812 also access other processes running on the same machine. We call
1813 these @dfn{system processes}, to distinguish them from Emacs
1816 Emacs provides several primitives for accessing system processes.
1817 Not all platforms support these primitives; on those which don't,
1818 these primitives return @code{nil}.
1820 @defun list-system-processes
1821 This function returns a list of all the processes running on the
1822 system. Each process is identified by its @acronym{PID}, a numerical
1823 process ID that is assigned by the OS and distinguishes the process
1824 from all the other processes running on the same machine at the same
1828 @defun process-attributes pid
1829 This function returns an alist of attributes for the process specified
1830 by its process ID @var{pid}. Each association in the alist is of the
1831 form @code{(@var{key} . @var{value})}, where @var{key} designates the
1832 attribute and @var{value} is the value of that attribute. The various
1833 attribute @var{key}s that this function can return are listed below.
1834 Not all platforms support all of these attributes; if an attribute is
1835 not supported, its association will not appear in the returned alist.
1836 Values that are numbers can be either integer or floating point,
1837 depending on the magnitude of the value.
1841 The effective user ID of the user who invoked the process. The
1842 corresponding @var{value} is a number. If the process was invoked by
1843 the same user who runs the current Emacs session, the value is
1844 identical to what @code{user-uid} returns (@pxref{User
1848 User name corresponding to the process's effective user ID, a string.
1851 The group ID of the effective user ID, a number.
1854 Group name corresponding to the effective user's group ID, a string.
1857 The name of the command that runs in the process. This is a string
1858 that usually specifies the name of the executable file of the process,
1859 without the leading directories. However, some special system
1860 processes can report strings that do not correspond to an executable
1864 The state code of the process. This is a short string that encodes
1865 the scheduling state of the process. Here's a list of the most
1866 frequently seen codes:
1870 uninterruptible sleep (usually I/O)
1874 interruptible sleep (waiting for some event)
1876 stopped, e.g., by a job control signal
1878 zombie: a process that terminated, but was not reaped by its parent
1882 For the full list of the possible states, see the manual page of the
1883 @command{ps} command.
1886 The process ID of the parent process, a number.
1889 The process group ID of the process, a number.
1892 The session ID of the process. This is a number that is the process
1893 ID of the process's @dfn{session leader}.
1896 A string that is the name of the process's controlling terminal. On
1897 Unix and GNU systems, this is normally the file name of the
1898 corresponding terminal device, such as @file{/dev/pts65}.
1901 The numerical process group ID of the foreground process group that
1902 uses the process's terminal.
1905 The number of minor page faults caused by the process since its
1906 beginning. (Minor page faults are those that don't involve reading
1910 The number of major page faults caused by the process since its
1911 beginning. (Major page faults require a disk to be read, and are thus
1912 more expensive than minor page faults.)
1916 Like @code{minflt} and @code{majflt}, but include the number of page
1917 faults for all the child processes of the given process.
1920 Time spent by the process in the user context, for running the
1921 application's code. The corresponding @var{value} is in the
1922 @w{@code{(@var{high} @var{low} @var{microsec} @var{picosec})}} format, the same
1923 format used by functions @code{current-time} (@pxref{Time of Day,
1924 current-time}) and @code{file-attributes} (@pxref{File Attributes}).
1927 Time spent by the process in the system (kernel) context, for
1928 processing system calls. The corresponding @var{value} is in the same
1929 format as for @code{utime}.
1932 The sum of @code{utime} and @code{stime}. The corresponding
1933 @var{value} is in the same format as for @code{utime}.
1938 Like @code{utime}, @code{stime}, and @code{time}, but include the
1939 times of all the child processes of the given process.
1942 The numerical priority of the process.
1945 The @dfn{nice value} of the process, a number. (Processes with smaller
1946 nice values get scheduled more favorably.)
1949 The number of threads in the process.
1952 The time when the process was started, in the same
1953 @code{(@var{high} @var{low} @var{microsec} @var{picosec})} format used by
1954 @code{file-attributes} and @code{current-time}.
1957 The time elapsed since the process started, in the format @code{(@var{high}
1958 @var{low} @var{microsec} @var{picosec})}.
1961 The virtual memory size of the process, measured in kilobytes.
1964 The size of the process's @dfn{resident set}, the number of kilobytes
1965 occupied by the process in the machine's physical memory.
1968 The percentage of the CPU time used by the process since it started.
1969 The corresponding @var{value} is a floating-point number between 0 and
1973 The percentage of the total physical memory installed on the machine
1974 used by the process's resident set. The value is a floating-point
1975 number between 0 and 100.
1978 The command-line with which the process was invoked. This is a string
1979 in which individual command-line arguments are separated by blanks;
1980 whitespace characters that are embedded in the arguments are quoted as
1981 appropriate for the system's shell: escaped by backslash characters on
1982 GNU and Unix, and enclosed in double quote characters on Windows.
1983 Thus, this command-line string can be directly used in primitives such
1984 as @code{shell-command}.
1990 @node Transaction Queues
1991 @section Transaction Queues
1992 @cindex transaction queue
1994 @c That's not very informative. What is a transaction, and when might
1995 @c I want to use one?
1996 You can use a @dfn{transaction queue} to communicate with a subprocess
1997 using transactions. First use @code{tq-create} to create a transaction
1998 queue communicating with a specified process. Then you can call
1999 @code{tq-enqueue} to send a transaction.
2001 @defun tq-create process
2002 This function creates and returns a transaction queue communicating with
2003 @var{process}. The argument @var{process} should be a subprocess
2004 capable of sending and receiving streams of bytes. It may be a child
2005 process, or it may be a TCP connection to a server, possibly on another
2009 @defun tq-enqueue queue question regexp closure fn &optional delay-question
2010 This function sends a transaction to queue @var{queue}. Specifying the
2011 queue has the effect of specifying the subprocess to talk to.
2013 The argument @var{question} is the outgoing message that starts the
2014 transaction. The argument @var{fn} is the function to call when the
2015 corresponding answer comes back; it is called with two arguments:
2016 @var{closure}, and the answer received.
2018 The argument @var{regexp} is a regular expression that should match
2019 text at the end of the entire answer, but nothing before; that's how
2020 @code{tq-enqueue} determines where the answer ends.
2022 If the argument @var{delay-question} is non-@code{nil}, delay sending
2023 this question until the process has finished replying to any previous
2024 questions. This produces more reliable results with some processes.
2027 @c Let's not mention it then.
2028 The return value of @code{tq-enqueue} itself is not meaningful.
2032 @defun tq-close queue
2033 Shut down transaction queue @var{queue}, waiting for all pending transactions
2034 to complete, and then terminate the connection or child process.
2037 Transaction queues are implemented by means of a filter function.
2038 @xref{Filter Functions}.
2041 @section Network Connections
2042 @cindex network connection
2046 Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
2047 connections (@pxref{Datagrams}) to other processes on the same machine
2049 A network connection is handled by Lisp much like a subprocess, and is
2050 represented by a process object. However, the process you are
2051 communicating with is not a child of the Emacs process, has no
2052 process @acronym{ID}, and you can't kill it or send it signals. All you
2053 can do is send and receive data. @code{delete-process} closes the
2054 connection, but does not kill the program at the other end; that
2055 program must decide what to do about closure of the connection.
2057 Lisp programs can listen for connections by creating network
2058 servers. A network server is also represented by a kind of process
2059 object, but unlike a network connection, the network server never
2060 transfers data itself. When it receives a connection request, it
2061 creates a new network connection to represent the connection just
2062 made. (The network connection inherits certain information, including
2063 the process plist, from the server.) The network server then goes
2064 back to listening for more connection requests.
2066 Network connections and servers are created by calling
2067 @code{make-network-process} with an argument list consisting of
2068 keyword/argument pairs, for example @code{:server t} to create a
2069 server process, or @code{:type 'datagram} to create a datagram
2070 connection. @xref{Low-Level Network}, for details. You can also use
2071 the @code{open-network-stream} function described below.
2073 To distinguish the different types of processes, the
2074 @code{process-type} function returns the symbol @code{network} for a
2075 network connection or server, @code{serial} for a serial port
2076 connection, or @code{real} for a real subprocess.
2078 The @code{process-status} function returns @code{open},
2079 @code{closed}, @code{connect}, or @code{failed} for network
2080 connections. For a network server, the status is always
2081 @code{listen}. None of those values is possible for a real
2082 subprocess. @xref{Process Information}.
2084 You can stop and resume operation of a network process by calling
2085 @code{stop-process} and @code{continue-process}. For a server
2086 process, being stopped means not accepting new connections. (Up to 5
2087 connection requests will be queued for when you resume the server; you
2088 can increase this limit, unless it is imposed by the operating
2089 system---see the @code{:server} keyword of @code{make-network-process},
2090 @ref{Network Processes}.) For a network stream connection, being
2091 stopped means not processing input (any arriving input waits until you
2092 resume the connection). For a datagram connection, some number of
2093 packets may be queued but input may be lost. You can use the function
2094 @code{process-command} to determine whether a network connection or
2095 server is stopped; a non-@code{nil} value means yes.
2097 @cindex network connection, encrypted
2098 @cindex encrypted network connections
2099 @cindex @acronym{TLS} network connections
2100 @cindex @acronym{STARTTLS} network connections
2101 Emacs can create encrypted network connections, using either built-in
2102 or external support. The built-in support uses the GnuTLS
2103 Transport Layer Security Library; see
2104 @uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}.
2105 If your Emacs was compiled with GnuTLS support, the function
2106 @code{gnutls-available-p} is defined and returns non-@code{nil}. For
2107 more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}.
2108 The external support uses the @file{starttls.el} library, which
2109 requires a helper utility such as @command{gnutls-cli} to be installed
2110 on the system. The @code{open-network-stream} function can
2111 transparently handle the details of creating encrypted connections for
2112 you, using whatever support is available.
2114 @defun open-network-stream name buffer host service &rest parameters
2115 This function opens a TCP connection, with optional encryption, and
2116 returns a process object that represents the connection.
2118 The @var{name} argument specifies the name for the process object. It
2119 is modified as necessary to make it unique.
2121 The @var{buffer} argument is the buffer to associate with the
2122 connection. Output from the connection is inserted in the buffer,
2123 unless you specify your own filter function to handle the output. If
2124 @var{buffer} is @code{nil}, it means that the connection is not
2125 associated with any buffer.
2127 The arguments @var{host} and @var{service} specify where to connect to;
2128 @var{host} is the host name (a string), and @var{service} is the name of
2129 a defined network service (a string) or a port number (an integer).
2131 The remaining arguments @var{parameters} are keyword/argument pairs
2132 that are mainly relevant to encrypted connections:
2136 @item :nowait @var{boolean}
2137 If non-@code{nil}, try to make an asynchronous connection.
2139 @item :type @var{type}
2140 The type of connection. Options are:
2144 An ordinary, unencrypted connection.
2147 A @acronym{TLS} (Transport Layer Security) connection.
2150 Start with a plain connection, and if parameters @samp{:success}
2151 and @samp{:capability-command} are supplied, try to upgrade to an encrypted
2152 connection via @acronym{STARTTLS}. If that fails, retain the
2153 unencrypted connection.
2155 As for @code{nil}, but if @acronym{STARTTLS} fails drop the connection.
2160 @item :always-query-capabilities @var{boolean}
2161 If non-@code{nil}, always ask for the server's capabilities, even when
2162 doing a @samp{plain} connection.
2164 @item :capability-command @var{capability-command}
2165 Command string to query the host capabilities.
2167 @item :end-of-command @var{regexp}
2168 @itemx :end-of-capability @var{regexp}
2169 Regular expression matching the end of a command, or the end of the
2170 command @var{capability-command}. The latter defaults to the former.
2172 @item :starttls-function @var{function}
2173 Function of one argument (the response to @var{capability-command}),
2174 which returns either @code{nil}, or the command to activate @acronym{STARTTLS}
2177 @item :success @var{regexp}
2178 Regular expression matching a successful @acronym{STARTTLS} negotiation.
2180 @item :use-starttls-if-possible @var{boolean}
2181 If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs
2182 doesn't have built-in @acronym{TLS} support.
2184 @item :warn-unless-encrypted @var{boolean}
2185 If non-@code{nil}, and @code{:return-value} is also non-@code{nil},
2186 Emacs will warn if the connection isn't encrypted. This is useful for
2187 protocols like @acronym{IMAP} and the like, where most users would
2188 expect the network traffic to be encrypted.
2190 @item :client-certificate @var{list-or-t}
2191 Either a list of the form @code{(@var{key-file} @var{cert-file})},
2192 naming the certificate key file and certificate file itself, or
2193 @code{t}, meaning to query @code{auth-source} for this information
2194 (@pxref{Top,,Overview, auth, The Auth-Source Manual}).
2195 Only used for @acronym{TLS} or @acronym{STARTTLS}.
2197 @item :return-list @var{cons-or-nil}
2198 The return value of this function. If omitted or @code{nil}, return a
2199 process object. Otherwise, a cons of the form @code{(@var{process-object}
2200 . @var{plist})}, where @var{plist} has keywords:
2203 @item :greeting @var{string-or-nil}
2204 If non-@code{nil}, the greeting string returned by the host.
2205 @item :capabilities @var{string-or-nil}
2206 If non-@code{nil}, the host's capability string.
2207 @item :type @var{symbol}
2208 The connection type: @samp{plain} or @samp{tls}.
2216 @node Network Servers
2217 @section Network Servers
2218 @cindex network servers
2220 You create a server by calling @code{make-network-process}
2221 (@pxref{Network Processes}) with @code{:server t}. The server will
2222 listen for connection requests from clients. When it accepts a client
2223 connection request, that creates a new network connection, itself a
2224 process object, with the following parameters:
2228 The connection's process name is constructed by concatenating the
2229 server process's @var{name} with a client identification string. The
2230 @c FIXME? What about IPv6? Say briefly what the difference is?
2231 client identification string for an IPv4 connection looks like
2232 @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}, which represents an
2233 address and port number. Otherwise, it is a
2234 unique number in brackets, as in @samp{<@var{nnn}>}. The number
2235 is unique for each connection in the Emacs session.
2238 If the server has a non-default filter, the connection process does
2239 not get a separate process buffer; otherwise, Emacs creates a new
2240 buffer for the purpose. The buffer name is the server's buffer name
2241 or process name, concatenated with the client identification string.
2243 The server's process buffer value is never used directly, but the log
2244 function can retrieve it and use it to log connections by inserting
2248 The communication type and the process filter and sentinel are
2249 inherited from those of the server. The server never directly
2250 uses its filter and sentinel; their sole purpose is to initialize
2251 connections made to the server.
2254 The connection's process contact information is set according to the client's
2255 addressing information (typically an IP address and a port number).
2256 This information is associated with the @code{process-contact}
2257 keywords @code{:host}, @code{:service}, @code{:remote}.
2260 The connection's local address is set up according to the port
2261 number used for the connection.
2264 The client process's plist is initialized from the server's plist.
2271 A @dfn{datagram} connection communicates with individual packets rather
2272 than streams of data. Each call to @code{process-send} sends one
2273 datagram packet (@pxref{Input to Processes}), and each datagram
2274 received results in one call to the filter function.
2276 The datagram connection doesn't have to talk with the same remote
2277 peer all the time. It has a @dfn{remote peer address} which specifies
2278 where to send datagrams to. Each time an incoming datagram is passed
2279 to the filter function, the peer address is set to the address that
2280 datagram came from; that way, if the filter function sends a datagram,
2281 it will go back to that place. You can specify the remote peer
2282 address when you create the datagram connection using the
2283 @code{:remote} keyword. You can change it later on by calling
2284 @code{set-process-datagram-address}.
2286 @defun process-datagram-address process
2287 If @var{process} is a datagram connection or server, this function
2288 returns its remote peer address.
2291 @defun set-process-datagram-address process address
2292 If @var{process} is a datagram connection or server, this function
2293 sets its remote peer address to @var{address}.
2296 @node Low-Level Network
2297 @section Low-Level Network Access
2299 You can also create network connections by operating at a lower
2300 level than that of @code{open-network-stream}, using
2301 @code{make-network-process}.
2304 * Proc: Network Processes. Using @code{make-network-process}.
2305 * Options: Network Options. Further control over network connections.
2306 * Features: Network Feature Testing.
2307 Determining which network features work on
2308 the machine you are using.
2311 @node Network Processes
2312 @subsection @code{make-network-process}
2314 The basic function for creating network connections and network
2315 servers is @code{make-network-process}. It can do either of those
2316 jobs, depending on the arguments you give it.
2318 @defun make-network-process &rest args
2319 This function creates a network connection or server and returns the
2320 process object that represents it. The arguments @var{args} are a
2321 list of keyword/argument pairs. Omitting a keyword is always
2322 equivalent to specifying it with value @code{nil}, except for
2323 @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here
2324 are the meaningful keywords (those corresponding to network options
2325 are listed in the following section):
2328 @item :name @var{name}
2329 Use the string @var{name} as the process name. It is modified if
2330 necessary to make it unique.
2332 @item :type @var{type}
2333 Specify the communication type. A value of @code{nil} specifies a
2334 stream connection (the default); @code{datagram} specifies a datagram
2335 connection; @code{seqpacket} specifies a sequenced packet stream
2336 connection. Both connections and servers can be of these types.
2338 @item :server @var{server-flag}
2339 If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
2340 create a connection. For a stream type server, @var{server-flag} may
2341 be an integer, which then specifies the length of the queue of pending
2342 connections to the server. The default queue length is 5.
2344 @item :host @var{host}
2345 Specify the host to connect to. @var{host} should be a host name or
2346 Internet address, as a string, or the symbol @code{local} to specify
2347 the local host. If you specify @var{host} for a server, it must
2348 specify a valid address for the local host, and only clients
2349 connecting to that address will be accepted.
2351 @item :service @var{service}
2352 @var{service} specifies a port number to connect to; or, for a server,
2353 the port number to listen on. It should be a service name that
2354 translates to a port number, or an integer specifying the port number
2355 directly. For a server, it can also be @code{t}, which means to let
2356 the system select an unused port number.
2358 @item :family @var{family}
2359 @var{family} specifies the address (and protocol) family for
2360 communication. @code{nil} means determine the proper address family
2361 automatically for the given @var{host} and @var{service}.
2362 @code{local} specifies a Unix socket, in which case @var{host} is
2363 ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6,
2366 @item :local @var{local-address}
2367 For a server process, @var{local-address} is the address to listen on.
2368 It overrides @var{family}, @var{host} and @var{service}, so you
2369 might as well not specify them.
2371 @item :remote @var{remote-address}
2372 For a connection, @var{remote-address} is the address to connect to.
2373 It overrides @var{family}, @var{host} and @var{service}, so you
2374 might as well not specify them.
2376 For a datagram server, @var{remote-address} specifies the initial
2377 setting of the remote datagram address.
2379 The format of @var{local-address} or @var{remote-address} depends on
2384 An IPv4 address is represented as a five-element vector of four 8-bit
2385 integers and one 16-bit integer
2386 @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to
2387 numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number
2391 An IPv6 address is represented as a nine-element vector of 16-bit
2392 integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f}
2393 @var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address
2394 @var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and
2395 port number @var{p}.
2398 A local address is represented as a string, which specifies the address
2399 in the local address space.
2402 An unsupported-family address is represented by a cons
2403 @code{(@var{f} . @var{av})}, where @var{f} is the family number and
2404 @var{av} is a vector specifying the socket address using one element
2405 per address data byte. Do not rely on this format in portable code,
2406 as it may depend on implementation defined constants, data sizes, and
2407 data structure alignment.
2410 @item :nowait @var{bool}
2411 If @var{bool} is non-@code{nil} for a stream connection, return
2412 without waiting for the connection to complete. When the connection
2413 succeeds or fails, Emacs will call the sentinel function, with a
2414 second argument matching @code{"open"} (if successful) or
2415 @code{"failed"}. The default is to block, so that
2416 @code{make-network-process} does not return until the connection
2417 has succeeded or failed.
2419 @item :stop @var{stopped}
2420 If @var{stopped} is non-@code{nil}, start the network connection or
2421 server in the stopped state.
2423 @item :buffer @var{buffer}
2424 Use @var{buffer} as the process buffer.
2426 @item :coding @var{coding}
2427 Use @var{coding} as the coding system for this process. To specify
2428 different coding systems for decoding data from the connection and for
2429 encoding data sent to it, specify @code{(@var{decoding} .
2430 @var{encoding})} for @var{coding}.
2432 If you don't specify this keyword at all, the default
2433 is to determine the coding systems from the data.
2435 @item :noquery @var{query-flag}
2436 Initialize the process query flag to @var{query-flag}.
2437 @xref{Query Before Exit}.
2439 @item :filter @var{filter}
2440 Initialize the process filter to @var{filter}.
2442 @item :filter-multibyte @var{multibyte}
2443 If @var{multibyte} is non-@code{nil}, strings given to the process
2444 filter are multibyte, otherwise they are unibyte. The default is the
2445 default value of @code{enable-multibyte-characters}.
2447 @item :sentinel @var{sentinel}
2448 Initialize the process sentinel to @var{sentinel}.
2450 @item :log @var{log}
2451 Initialize the log function of a server process to @var{log}. The log
2452 function is called each time the server accepts a network connection
2453 from a client. The arguments passed to the log function are
2454 @var{server}, @var{connection}, and @var{message}; where @var{server}
2455 is the server process, @var{connection} is the new process for the
2456 connection, and @var{message} is a string describing what has
2459 @item :plist @var{plist}
2460 Initialize the process plist to @var{plist}.
2463 The original argument list, modified with the actual connection
2464 information, is available via the @code{process-contact} function.
2467 @node Network Options
2468 @subsection Network Options
2470 The following network options can be specified when you create a
2471 network process. Except for @code{:reuseaddr}, you can also set or
2472 modify these options later, using @code{set-network-process-option}.
2474 For a server process, the options specified with
2475 @code{make-network-process} are not inherited by the client
2476 connections, so you will need to set the necessary options for each
2477 child connection as it is created.
2480 @item :bindtodevice @var{device-name}
2481 If @var{device-name} is a non-empty string identifying a network
2482 interface name (see @code{network-interface-list}), only handle
2483 packets received on that interface. If @var{device-name} is @code{nil}
2484 (the default), handle packets received on any interface.
2486 Using this option may require special privileges on some systems.
2488 @item :broadcast @var{broadcast-flag}
2489 If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
2490 process will receive datagram packet sent to a broadcast address, and
2491 be able to send packets to a broadcast address. This is ignored for a stream
2494 @item :dontroute @var{dontroute-flag}
2495 If @var{dontroute-flag} is non-@code{nil}, the process can only send
2496 to hosts on the same network as the local host.
2498 @item :keepalive @var{keepalive-flag}
2499 If @var{keepalive-flag} is non-@code{nil} for a stream connection,
2500 enable exchange of low-level keep-alive messages.
2502 @item :linger @var{linger-arg}
2503 If @var{linger-arg} is non-@code{nil}, wait for successful
2504 transmission of all queued packets on the connection before it is
2505 deleted (see @code{delete-process}). If @var{linger-arg} is an
2506 integer, it specifies the maximum time in seconds to wait for queued
2507 packets to be sent before closing the connection. The default is
2508 @code{nil}, which means to discard unsent queued packets when the
2511 @c FIXME Where out-of-band data is ...?
2512 @item :oobinline @var{oobinline-flag}
2513 If @var{oobinline-flag} is non-@code{nil} for a stream connection,
2514 receive out-of-band data in the normal data stream. Otherwise, ignore
2517 @item :priority @var{priority}
2518 Set the priority for packets sent on this connection to the integer
2519 @var{priority}. The interpretation of this number is protocol
2520 specific; such as setting the TOS (type of service) field on IP
2521 packets sent on this connection. It may also have system dependent
2522 effects, such as selecting a specific output queue on the network
2525 @item :reuseaddr @var{reuseaddr-flag}
2526 If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
2527 server process, allow this server to reuse a specific port number (see
2528 @code{:service}), unless another process on this host is already
2529 listening on that port. If @var{reuseaddr-flag} is @code{nil}, there
2530 may be a period of time after the last use of that port (by any
2531 process on the host) where it is not possible to make a new server on
2535 @defun set-network-process-option process option value &optional no-error
2536 This function sets or modifies a network option for network process
2537 @var{process}. The accepted options and values are as for
2538 @code{make-network-process}. If @var{no-error} is non-@code{nil},
2539 this function returns @code{nil} instead of signaling an error if
2540 @var{option} is not a supported option. If the function successfully
2541 completes, it returns @code{t}.
2543 The current setting of an option is available via the
2544 @code{process-contact} function.
2547 @node Network Feature Testing
2548 @subsection Testing Availability of Network Features
2550 To test for the availability of a given network feature, use
2551 @code{featurep} like this:
2554 (featurep 'make-network-process '(@var{keyword} @var{value}))
2558 The result of this form is @code{t} if it works to specify
2559 @var{keyword} with value @var{value} in @code{make-network-process}.
2560 Here are some of the @var{keyword}---@var{value} pairs you can test in
2565 Non-@code{nil} if non-blocking connect is supported.
2566 @item (:type datagram)
2567 Non-@code{nil} if datagrams are supported.
2568 @item (:family local)
2569 Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported.
2570 @item (:family ipv6)
2571 Non-@code{nil} if IPv6 is supported.
2573 Non-@code{nil} if the system can select the port for a server.
2576 To test for the availability of a given network option, use
2577 @code{featurep} like this:
2580 (featurep 'make-network-process '@var{keyword})
2584 The accepted @var{keyword} values are @code{:bindtodevice}, etc.
2585 For the complete list, @pxref{Network Options}. This form returns
2586 non-@code{nil} if that particular network option is supported by
2587 @code{make-network-process} (or @code{set-network-process-option}).
2590 @section Misc Network Facilities
2592 These additional functions are useful for creating and operating
2593 on network connections. Note that they are supported only on some
2596 @defun network-interface-list
2597 This function returns a list describing the network interfaces
2598 of the machine you are using. The value is an alist whose
2599 elements have the form @code{(@var{name} . @var{address})}.
2600 @var{address} has the same form as the @var{local-address}
2601 and @var{remote-address} arguments to @code{make-network-process}.
2604 @defun network-interface-info ifname
2605 This function returns information about the network interface named
2606 @var{ifname}. The value is a list of the form
2607 @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
2611 The Internet protocol address.
2613 The broadcast address.
2617 The layer 2 address (Ethernet MAC address, for instance).
2619 The current flags of the interface.
2623 @defun format-network-address address &optional omit-port
2624 This function converts the Lisp representation of a network address to
2627 A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]}
2628 represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port
2629 number @var{p}. @code{format-network-address} converts that to the
2630 string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
2632 A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e}
2633 @var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along
2634 with a port number. @code{format-network-address} converts that to
2636 @code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}.
2638 If the vector does not include the port number, @var{p}, or if
2639 @var{omit-port} is non-@code{nil}, the result does not include the
2640 @code{:@var{p}} suffix.
2644 @section Communicating with Serial Ports
2645 @cindex @file{/dev/tty}
2647 @cindex serial connections
2649 Emacs can communicate with serial ports. For interactive use,
2650 @kbd{M-x serial-term} opens a terminal window. In a Lisp program,
2651 @code{make-serial-process} creates a process object.
2653 The serial port can be configured at run-time, without having to
2654 close and re-open it. The function @code{serial-process-configure}
2655 lets you change the speed, bytesize, and other parameters. In a
2656 terminal window created by @code{serial-term}, you can click on the
2657 mode line for configuration.
2659 A serial connection is represented by a process object, which can be
2660 used in a similar way to a subprocess or network process. You can send and
2661 receive data, and configure the serial port. A serial process object
2662 has no process ID, however, and you can't send signals to it, and the
2663 status codes are different from other types of processes.
2664 @code{delete-process} on the process object or @code{kill-buffer} on
2665 the process buffer close the connection, but this does not affect the
2666 device connected to the serial port.
2668 The function @code{process-type} returns the symbol @code{serial}
2669 for a process object representing a serial port connection.
2671 Serial ports are available on GNU/Linux, Unix, and MS Windows systems.
2673 @deffn Command serial-term port speed
2674 Start a terminal-emulator for a serial port in a new buffer.
2675 @var{port} is the name of the serial port to connect to. For
2676 example, this could be @file{/dev/ttyS0} on Unix. On MS Windows, this
2677 could be @file{COM1}, or @file{\\.\COM10} (double the backslashes in
2680 @c FIXME is 9600 still the most common value, or is it 115200 now?
2681 @c (Same value, 9600, appears below as well.)
2682 @var{speed} is the speed of the serial port in bits per second. 9600
2683 is a common value. The buffer is in Term mode; see @ref{Term Mode,,,
2684 emacs, The GNU Emacs Manual}, for the commands to use in that buffer.
2685 You can change the speed and the configuration in the mode line menu.
2688 @defun make-serial-process &rest args
2689 This function creates a process and a buffer. Arguments are specified
2690 as keyword/argument pairs. Here's the list of the meaningful
2691 keywords, with the first two (@var{port} and @var{speed}) being mandatory:
2694 @item :port @var{port}
2695 This is the name of the serial port. On Unix and GNU systems, this is
2696 a file name such as @file{/dev/ttyS0}. On Windows, this could be
2697 @file{COM1}, or @file{\\.\COM10} for ports higher than @file{COM9}
2698 (double the backslashes in Lisp strings).
2700 @item :speed @var{speed}
2701 The speed of the serial port in bits per second. This function calls
2702 @code{serial-process-configure} to handle the speed; see the
2703 following documentation of that function for more details.
2705 @item :name @var{name}
2706 The name of the process. If @var{name} is not given, @var{port} will
2707 serve as the process name as well.
2709 @item :buffer @var{buffer}
2710 The buffer to associate with the process. The value can be either a
2711 buffer or a string that names a buffer. Process output goes at the
2712 end of that buffer, unless you specify an output stream or filter
2713 function to handle the output. If @var{buffer} is not given, the
2714 process buffer's name is taken from the value of the @code{:name}
2717 @item :coding @var{coding}
2718 If @var{coding} is a symbol, it specifies the coding system used for
2719 both reading and writing for this process. If @var{coding} is a cons
2720 @code{(@var{decoding} . @var{encoding})}, @var{decoding} is used for
2721 reading, and @var{encoding} is used for writing. If not specified,
2722 the default is to determine the coding systems from the data itself.
2724 @item :noquery @var{query-flag}
2725 Initialize the process query flag to @var{query-flag}. @xref{Query
2726 Before Exit}. The flags defaults to @code{nil} if unspecified.
2728 @item :stop @var{bool}
2729 Start process in the stopped state if @var{bool} is
2730 non-@code{nil}. In the stopped state, a serial process does not
2731 accept incoming data, but you can send outgoing data. The stopped
2732 state is cleared by @code{continue-process} and set by
2733 @code{stop-process}.
2735 @item :filter @var{filter}
2736 Install @var{filter} as the process filter.
2738 @item :sentinel @var{sentinel}
2739 Install @var{sentinel} as the process sentinel.
2741 @item :plist @var{plist}
2742 Install @var{plist} as the initial plist of the process.
2748 These are handled by @code{serial-process-configure}, which is called
2749 by @code{make-serial-process}.
2752 The original argument list, possibly modified by later configuration,
2753 is available via the function @code{process-contact}.
2758 (make-serial-process :port "/dev/ttyS0" :speed 9600)
2762 @defun serial-process-configure &rest args
2763 @cindex baud, in serial connections
2764 @cindex bytesize, in serial connections
2765 @cindex parity, in serial connections
2766 @cindex stopbits, in serial connections
2767 @cindex flowcontrol, in serial connections
2769 This function configures a serial port connection. Arguments are
2770 specified as keyword/argument pairs. Attributes that are not given
2771 are re-initialized from the process's current configuration (available
2772 via the function @code{process-contact}), or set to reasonable default
2773 values. The following arguments are defined:
2776 @item :process @var{process}
2777 @itemx :name @var{name}
2778 @itemx :buffer @var{buffer}
2779 @itemx :port @var{port}
2780 Any of these arguments can be given to identify the process that is to
2781 be configured. If none of these arguments is given, the current
2782 buffer's process is used.
2784 @item :speed @var{speed}
2785 The speed of the serial port in bits per second, a.k.a.@: @dfn{baud
2786 rate}. The value can be any number, but most serial ports work only
2787 at a few defined values between 1200 and 115200, with 9600 being the
2788 most common value. If @var{speed} is @code{nil}, the function ignores
2789 all other arguments and does not configure the port. This may be
2790 useful for special serial ports such as Bluetooth-to-serial converters,
2791 which can only be configured through @samp{AT} commands sent through the
2792 connection. The value of @code{nil} for @var{speed} is valid only for
2793 connections that were already opened by a previous call to
2794 @code{make-serial-process} or @code{serial-term}.
2796 @item :bytesize @var{bytesize}
2797 The number of bits per byte, which can be 7 or 8. If @var{bytesize}
2798 is not given or @code{nil}, it defaults to 8.
2800 @item :parity @var{parity}
2801 The value can be @code{nil} (don't use parity), the symbol
2802 @code{odd} (use odd parity), or the symbol @code{even} (use even
2803 parity). If @var{parity} is not given, it defaults to no parity.
2805 @item :stopbits @var{stopbits}
2806 The number of stopbits used to terminate a transmission
2807 of each byte. @var{stopbits} can be 1 or 2. If @var{stopbits} is not
2808 given or @code{nil}, it defaults to 1.
2810 @item :flowcontrol @var{flowcontrol}
2811 The type of flow control to use for this connection, which is either
2812 @code{nil} (don't use flow control), the symbol @code{hw} (use RTS/CTS
2813 hardware flow control), or the symbol @code{sw} (use XON/XOFF software
2814 flow control). If @var{flowcontrol} is not given, it defaults to no
2818 Internally, @code{make-serial-process} calls
2819 @code{serial-process-configure} for the initial configuration of the
2824 @section Packing and Unpacking Byte Arrays
2825 @cindex byte packing and unpacking
2827 This section describes how to pack and unpack arrays of bytes,
2828 usually for binary network protocols. These functions convert byte arrays
2829 to alists, and vice versa. The byte array can be represented as a
2830 @c FIXME? No multibyte?
2831 unibyte string or as a vector of integers, while the alist associates
2832 symbols either with fixed-size objects or with recursive sub-alists.
2833 To use the functions referred to in this section, load the
2834 @code{bindat} library.
2835 @c It doesn't have any autoloads.
2838 @cindex deserializing
2841 Conversion from byte arrays to nested alists is also known as
2842 @dfn{deserializing} or @dfn{unpacking}, while going in the opposite
2843 direction is also known as @dfn{serializing} or @dfn{packing}.
2846 * Bindat Spec:: Describing data layout.
2847 * Bindat Functions:: Doing the unpacking and packing.
2848 * Bindat Examples:: Samples of what bindat.el can do for you!
2852 @subsection Describing Data Layout
2854 To control unpacking and packing, you write a @dfn{data layout
2855 specification}, a special nested list describing named and typed
2856 @dfn{fields}. This specification controls the length of each field to be
2857 processed, and how to pack or unpack it. We normally keep bindat specs
2858 in variables whose names end in @samp{-bindat-spec}; that kind of name
2859 is automatically recognized as risky.
2863 @cindex little endian
2864 @cindex network byte ordering
2865 A field's @dfn{type} describes the size (in bytes) of the object
2866 that the field represents and, in the case of multibyte fields, how
2867 the bytes are ordered within the field. The two possible orderings
2868 are @dfn{big endian} (also known as ``network byte ordering'') and
2869 @dfn{little endian}. For instance, the number @code{#x23cd} (decimal
2870 9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
2871 and in little endian, @code{#xcd} @code{#x23}. Here are the possible
2877 Unsigned byte, with length 1.
2882 Unsigned integer in network byte order, with length 2.
2885 Unsigned integer in network byte order, with length 3.
2890 Unsigned integer in network byte order, with length 4.
2891 Note: These values may be limited by Emacs's integer implementation limits.
2896 Unsigned integer in little endian order, with length 2, 3 and 4, respectively.
2899 String of length @var{len}.
2901 @item strz @var{len}
2902 Zero-terminated string, in a fixed-size field with length @var{len}.
2904 @item vec @var{len} [@var{type}]
2905 Vector of @var{len} elements of type @var{type}, defaulting to bytes.
2906 The @var{type} is any of the simple types above, or another vector
2907 specified as a list of the form @code{(vec @var{len} [@var{type}])}.
2911 Four-byte vector representing an Internet address. For example:
2912 @code{[127 0 0 1]} for localhost.
2914 @item bits @var{len}
2915 List of set bits in @var{len} bytes. The bytes are taken in big
2916 endian order and the bits are numbered starting with @code{8 *
2917 @var{len} @minus{} 1} and ending with zero. For example: @code{bits
2918 2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and
2919 @code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}.
2921 @item (eval @var{form})
2922 @var{form} is a Lisp expression evaluated at the moment the field is
2923 unpacked or packed. The result of the evaluation should be one of the
2924 above-listed type specifications.
2927 For a fixed-size field, the length @var{len} is given as an integer
2928 specifying the number of bytes in the field.
2930 When the length of a field is not fixed, it typically depends on the
2931 value of a preceding field. In this case, the length @var{len} can be
2932 given either as a list @code{(@var{name} ...)} identifying a
2933 @dfn{field name} in the format specified for @code{bindat-get-field}
2934 below, or by an expression @code{(eval @var{form})} where @var{form}
2935 should evaluate to an integer, specifying the field length.
2937 A field specification generally has the form @code{([@var{name}]
2938 @var{handler})}, where @var{name} is optional. Don't use names that
2939 are symbols meaningful as type specifications (above) or handler
2940 specifications (below), since that would be ambiguous. @var{name} can
2941 be a symbol or an expression @code{(eval @var{form})}, in which case
2942 @var{form} should evaluate to a symbol.
2944 @var{handler} describes how to unpack or pack the field and can be one
2949 Unpack/pack this field according to the type specification @var{type}.
2951 @item eval @var{form}
2952 Evaluate @var{form}, a Lisp expression, for side-effect only. If the
2953 field name is specified, the value is bound to that field name.
2955 @item fill @var{len}
2956 Skip @var{len} bytes. In packing, this leaves them unchanged,
2957 which normally means they remain zero. In unpacking, this means
2960 @item align @var{len}
2961 Skip to the next multiple of @var{len} bytes.
2963 @item struct @var{spec-name}
2964 Process @var{spec-name} as a sub-specification. This describes a
2965 structure nested within another structure.
2967 @item union @var{form} (@var{tag} @var{spec})@dots{}
2968 @c ??? I don't see how one would actually use this.
2969 @c ??? what kind of expression would be useful for @var{form}?
2970 Evaluate @var{form}, a Lisp expression, find the first @var{tag}
2971 that matches it, and process its associated data layout specification
2972 @var{spec}. Matching can occur in one of three ways:
2976 If a @var{tag} has the form @code{(eval @var{expr})}, evaluate
2977 @var{expr} with the variable @code{tag} dynamically bound to the value
2978 of @var{form}. A non-@code{nil} result indicates a match.
2981 @var{tag} matches if it is @code{equal} to the value of @var{form}.
2984 @var{tag} matches unconditionally if it is @code{t}.
2987 @item repeat @var{count} @var{field-specs}@dots{}
2988 Process the @var{field-specs} recursively, in order, then repeat
2989 starting from the first one, processing all the specifications @var{count}
2990 times overall. The @var{count} is given using the same formats as a
2991 field length---if an @code{eval} form is used, it is evaluated just once.
2992 For correct operation, each specification in @var{field-specs} must
2996 For the @code{(eval @var{form})} forms used in a bindat specification,
2997 the @var{form} can access and update these dynamically bound variables
3002 Value of the last field processed.
3005 The data as a byte array.
3008 Current index (within @code{bindat-raw}) for unpacking or packing.
3011 The alist containing the structured data that have been unpacked so
3012 far, or the entire structure being packed. You can use
3013 @code{bindat-get-field} to access specific fields of this structure.
3017 Inside a @code{repeat} block, these contain the maximum number of
3018 repetitions (as specified by the @var{count} parameter), and the
3019 current repetition number (counting from 0). Setting @code{count} to
3020 zero will terminate the inner-most repeat block after the current
3021 repetition has completed.
3024 @node Bindat Functions
3025 @subsection Functions to Unpack and Pack Bytes
3027 In the following documentation, @var{spec} refers to a data layout
3028 specification, @code{bindat-raw} to a byte array, and @var{struct} to an
3029 alist representing unpacked field data.
3031 @defun bindat-unpack spec bindat-raw &optional bindat-idx
3032 @c FIXME? Again, no multibyte?
3033 This function unpacks data from the unibyte string or byte
3034 array @code{bindat-raw}
3035 according to @var{spec}. Normally, this starts unpacking at the
3036 beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it
3037 specifies a zero-based starting position to use instead.
3039 The value is an alist or nested alist in which each element describes
3043 @defun bindat-get-field struct &rest name
3044 This function selects a field's data from the nested alist
3045 @var{struct}. Usually @var{struct} was returned by
3046 @code{bindat-unpack}. If @var{name} corresponds to just one argument,
3047 that means to extract a top-level field value. Multiple @var{name}
3048 arguments specify repeated lookup of sub-structures. An integer name
3049 acts as an array index.
3051 For example, if @var{name} is @code{(a b 2 c)}, that means to find
3052 field @code{c} in the third element of subfield @code{b} of field
3053 @code{a}. (This corresponds to @code{struct.a.b[2].c} in C.)
3056 Although packing and unpacking operations change the organization of
3057 data (in memory), they preserve the data's @dfn{total length}, which is
3058 the sum of all the fields' lengths, in bytes. This value is not
3059 generally inherent in either the specification or alist alone; instead,
3060 both pieces of information contribute to its calculation. Likewise, the
3061 length of a string or array being unpacked may be longer than the data's
3062 total length as described by the specification.
3064 @defun bindat-length spec struct
3065 This function returns the total length of the data in @var{struct},
3066 according to @var{spec}.
3069 @defun bindat-pack spec struct &optional bindat-raw bindat-idx
3070 This function returns a byte array packed according to @var{spec} from
3071 the data in the alist @var{struct}. It normally creates and fills a
3072 new byte array starting at the beginning. However, if @var{bindat-raw}
3073 is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to
3074 pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting
3075 offset for packing into @code{bindat-raw}.
3077 When pre-allocating, you should make sure @code{(length @var{bindat-raw})}
3078 meets or exceeds the total length to avoid an out-of-range error.
3081 @defun bindat-ip-to-string ip
3082 Convert the Internet address vector @var{ip} to a string in the usual
3084 @c FIXME? Does it do IPv6?
3087 (bindat-ip-to-string [127 0 0 1])
3088 @result{} "127.0.0.1"
3092 @node Bindat Examples
3093 @subsection Examples of Byte Unpacking and Packing
3094 @c FIXME? This seems a very long example for something that is not used
3095 @c very often. As of 24.1, gdb-mi.el is the only user of bindat.el in Emacs.
3096 @c Maybe one or both of these examples should just be moved to the
3097 @c commentary of bindat.el.
3099 Here is a complete example of byte unpacking and packing:
3104 (defvar fcookie-index-spec
3112 (:offset repeat (:count) (:foo u32)))
3113 "Description of a fortune cookie index file's contents.")
3115 (defun fcookie (cookies &optional index)
3116 "Display a random fortune cookie from file COOKIES.
3117 Optional second arg INDEX specifies the associated index
3118 filename, by default \"COOKIES.dat\". Display cookie text
3119 in buffer \"*Fortune Cookie: BASENAME*\", where BASENAME
3120 is COOKIES without the directory part."
3121 (interactive "fCookies file: ")
3122 (let* ((info (with-temp-buffer
3123 (insert-file-contents-literally
3124 (or index (concat cookies ".dat")))
3125 (bindat-unpack fcookie-index-spec
3127 (sel (random (bindat-get-field info :count)))
3128 (beg (cdar (bindat-get-field info :offset sel)))
3129 (end (or (cdar (bindat-get-field info
3131 (nth 7 (file-attributes cookies)))))
3134 (format "*Fortune Cookie: %s*"
3135 (file-name-nondirectory cookies))))
3137 (insert-file-contents-literally
3138 cookies nil beg (- end 3))))
3140 (defun fcookie-create-index (cookies &optional index delim)
3141 "Scan file COOKIES, and write out its index file.
3142 Optional arg INDEX specifies the index filename, which by
3143 default is \"COOKIES.dat\". Optional arg DELIM specifies the
3144 unibyte character that, when found on a line of its own in
3145 COOKIES, indicates the border between entries."
3146 (interactive "fCookies file: ")
3147 (setq delim (or delim ?%))
3148 (let ((delim-line (format "\n%c\n" delim))
3151 min p q len offsets)
3152 (unless (= 3 (string-bytes delim-line))
3153 (error "Delimiter cannot be represented in one byte"))
3155 (insert-file-contents-literally cookies)
3156 (while (and (setq p (point))
3157 (search-forward delim-line (point-max) t)
3158 (setq len (- (point) 3 p)))
3159 (setq count (1+ count)
3161 min (min (or min max) len)
3162 offsets (cons (1- p) offsets))))
3164 (set-buffer-multibyte nil)
3174 (:offset . ,(mapcar (lambda (o)
3175 (list (cons :foo o)))
3176 (nreverse offsets))))))
3177 (let ((coding-system-for-write 'raw-text-unix))
3178 (write-file (or index (concat cookies ".dat")))))))
3181 The following is an example of defining and unpacking a complex
3182 structure. Consider the following C structures:
3186 unsigned long dest_ip;
3187 unsigned long src_ip;
3188 unsigned short dest_port;
3189 unsigned short src_port;
3194 unsigned char opcode;
3195 unsigned short length; /* in network byte order */
3196 unsigned char id[8]; /* null-terminated string */
3197 unsigned char data[/* (length + 3) & ~3 */];
3201 struct header header;
3202 unsigned long counters[2]; /* in little endian order */
3203 unsigned char items;
3204 unsigned char filler[3];
3205 struct data item[/* items */];
3210 The corresponding data layout specification is:
3222 (length u16) ; network byte order
3228 '((header struct header-spec)
3229 (counters vec 2 u32r) ; little endian order
3232 (item repeat (items)
3233 (struct data-spec))))
3236 A binary data representation is:
3240 [ 192 168 1 100 192 168 1 101 01 28 21 32
3241 160 134 1 0 5 1 0 0 2 0 0 0
3242 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
3243 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
3246 The corresponding decoded structure is:
3249 (setq decoded (bindat-unpack packet-spec binary-data))
3252 (dest-ip . [192 168 1 100])
3253 (src-ip . [192 168 1 101])
3256 (counters . [100000 261])
3258 (item ((data . [1 2 3 4 5])
3263 ((data . [6 7 8 9 10 11 12])
3270 An example of fetching data from this structure:
3273 (bindat-get-field decoded 'item 1 'id)