2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2016 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
1142 of its terminal to its own child process. If this is true, the
1143 function returns the numeric ID of the foreground process group of
1144 @var{process}; it returns @code{nil} if Emacs can be certain that this
1145 is not so. The value is @code{t} if Emacs cannot tell whether this is
1149 @node Signals to Processes
1150 @section Sending Signals to Processes
1151 @cindex process signals
1152 @cindex sending signals
1155 @dfn{Sending a signal} to a subprocess is a way of interrupting its
1156 activities. There are several different signals, each with its own
1157 meaning. The set of signals and their names is defined by the operating
1158 system. For example, the signal @code{SIGINT} means that the user has
1159 typed @kbd{C-c}, or that some analogous thing has happened.
1161 Each signal has a standard effect on the subprocess. Most signals
1162 kill the subprocess, but some stop (or resume) execution instead. Most
1163 signals can optionally be handled by programs; if the program handles
1164 the signal, then we can say nothing in general about its effects.
1166 You can send signals explicitly by calling the functions in this
1167 section. Emacs also sends signals automatically at certain times:
1168 killing a buffer sends a @code{SIGHUP} signal to all its associated
1169 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
1170 processes. (@code{SIGHUP} is a signal that usually indicates that the
1171 user ``hung up the phone'', i.e., disconnected.)
1173 Each of the signal-sending functions takes two optional arguments:
1174 @var{process} and @var{current-group}.
1176 The argument @var{process} must be either a process, a process
1177 name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name
1178 stands for a process through @code{get-buffer-process}. @code{nil}
1179 stands for the process associated with the current buffer. An error
1180 is signaled if @var{process} does not identify a process.
1182 The argument @var{current-group} is a flag that makes a difference
1183 when you are running a job-control shell as an Emacs subprocess. If it
1184 is non-@code{nil}, then the signal is sent to the current process-group
1185 of the terminal that Emacs uses to communicate with the subprocess. If
1186 the process is a job-control shell, this means the shell's current
1187 subjob. If it is @code{nil}, the signal is sent to the process group of
1188 the immediate subprocess of Emacs. If the subprocess is a job-control
1189 shell, this is the shell itself.
1191 The flag @var{current-group} has no effect when a pipe is used to
1192 communicate with the subprocess, because the operating system does not
1193 support the distinction in the case of pipes. For the same reason,
1194 job-control shells won't work when a pipe is used. See
1195 @code{process-connection-type} in @ref{Asynchronous Processes}.
1197 @defun interrupt-process &optional process current-group
1198 This function interrupts the process @var{process} by sending the
1199 signal @code{SIGINT}. Outside of Emacs, typing the interrupt
1200 character (normally @kbd{C-c} on some systems, and @key{DEL} on
1201 others) sends this signal. When the argument @var{current-group} is
1202 non-@code{nil}, you can think of this function as typing @kbd{C-c}
1203 on the terminal by which Emacs talks to the subprocess.
1206 @defun kill-process &optional process current-group
1207 This function kills the process @var{process} by sending the
1208 signal @code{SIGKILL}. This signal kills the subprocess immediately,
1209 and cannot be handled by the subprocess.
1212 @defun quit-process &optional process current-group
1213 This function sends the signal @code{SIGQUIT} to the process
1214 @var{process}. This signal is the one sent by the quit
1215 character (usually @kbd{C-\}) when you are not inside
1219 @defun stop-process &optional process current-group
1220 This function stops the process @var{process} by sending the
1221 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
1224 Outside of Emacs, on systems with job control, the stop character
1225 (usually @kbd{C-z}) normally sends this signal. When
1226 @var{current-group} is non-@code{nil}, you can think of this function as
1227 typing @kbd{C-z} on the terminal Emacs uses to communicate with the
1231 @defun continue-process &optional process current-group
1232 This function resumes execution of the process @var{process} by sending
1233 it the signal @code{SIGCONT}. This presumes that @var{process} was
1237 @deffn Command signal-process process signal
1238 This function sends a signal to process @var{process}. The argument
1239 @var{signal} specifies which signal to send; it should be an integer,
1240 or a symbol whose name is a signal.
1242 The @var{process} argument can be a system process @acronym{ID} (an
1243 integer); that allows you to send signals to processes that are not
1244 children of Emacs. @xref{System Processes}.
1247 @node Output from Processes
1248 @section Receiving Output from Processes
1249 @cindex process output
1250 @cindex output from processes
1252 The output that a subprocess writes to its standard output stream
1253 is passed to a function called the @dfn{filter function}. The default
1254 filter function simply inserts the output into a buffer, which is
1255 called the associated buffer of the process (@pxref{Process
1256 Buffers}). If the process has no buffer then the default filter
1257 discards the output.
1259 When a subprocess terminates, Emacs reads any pending output,
1260 then stops reading output from that subprocess. Therefore, if the
1261 subprocess has children that are still live and still producing
1262 output, Emacs won't receive that output.
1264 Output from a subprocess can arrive only while Emacs is waiting: when
1265 reading terminal input (see the function @code{waiting-for-user-input-p}),
1266 in @code{sit-for} and @code{sleep-for} (@pxref{Waiting}), and in
1267 @code{accept-process-output} (@pxref{Accepting Output}). This
1268 minimizes the problem of timing errors that usually plague parallel
1269 programming. For example, you can safely create a process and only
1270 then specify its buffer or filter function; no output can arrive
1271 before you finish, if the code in between does not call any primitive
1274 @defvar process-adaptive-read-buffering
1275 On some systems, when Emacs reads the output from a subprocess, the
1276 output data is read in very small blocks, potentially resulting in
1277 very poor performance. This behavior can be remedied to some extent
1278 by setting the variable @code{process-adaptive-read-buffering} to a
1279 non-@code{nil} value (the default), as it will automatically delay reading
1280 from such processes, thus allowing them to produce more output before
1281 Emacs tries to read it.
1284 It is impossible to separate the standard output and standard error
1285 streams of the subprocess, because Emacs normally spawns the subprocess
1286 inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If
1287 you want to keep the output to those streams separate, you should
1288 redirect one of them to a file---for example, by using an appropriate
1292 * Process Buffers:: By default, output is put in a buffer.
1293 * Filter Functions:: Filter functions accept output from the process.
1294 * Decoding Output:: Filters can get unibyte or multibyte strings.
1295 * Accepting Output:: How to wait until process output arrives.
1298 @node Process Buffers
1299 @subsection Process Buffers
1301 A process can (and usually does) have an @dfn{associated buffer},
1302 which is an ordinary Emacs buffer that is used for two purposes: storing
1303 the output from the process, and deciding when to kill the process. You
1304 can also use the buffer to identify a process to operate on, since in
1305 normal practice only one process is associated with any given buffer.
1306 Many applications of processes also use the buffer for editing input to
1307 be sent to the process, but this is not built into Emacs Lisp.
1309 By default, process output is inserted in the associated buffer.
1310 (You can change this by defining a custom filter function,
1311 @pxref{Filter Functions}.) The position to insert the output is
1312 determined by the @code{process-mark}, which is then updated to point
1313 to the end of the text just inserted. Usually, but not always, the
1314 @code{process-mark} is at the end of the buffer.
1316 @findex process-kill-buffer-query-function
1317 Killing the associated buffer of a process also kills the process.
1318 Emacs asks for confirmation first, if the process's
1319 @code{process-query-on-exit-flag} is non-@code{nil} (@pxref{Query
1320 Before Exit}). This confirmation is done by the function
1321 @code{process-kill-buffer-query-function}, which is run from
1322 @code{kill-buffer-query-functions} (@pxref{Killing Buffers}).
1324 @defun process-buffer process
1325 This function returns the associated buffer of the process
1330 (process-buffer (get-process "shell"))
1331 @result{} #<buffer *shell*>
1336 @defun process-mark process
1337 This function returns the process marker for @var{process}, which is the
1338 marker that says where to insert output from the process.
1340 If @var{process} does not have a buffer, @code{process-mark} returns a
1341 marker that points nowhere.
1343 The default filter function uses this marker to decide where to
1344 insert process output, and updates it to point after the inserted text.
1345 That is why successive batches of output are inserted consecutively.
1347 Custom filter functions normally should use this marker in the same fashion.
1348 For an example of a filter function that uses @code{process-mark},
1349 @pxref{Process Filter Example}.
1351 When the user is expected to enter input in the process buffer for
1352 transmission to the process, the process marker separates the new input
1353 from previous output.
1356 @defun set-process-buffer process buffer
1357 This function sets the buffer associated with @var{process} to
1358 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
1359 associated with no buffer.
1362 @defun get-buffer-process buffer-or-name
1363 This function returns a nondeleted process associated with the buffer
1364 specified by @var{buffer-or-name}. If there are several processes
1365 associated with it, this function chooses one (currently, the one most
1366 recently created, but don't count on that). Deletion of a process
1367 (see @code{delete-process}) makes it ineligible for this function to
1370 It is usually a bad idea to have more than one process associated with
1375 (get-buffer-process "*shell*")
1376 @result{} #<process shell>
1380 Killing the process's buffer deletes the process, which kills the
1381 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
1384 @node Filter Functions
1385 @subsection Process Filter Functions
1386 @cindex filter function
1387 @cindex process filter
1389 @cindex default filter function of a process
1390 A process @dfn{filter function} is a function that receives the
1391 standard output from the associated process. @emph{All} output from
1392 that process is passed to the filter. The default filter simply
1393 outputs directly to the process buffer.
1395 The filter function can only be called when Emacs is waiting for
1396 something, because process output arrives only at such times. Emacs
1397 waits when reading terminal input (see the function
1398 @code{waiting-for-user-input-p}), in @code{sit-for} and
1399 @code{sleep-for} (@pxref{Waiting}), and in
1400 @code{accept-process-output} (@pxref{Accepting Output}).
1402 A filter function must accept two arguments: the associated process
1403 and a string, which is output just received from it. The function is
1404 then free to do whatever it chooses with the output.
1406 @c Note this text is duplicated in the sentinels section.
1407 Quitting is normally inhibited within a filter function---otherwise,
1408 the effect of typing @kbd{C-g} at command level or to quit a user
1409 command would be unpredictable. If you want to permit quitting inside
1410 a filter function, bind @code{inhibit-quit} to @code{nil}. In most
1411 cases, the right way to do this is with the macro
1412 @code{with-local-quit}. @xref{Quitting}.
1414 If an error happens during execution of a filter function, it is
1415 caught automatically, so that it doesn't stop the execution of whatever
1416 program was running when the filter function was started. However, if
1417 @code{debug-on-error} is non-@code{nil}, errors are not caught.
1418 This makes it possible to use the Lisp debugger to debug the
1419 filter function. @xref{Debugger}.
1421 Many filter functions sometimes (or always) insert the output in the
1422 process's buffer, mimicking the actions of the default filter.
1423 Such filter functions need to make sure that they save the
1424 current buffer, select the correct buffer (if different) before
1425 inserting output, and then restore the original buffer.
1426 They should also check whether the buffer is still alive, update the
1427 process marker, and in some cases update the value of point. Here is
1428 how to do these things:
1430 @anchor{Process Filter Example}
1433 (defun ordinary-insertion-filter (proc string)
1434 (when (buffer-live-p (process-buffer proc))
1435 (with-current-buffer (process-buffer proc)
1436 (let ((moving (= (point) (process-mark proc))))
1440 ;; @r{Insert the text, advancing the process marker.}
1441 (goto-char (process-mark proc))
1443 (set-marker (process-mark proc) (point)))
1444 (if moving (goto-char (process-mark proc)))))))
1448 To make the filter force the process buffer to be visible whenever new
1449 text arrives, you could insert a line like the following just before the
1450 @code{with-current-buffer} construct:
1453 (display-buffer (process-buffer proc))
1456 To force point to the end of the new output, no matter where it was
1457 previously, eliminate the variable @code{moving} and call
1458 @code{goto-char} unconditionally.
1461 In earlier Emacs versions, every filter function that did regular
1462 expression searching or matching had to explicitly save and restore the
1463 match data. Now Emacs does this automatically for filter functions;
1464 they never need to do it explicitly.
1466 Note that Emacs automatically saves and restores the match data
1467 while executing filter functions. @xref{Match Data}.
1469 The output to the filter may come in chunks of any size. A program
1470 that produces the same output twice in a row may send it as one batch of
1471 200 characters one time, and five batches of 40 characters the next. If
1472 the filter looks for certain text strings in the subprocess output, make
1473 sure to handle the case where one of these strings is split across two
1474 or more batches of output; one way to do this is to insert the
1475 received text into a temporary buffer, which can then be searched.
1477 @defun set-process-filter process filter
1478 This function gives @var{process} the filter function @var{filter}. If
1479 @var{filter} is @code{nil}, it gives the process the default filter,
1480 which inserts the process output into the process buffer.
1483 @defun process-filter process
1484 This function returns the filter function of @var{process}.
1487 In case the process's output needs to be passed to several filters, you can
1488 use @code{add-function} to combine an existing filter with a new one.
1489 @xref{Advising Functions}.
1491 Here is an example of the use of a filter function:
1495 (defun keep-output (process output)
1496 (setq kept (cons output kept)))
1497 @result{} keep-output
1504 (set-process-filter (get-process "shell") 'keep-output)
1505 @result{} keep-output
1508 (process-send-string "shell" "ls ~/other\n")
1511 @result{} ("lewis@@slug:$ "
1514 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
1515 address.txt backup.psf kolstad.psf
1516 backup.bib~ david.mss resume-Dec-86.mss~
1517 backup.err david.psf resume-Dec.psf
1518 backup.mss dland syllabus.mss
1520 "#backups.mss# backup.mss~ kolstad.mss
1525 @ignore @c The code in this example doesn't show the right way to do things.
1526 Here is another, more realistic example, which demonstrates how to use
1527 the process mark to do insertion in the same fashion as the default filter:
1531 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
1532 ;; @r{and make sure that buffer is shown in some window.}
1533 (defun my-process-filter (proc str)
1534 (let ((cur (selected-window))
1536 (pop-to-buffer my-shell-buffer)
1539 (goto-char (point-max))
1541 (set-marker (process-mark proc) (point-max))
1542 (select-window cur)))
1547 @node Decoding Output
1548 @subsection Decoding Process Output
1549 @cindex decode process output
1551 When Emacs writes process output directly into a multibyte buffer,
1552 it decodes the output according to the process output coding system.
1553 If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
1554 converts the unibyte output to multibyte using
1555 @code{string-to-multibyte}, and inserts the resulting multibyte text.
1557 You can use @code{set-process-coding-system} to specify which coding
1558 system to use (@pxref{Process Information}). Otherwise, the coding
1559 system comes from @code{coding-system-for-read}, if that is
1560 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
1561 Coding Systems}). If the text output by a process contains null
1562 bytes, Emacs by default uses @code{no-conversion} for it; see
1563 @ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
1564 control this behavior.
1566 @strong{Warning:} Coding systems such as @code{undecided}, which
1567 determine the coding system from the data, do not work entirely
1568 reliably with asynchronous subprocess output. This is because Emacs
1569 has to process asynchronous subprocess output in batches, as it
1570 arrives. Emacs must try to detect the proper coding system from one
1571 batch at a time, and this does not always work. Therefore, if at all
1572 possible, specify a coding system that determines both the character
1573 code conversion and the end of line conversion---that is, one like
1574 @code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
1576 @c Let's keep the index entries that were there for
1577 @c set-process-filter-multibyte and process-filter-multibyte-p,
1578 @cindex filter multibyte flag, of process
1579 @cindex process filter multibyte flag
1580 When Emacs calls a process filter function, it provides the process
1581 output as a multibyte string or as a unibyte string according to the
1582 process's filter coding system. Emacs
1583 decodes the output according to the process output coding system,
1584 which usually produces a multibyte string, except for coding systems
1585 such as @code{binary} and @code{raw-text}.
1587 @node Accepting Output
1588 @subsection Accepting Output from Processes
1589 @cindex accept input from processes
1591 Output from asynchronous subprocesses normally arrives only while
1592 Emacs is waiting for some sort of external event, such as elapsed time
1593 or terminal input. Occasionally it is useful in a Lisp program to
1594 explicitly permit output to arrive at a specific point, or even to wait
1595 until output arrives from a process.
1597 @defun accept-process-output &optional process seconds millisec just-this-one
1598 This function allows Emacs to read pending output from processes. The
1599 output is given to their filter functions. If @var{process} is
1600 non-@code{nil} then this function does not return until some output
1601 has been received from @var{process}.
1603 The arguments @var{seconds} and @var{millisec} let you specify timeout
1604 periods. The former specifies a period measured in seconds and the
1605 latter specifies one measured in milliseconds. The two time periods
1606 thus specified are added together, and @code{accept-process-output}
1607 returns after that much time, even if there is no
1610 The argument @var{millisec} is obsolete (and should not be used),
1611 because @var{seconds} can be floating point to specify
1612 waiting a fractional number of seconds. If @var{seconds} is 0, the
1613 function accepts whatever output is pending but does not wait.
1615 @c Emacs 22.1 feature
1616 If @var{process} is a process, and the argument @var{just-this-one} is
1617 non-@code{nil}, only output from that process is handled, suspending output
1618 from other processes until some output has been received from that
1619 process or the timeout expires. If @var{just-this-one} is an integer,
1620 also inhibit running timers. This feature is generally not
1621 recommended, but may be necessary for specific applications, such as
1624 The function @code{accept-process-output} returns non-@code{nil} if it
1625 got output from @var{process}, or from any process if @var{process} is
1626 @code{nil}. It returns @code{nil} if the timeout expired before output
1631 @section Sentinels: Detecting Process Status Changes
1632 @cindex process sentinel
1633 @cindex sentinel (of process)
1635 A @dfn{process sentinel} is a function that is called whenever the
1636 associated process changes status for any reason, including signals
1637 (whether sent by Emacs or caused by the process's own actions) that
1638 terminate, stop, or continue the process. The process sentinel is
1639 also called if the process exits. The sentinel receives two
1640 arguments: the process for which the event occurred, and a string
1641 describing the type of event.
1643 @cindex default sentinel function of a process
1644 If no sentinel function was specified for a process, it will use the
1645 default sentinel function, which inserts a message in the process's
1646 buffer with the process name and the string describing the event.
1648 The string describing the event looks like one of the following:
1652 @code{"finished\n"}.
1658 @code{"exited abnormally with code @var{exitcode} (core dumped)\n"}.
1659 The ``core dumped'' part is optional, and only appears if the process
1663 @code{"failed with code @var{fail-code}\n"}.
1666 @code{"@var{signal-description} (core dumped)\n"}. The
1667 @var{signal-description} is a system-dependent textual description of
1668 a signal, e.g., @code{"killed"} for @code{SIGKILL}. The ``core
1669 dumped'' part is optional, and only appears if the process dumped
1673 @code{"open from @var{host-name}\n"}.
1679 @code{"connection broken by remote peer\n"}.
1682 A sentinel runs only while Emacs is waiting (e.g., for terminal
1683 input, or for time to elapse, or for process output). This avoids the
1684 timing errors that could result from running sentinels at random places in
1685 the middle of other Lisp programs. A program can wait, so that
1686 sentinels will run, by calling @code{sit-for} or @code{sleep-for}
1687 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
1688 Output}). Emacs also allows sentinels to run when the command loop is
1689 reading input. @code{delete-process} calls the sentinel when it
1690 terminates a running process.
1692 Emacs does not keep a queue of multiple reasons to call the sentinel
1693 of one process; it records just the current status and the fact that
1694 there has been a change. Therefore two changes in status, coming in
1695 quick succession, can call the sentinel just once. However, process
1696 termination will always run the sentinel exactly once. This is
1697 because the process status can't change again after termination.
1699 Emacs explicitly checks for output from the process before running
1700 the process sentinel. Once the sentinel runs due to process
1701 termination, no further output can arrive from the process.
1703 A sentinel that writes the output into the buffer of the process
1704 should check whether the buffer is still alive. If it tries to insert
1705 into a dead buffer, it will get an error. If the buffer is dead,
1706 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
1708 @c Note this text is duplicated in the filter functions section.
1709 Quitting is normally inhibited within a sentinel---otherwise, the
1710 effect of typing @kbd{C-g} at command level or to quit a user command
1711 would be unpredictable. If you want to permit quitting inside a
1712 sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the
1713 right way to do this is with the macro @code{with-local-quit}.
1716 If an error happens during execution of a sentinel, it is caught
1717 automatically, so that it doesn't stop the execution of whatever
1718 programs was running when the sentinel was started. However, if
1719 @code{debug-on-error} is non-@code{nil}, errors are not caught.
1720 This makes it possible to use the Lisp debugger to debug the
1721 sentinel. @xref{Debugger}.
1723 While a sentinel is running, the process sentinel is temporarily
1724 set to @code{nil} so that the sentinel won't run recursively.
1725 For this reason it is not possible for a sentinel to specify
1729 In earlier Emacs versions, every sentinel that did regular expression
1730 searching or matching had to explicitly save and restore the match data.
1731 Now Emacs does this automatically for sentinels; they never need to do
1734 Note that Emacs automatically saves and restores the match data
1735 while executing sentinels. @xref{Match Data}.
1737 @defun set-process-sentinel process sentinel
1738 This function associates @var{sentinel} with @var{process}. If
1739 @var{sentinel} is @code{nil}, then the process will have the default
1740 sentinel, which inserts a message in the process's buffer when the
1741 process status changes.
1743 Changes in process sentinels take effect immediately---if the sentinel
1744 is slated to be run but has not been called yet, and you specify a new
1745 sentinel, the eventual call to the sentinel will use the new one.
1749 (defun msg-me (process event)
1751 (format "Process: %s had the event '%s'" process event)))
1752 (set-process-sentinel (get-process "shell") 'msg-me)
1756 (kill-process (get-process "shell"))
1757 @print{} Process: #<process shell> had the event 'killed'
1758 @result{} #<process shell>
1763 @defun process-sentinel process
1764 This function returns the sentinel of @var{process}.
1767 In case a process status changes need to be passed to several sentinels, you
1768 can use @code{add-function} to combine an existing sentinel with a new one.
1769 @xref{Advising Functions}.
1771 @defun waiting-for-user-input-p
1772 While a sentinel or filter function is running, this function returns
1773 non-@code{nil} if Emacs was waiting for keyboard input from the user at
1774 the time the sentinel or filter function was called, or @code{nil} if it
1778 @node Query Before Exit
1779 @section Querying Before Exit
1781 When Emacs exits, it terminates all its subprocesses by sending them
1782 the @code{SIGHUP} signal. Because subprocesses may be doing
1783 valuable work, Emacs normally asks the user to confirm that it is ok
1784 to terminate them. Each process has a query flag, which, if
1785 non-@code{nil}, says that Emacs should ask for confirmation before
1786 exiting and thus killing that process. The default for the query flag
1787 is @code{t}, meaning @emph{do} query.
1789 @defun process-query-on-exit-flag process
1790 This returns the query flag of @var{process}.
1793 @defun set-process-query-on-exit-flag process flag
1794 This function sets the query flag of @var{process} to @var{flag}. It
1797 Here is an example of using @code{set-process-query-on-exit-flag} on a
1798 shell process to avoid querying:
1802 (set-process-query-on-exit-flag (get-process "shell") nil)
1808 @node System Processes
1809 @section Accessing Other Processes
1810 @cindex system processes
1812 In addition to accessing and manipulating processes that are
1813 subprocesses of the current Emacs session, Emacs Lisp programs can
1814 also access other processes running on the same machine. We call
1815 these @dfn{system processes}, to distinguish them from Emacs
1818 Emacs provides several primitives for accessing system processes.
1819 Not all platforms support these primitives; on those which don't,
1820 these primitives return @code{nil}.
1822 @defun list-system-processes
1823 This function returns a list of all the processes running on the
1824 system. Each process is identified by its @acronym{PID}, a numerical
1825 process ID that is assigned by the OS and distinguishes the process
1826 from all the other processes running on the same machine at the same
1830 @defun process-attributes pid
1831 This function returns an alist of attributes for the process specified
1832 by its process ID @var{pid}. Each association in the alist is of the
1833 form @code{(@var{key} . @var{value})}, where @var{key} designates the
1834 attribute and @var{value} is the value of that attribute. The various
1835 attribute @var{key}s that this function can return are listed below.
1836 Not all platforms support all of these attributes; if an attribute is
1837 not supported, its association will not appear in the returned alist.
1838 Values that are numbers can be either integer or floating point,
1839 depending on the magnitude of the value.
1843 The effective user ID of the user who invoked the process. The
1844 corresponding @var{value} is a number. If the process was invoked by
1845 the same user who runs the current Emacs session, the value is
1846 identical to what @code{user-uid} returns (@pxref{User
1850 User name corresponding to the process's effective user ID, a string.
1853 The group ID of the effective user ID, a number.
1856 Group name corresponding to the effective user's group ID, a string.
1859 The name of the command that runs in the process. This is a string
1860 that usually specifies the name of the executable file of the process,
1861 without the leading directories. However, some special system
1862 processes can report strings that do not correspond to an executable
1866 The state code of the process. This is a short string that encodes
1867 the scheduling state of the process. Here's a list of the most
1868 frequently seen codes:
1872 uninterruptible sleep (usually I/O)
1876 interruptible sleep (waiting for some event)
1878 stopped, e.g., by a job control signal
1880 zombie: a process that terminated, but was not reaped by its parent
1884 For the full list of the possible states, see the manual page of the
1885 @command{ps} command.
1888 The process ID of the parent process, a number.
1891 The process group ID of the process, a number.
1894 The session ID of the process. This is a number that is the process
1895 ID of the process's @dfn{session leader}.
1898 A string that is the name of the process's controlling terminal. On
1899 Unix and GNU systems, this is normally the file name of the
1900 corresponding terminal device, such as @file{/dev/pts65}.
1903 The numerical process group ID of the foreground process group that
1904 uses the process's terminal.
1907 The number of minor page faults caused by the process since its
1908 beginning. (Minor page faults are those that don't involve reading
1912 The number of major page faults caused by the process since its
1913 beginning. (Major page faults require a disk to be read, and are thus
1914 more expensive than minor page faults.)
1918 Like @code{minflt} and @code{majflt}, but include the number of page
1919 faults for all the child processes of the given process.
1922 Time spent by the process in the user context, for running the
1923 application's code. The corresponding @var{value} is in the
1924 @w{@code{(@var{high} @var{low} @var{microsec} @var{picosec})}} format, the same
1925 format used by functions @code{current-time} (@pxref{Time of Day,
1926 current-time}) and @code{file-attributes} (@pxref{File Attributes}).
1929 Time spent by the process in the system (kernel) context, for
1930 processing system calls. The corresponding @var{value} is in the same
1931 format as for @code{utime}.
1934 The sum of @code{utime} and @code{stime}. The corresponding
1935 @var{value} is in the same format as for @code{utime}.
1940 Like @code{utime}, @code{stime}, and @code{time}, but include the
1941 times of all the child processes of the given process.
1944 The numerical priority of the process.
1947 The @dfn{nice value} of the process, a number. (Processes with smaller
1948 nice values get scheduled more favorably.)
1951 The number of threads in the process.
1954 The time when the process was started, in the same
1955 @code{(@var{high} @var{low} @var{microsec} @var{picosec})} format used by
1956 @code{file-attributes} and @code{current-time}.
1959 The time elapsed since the process started, in the format @code{(@var{high}
1960 @var{low} @var{microsec} @var{picosec})}.
1963 The virtual memory size of the process, measured in kilobytes.
1966 The size of the process's @dfn{resident set}, the number of kilobytes
1967 occupied by the process in the machine's physical memory.
1970 The percentage of the CPU time used by the process since it started.
1971 The corresponding @var{value} is a floating-point number between 0 and
1975 The percentage of the total physical memory installed on the machine
1976 used by the process's resident set. The value is a floating-point
1977 number between 0 and 100.
1980 The command-line with which the process was invoked. This is a string
1981 in which individual command-line arguments are separated by blanks;
1982 whitespace characters that are embedded in the arguments are quoted as
1983 appropriate for the system's shell: escaped by backslash characters on
1984 GNU and Unix, and enclosed in double quote characters on Windows.
1985 Thus, this command-line string can be directly used in primitives such
1986 as @code{shell-command}.
1992 @node Transaction Queues
1993 @section Transaction Queues
1994 @cindex transaction queue
1996 @c That's not very informative. What is a transaction, and when might
1997 @c I want to use one?
1998 You can use a @dfn{transaction queue} to communicate with a subprocess
1999 using transactions. First use @code{tq-create} to create a transaction
2000 queue communicating with a specified process. Then you can call
2001 @code{tq-enqueue} to send a transaction.
2003 @defun tq-create process
2004 This function creates and returns a transaction queue communicating with
2005 @var{process}. The argument @var{process} should be a subprocess
2006 capable of sending and receiving streams of bytes. It may be a child
2007 process, or it may be a TCP connection to a server, possibly on another
2011 @defun tq-enqueue queue question regexp closure fn &optional delay-question
2012 This function sends a transaction to queue @var{queue}. Specifying the
2013 queue has the effect of specifying the subprocess to talk to.
2015 The argument @var{question} is the outgoing message that starts the
2016 transaction. The argument @var{fn} is the function to call when the
2017 corresponding answer comes back; it is called with two arguments:
2018 @var{closure}, and the answer received.
2020 The argument @var{regexp} is a regular expression that should match
2021 text at the end of the entire answer, but nothing before; that's how
2022 @code{tq-enqueue} determines where the answer ends.
2024 If the argument @var{delay-question} is non-@code{nil}, delay sending
2025 this question until the process has finished replying to any previous
2026 questions. This produces more reliable results with some processes.
2029 @c Let's not mention it then.
2030 The return value of @code{tq-enqueue} itself is not meaningful.
2034 @defun tq-close queue
2035 Shut down transaction queue @var{queue}, waiting for all pending transactions
2036 to complete, and then terminate the connection or child process.
2039 Transaction queues are implemented by means of a filter function.
2040 @xref{Filter Functions}.
2043 @section Network Connections
2044 @cindex network connection
2048 Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
2049 connections (@pxref{Datagrams}) to other processes on the same machine
2051 A network connection is handled by Lisp much like a subprocess, and is
2052 represented by a process object. However, the process you are
2053 communicating with is not a child of the Emacs process, has no
2054 process @acronym{ID}, and you can't kill it or send it signals. All you
2055 can do is send and receive data. @code{delete-process} closes the
2056 connection, but does not kill the program at the other end; that
2057 program must decide what to do about closure of the connection.
2059 Lisp programs can listen for connections by creating network
2060 servers. A network server is also represented by a kind of process
2061 object, but unlike a network connection, the network server never
2062 transfers data itself. When it receives a connection request, it
2063 creates a new network connection to represent the connection just
2064 made. (The network connection inherits certain information, including
2065 the process plist, from the server.) The network server then goes
2066 back to listening for more connection requests.
2068 Network connections and servers are created by calling
2069 @code{make-network-process} with an argument list consisting of
2070 keyword/argument pairs, for example @code{:server t} to create a
2071 server process, or @code{:type 'datagram} to create a datagram
2072 connection. @xref{Low-Level Network}, for details. You can also use
2073 the @code{open-network-stream} function described below.
2075 To distinguish the different types of processes, the
2076 @code{process-type} function returns the symbol @code{network} for a
2077 network connection or server, @code{serial} for a serial port
2078 connection, or @code{real} for a real subprocess.
2080 The @code{process-status} function returns @code{open},
2081 @code{closed}, @code{connect}, or @code{failed} for network
2082 connections. For a network server, the status is always
2083 @code{listen}. None of those values is possible for a real
2084 subprocess. @xref{Process Information}.
2086 You can stop and resume operation of a network process by calling
2087 @code{stop-process} and @code{continue-process}. For a server
2088 process, being stopped means not accepting new connections. (Up to 5
2089 connection requests will be queued for when you resume the server; you
2090 can increase this limit, unless it is imposed by the operating
2091 system---see the @code{:server} keyword of @code{make-network-process},
2092 @ref{Network Processes}.) For a network stream connection, being
2093 stopped means not processing input (any arriving input waits until you
2094 resume the connection). For a datagram connection, some number of
2095 packets may be queued but input may be lost. You can use the function
2096 @code{process-command} to determine whether a network connection or
2097 server is stopped; a non-@code{nil} value means yes.
2099 @cindex network connection, encrypted
2100 @cindex encrypted network connections
2101 @cindex @acronym{TLS} network connections
2102 @cindex @acronym{STARTTLS} network connections
2103 Emacs can create encrypted network connections, using either built-in
2104 or external support. The built-in support uses the GnuTLS
2105 Transport Layer Security Library; see
2106 @uref{http://www.gnu.org/software/gnutls/, the GnuTLS project page}.
2107 If your Emacs was compiled with GnuTLS support, the function
2108 @code{gnutls-available-p} is defined and returns non-@code{nil}. For
2109 more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}.
2110 The external support uses the @file{starttls.el} library, which
2111 requires a helper utility such as @command{gnutls-cli} to be installed
2112 on the system. The @code{open-network-stream} function can
2113 transparently handle the details of creating encrypted connections for
2114 you, using whatever support is available.
2116 @defun open-network-stream name buffer host service &rest parameters
2117 This function opens a TCP connection, with optional encryption, and
2118 returns a process object that represents the connection.
2120 The @var{name} argument specifies the name for the process object. It
2121 is modified as necessary to make it unique.
2123 The @var{buffer} argument is the buffer to associate with the
2124 connection. Output from the connection is inserted in the buffer,
2125 unless you specify your own filter function to handle the output. If
2126 @var{buffer} is @code{nil}, it means that the connection is not
2127 associated with any buffer.
2129 The arguments @var{host} and @var{service} specify where to connect to;
2130 @var{host} is the host name (a string), and @var{service} is the name of
2131 a defined network service (a string) or a port number (an integer).
2133 The remaining arguments @var{parameters} are keyword/argument pairs
2134 that are mainly relevant to encrypted connections:
2138 @item :nowait @var{boolean}
2139 If non-@code{nil}, try to make an asynchronous connection.
2141 @item :type @var{type}
2142 The type of connection. Options are:
2146 An ordinary, unencrypted connection.
2149 A @acronym{TLS} (Transport Layer Security) connection.
2152 Start with a plain connection, and if parameters @samp{:success}
2153 and @samp{:capability-command} are supplied, try to upgrade to an encrypted
2154 connection via @acronym{STARTTLS}. If that fails, retain the
2155 unencrypted connection.
2157 As for @code{nil}, but if @acronym{STARTTLS} fails drop the connection.
2162 @item :always-query-capabilities @var{boolean}
2163 If non-@code{nil}, always ask for the server's capabilities, even when
2164 doing a @samp{plain} connection.
2166 @item :capability-command @var{capability-command}
2167 Command string to query the host capabilities.
2169 @item :end-of-command @var{regexp}
2170 @itemx :end-of-capability @var{regexp}
2171 Regular expression matching the end of a command, or the end of the
2172 command @var{capability-command}. The latter defaults to the former.
2174 @item :starttls-function @var{function}
2175 Function of one argument (the response to @var{capability-command}),
2176 which returns either @code{nil}, or the command to activate @acronym{STARTTLS}
2179 @item :success @var{regexp}
2180 Regular expression matching a successful @acronym{STARTTLS} negotiation.
2182 @item :use-starttls-if-possible @var{boolean}
2183 If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs
2184 doesn't have built-in @acronym{TLS} support.
2186 @item :warn-unless-encrypted @var{boolean}
2187 If non-@code{nil}, and @code{:return-value} is also non-@code{nil},
2188 Emacs will warn if the connection isn't encrypted. This is useful for
2189 protocols like @acronym{IMAP} and the like, where most users would
2190 expect the network traffic to be encrypted.
2192 @item :client-certificate @var{list-or-t}
2193 Either a list of the form @code{(@var{key-file} @var{cert-file})},
2194 naming the certificate key file and certificate file itself, or
2195 @code{t}, meaning to query @code{auth-source} for this information
2196 (@pxref{Top,,Overview, auth, The Auth-Source Manual}).
2197 Only used for @acronym{TLS} or @acronym{STARTTLS}.
2199 @item :return-list @var{cons-or-nil}
2200 The return value of this function. If omitted or @code{nil}, return a
2201 process object. Otherwise, a cons of the form @code{(@var{process-object}
2202 . @var{plist})}, where @var{plist} has keywords:
2205 @item :greeting @var{string-or-nil}
2206 If non-@code{nil}, the greeting string returned by the host.
2207 @item :capabilities @var{string-or-nil}
2208 If non-@code{nil}, the host's capability string.
2209 @item :type @var{symbol}
2210 The connection type: @samp{plain} or @samp{tls}.
2218 @node Network Servers
2219 @section Network Servers
2220 @cindex network servers
2222 You create a server by calling @code{make-network-process}
2223 (@pxref{Network Processes}) with @code{:server t}. The server will
2224 listen for connection requests from clients. When it accepts a client
2225 connection request, that creates a new network connection, itself a
2226 process object, with the following parameters:
2230 The connection's process name is constructed by concatenating the
2231 server process's @var{name} with a client identification string. The
2232 @c FIXME? What about IPv6? Say briefly what the difference is?
2233 client identification string for an IPv4 connection looks like
2234 @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}, which represents an
2235 address and port number. Otherwise, it is a
2236 unique number in brackets, as in @samp{<@var{nnn}>}. The number
2237 is unique for each connection in the Emacs session.
2240 If the server has a non-default filter, the connection process does
2241 not get a separate process buffer; otherwise, Emacs creates a new
2242 buffer for the purpose. The buffer name is the server's buffer name
2243 or process name, concatenated with the client identification string.
2245 The server's process buffer value is never used directly, but the log
2246 function can retrieve it and use it to log connections by inserting
2250 The communication type and the process filter and sentinel are
2251 inherited from those of the server. The server never directly
2252 uses its filter and sentinel; their sole purpose is to initialize
2253 connections made to the server.
2256 The connection's process contact information is set according to the client's
2257 addressing information (typically an IP address and a port number).
2258 This information is associated with the @code{process-contact}
2259 keywords @code{:host}, @code{:service}, @code{:remote}.
2262 The connection's local address is set up according to the port
2263 number used for the connection.
2266 The client process's plist is initialized from the server's plist.
2273 A @dfn{datagram} connection communicates with individual packets rather
2274 than streams of data. Each call to @code{process-send} sends one
2275 datagram packet (@pxref{Input to Processes}), and each datagram
2276 received results in one call to the filter function.
2278 The datagram connection doesn't have to talk with the same remote
2279 peer all the time. It has a @dfn{remote peer address} which specifies
2280 where to send datagrams to. Each time an incoming datagram is passed
2281 to the filter function, the peer address is set to the address that
2282 datagram came from; that way, if the filter function sends a datagram,
2283 it will go back to that place. You can specify the remote peer
2284 address when you create the datagram connection using the
2285 @code{:remote} keyword. You can change it later on by calling
2286 @code{set-process-datagram-address}.
2288 @defun process-datagram-address process
2289 If @var{process} is a datagram connection or server, this function
2290 returns its remote peer address.
2293 @defun set-process-datagram-address process address
2294 If @var{process} is a datagram connection or server, this function
2295 sets its remote peer address to @var{address}.
2298 @node Low-Level Network
2299 @section Low-Level Network Access
2301 You can also create network connections by operating at a lower
2302 level than that of @code{open-network-stream}, using
2303 @code{make-network-process}.
2306 * Proc: Network Processes. Using @code{make-network-process}.
2307 * Options: Network Options. Further control over network connections.
2308 * Features: Network Feature Testing.
2309 Determining which network features work on
2310 the machine you are using.
2313 @node Network Processes
2314 @subsection @code{make-network-process}
2316 The basic function for creating network connections and network
2317 servers is @code{make-network-process}. It can do either of those
2318 jobs, depending on the arguments you give it.
2320 @defun make-network-process &rest args
2321 This function creates a network connection or server and returns the
2322 process object that represents it. The arguments @var{args} are a
2323 list of keyword/argument pairs. Omitting a keyword is always
2324 equivalent to specifying it with value @code{nil}, except for
2325 @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here
2326 are the meaningful keywords (those corresponding to network options
2327 are listed in the following section):
2330 @item :name @var{name}
2331 Use the string @var{name} as the process name. It is modified if
2332 necessary to make it unique.
2334 @item :type @var{type}
2335 Specify the communication type. A value of @code{nil} specifies a
2336 stream connection (the default); @code{datagram} specifies a datagram
2337 connection; @code{seqpacket} specifies a sequenced packet stream
2338 connection. Both connections and servers can be of these types.
2340 @item :server @var{server-flag}
2341 If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
2342 create a connection. For a stream type server, @var{server-flag} may
2343 be an integer, which then specifies the length of the queue of pending
2344 connections to the server. The default queue length is 5.
2346 @item :host @var{host}
2347 Specify the host to connect to. @var{host} should be a host name or
2348 Internet address, as a string, or the symbol @code{local} to specify
2349 the local host. If you specify @var{host} for a server, it must
2350 specify a valid address for the local host, and only clients
2351 connecting to that address will be accepted.
2353 @item :service @var{service}
2354 @var{service} specifies a port number to connect to; or, for a server,
2355 the port number to listen on. It should be a service name that
2356 translates to a port number, or an integer specifying the port number
2357 directly. For a server, it can also be @code{t}, which means to let
2358 the system select an unused port number.
2360 @item :family @var{family}
2361 @var{family} specifies the address (and protocol) family for
2362 communication. @code{nil} means determine the proper address family
2363 automatically for the given @var{host} and @var{service}.
2364 @code{local} specifies a Unix socket, in which case @var{host} is
2365 ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6,
2368 @item :local @var{local-address}
2369 For a server process, @var{local-address} is the address to listen on.
2370 It overrides @var{family}, @var{host} and @var{service}, so you
2371 might as well not specify them.
2373 @item :remote @var{remote-address}
2374 For a connection, @var{remote-address} is the address to connect to.
2375 It overrides @var{family}, @var{host} and @var{service}, so you
2376 might as well not specify them.
2378 For a datagram server, @var{remote-address} specifies the initial
2379 setting of the remote datagram address.
2381 The format of @var{local-address} or @var{remote-address} depends on
2386 An IPv4 address is represented as a five-element vector of four 8-bit
2387 integers and one 16-bit integer
2388 @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to
2389 numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number
2393 An IPv6 address is represented as a nine-element vector of 16-bit
2394 integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f}
2395 @var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address
2396 @var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and
2397 port number @var{p}.
2400 A local address is represented as a string, which specifies the address
2401 in the local address space.
2404 An unsupported-family address is represented by a cons
2405 @code{(@var{f} . @var{av})}, where @var{f} is the family number and
2406 @var{av} is a vector specifying the socket address using one element
2407 per address data byte. Do not rely on this format in portable code,
2408 as it may depend on implementation defined constants, data sizes, and
2409 data structure alignment.
2412 @item :nowait @var{bool}
2413 If @var{bool} is non-@code{nil} for a stream connection, return
2414 without waiting for the connection to complete. When the connection
2415 succeeds or fails, Emacs will call the sentinel function, with a
2416 second argument matching @code{"open"} (if successful) or
2417 @code{"failed"}. The default is to block, so that
2418 @code{make-network-process} does not return until the connection
2419 has succeeded or failed.
2421 @item :stop @var{stopped}
2422 If @var{stopped} is non-@code{nil}, start the network connection or
2423 server in the stopped state.
2425 @item :buffer @var{buffer}
2426 Use @var{buffer} as the process buffer.
2428 @item :coding @var{coding}
2429 Use @var{coding} as the coding system for this process. To specify
2430 different coding systems for decoding data from the connection and for
2431 encoding data sent to it, specify @code{(@var{decoding} .
2432 @var{encoding})} for @var{coding}.
2434 If you don't specify this keyword at all, the default
2435 is to determine the coding systems from the data.
2437 @item :noquery @var{query-flag}
2438 Initialize the process query flag to @var{query-flag}.
2439 @xref{Query Before Exit}.
2441 @item :filter @var{filter}
2442 Initialize the process filter to @var{filter}.
2444 @item :filter-multibyte @var{multibyte}
2445 If @var{multibyte} is non-@code{nil}, strings given to the process
2446 filter are multibyte, otherwise they are unibyte. The default is the
2447 default value of @code{enable-multibyte-characters}.
2449 @item :sentinel @var{sentinel}
2450 Initialize the process sentinel to @var{sentinel}.
2452 @item :log @var{log}
2453 Initialize the log function of a server process to @var{log}. The log
2454 function is called each time the server accepts a network connection
2455 from a client. The arguments passed to the log function are
2456 @var{server}, @var{connection}, and @var{message}; where @var{server}
2457 is the server process, @var{connection} is the new process for the
2458 connection, and @var{message} is a string describing what has
2461 @item :plist @var{plist}
2462 Initialize the process plist to @var{plist}.
2465 The original argument list, modified with the actual connection
2466 information, is available via the @code{process-contact} function.
2469 @node Network Options
2470 @subsection Network Options
2472 The following network options can be specified when you create a
2473 network process. Except for @code{:reuseaddr}, you can also set or
2474 modify these options later, using @code{set-network-process-option}.
2476 For a server process, the options specified with
2477 @code{make-network-process} are not inherited by the client
2478 connections, so you will need to set the necessary options for each
2479 child connection as it is created.
2482 @item :bindtodevice @var{device-name}
2483 If @var{device-name} is a non-empty string identifying a network
2484 interface name (see @code{network-interface-list}), only handle
2485 packets received on that interface. If @var{device-name} is @code{nil}
2486 (the default), handle packets received on any interface.
2488 Using this option may require special privileges on some systems.
2490 @item :broadcast @var{broadcast-flag}
2491 If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
2492 process will receive datagram packet sent to a broadcast address, and
2493 be able to send packets to a broadcast address. This is ignored for a stream
2496 @item :dontroute @var{dontroute-flag}
2497 If @var{dontroute-flag} is non-@code{nil}, the process can only send
2498 to hosts on the same network as the local host.
2500 @item :keepalive @var{keepalive-flag}
2501 If @var{keepalive-flag} is non-@code{nil} for a stream connection,
2502 enable exchange of low-level keep-alive messages.
2504 @item :linger @var{linger-arg}
2505 If @var{linger-arg} is non-@code{nil}, wait for successful
2506 transmission of all queued packets on the connection before it is
2507 deleted (see @code{delete-process}). If @var{linger-arg} is an
2508 integer, it specifies the maximum time in seconds to wait for queued
2509 packets to be sent before closing the connection. The default is
2510 @code{nil}, which means to discard unsent queued packets when the
2513 @c FIXME Where out-of-band data is ...?
2514 @item :oobinline @var{oobinline-flag}
2515 If @var{oobinline-flag} is non-@code{nil} for a stream connection,
2516 receive out-of-band data in the normal data stream. Otherwise, ignore
2519 @item :priority @var{priority}
2520 Set the priority for packets sent on this connection to the integer
2521 @var{priority}. The interpretation of this number is protocol
2522 specific; such as setting the TOS (type of service) field on IP
2523 packets sent on this connection. It may also have system dependent
2524 effects, such as selecting a specific output queue on the network
2527 @item :reuseaddr @var{reuseaddr-flag}
2528 If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
2529 server process, allow this server to reuse a specific port number (see
2530 @code{:service}), unless another process on this host is already
2531 listening on that port. If @var{reuseaddr-flag} is @code{nil}, there
2532 may be a period of time after the last use of that port (by any
2533 process on the host) where it is not possible to make a new server on
2537 @defun set-network-process-option process option value &optional no-error
2538 This function sets or modifies a network option for network process
2539 @var{process}. The accepted options and values are as for
2540 @code{make-network-process}. If @var{no-error} is non-@code{nil},
2541 this function returns @code{nil} instead of signaling an error if
2542 @var{option} is not a supported option. If the function successfully
2543 completes, it returns @code{t}.
2545 The current setting of an option is available via the
2546 @code{process-contact} function.
2549 @node Network Feature Testing
2550 @subsection Testing Availability of Network Features
2552 To test for the availability of a given network feature, use
2553 @code{featurep} like this:
2556 (featurep 'make-network-process '(@var{keyword} @var{value}))
2560 The result of this form is @code{t} if it works to specify
2561 @var{keyword} with value @var{value} in @code{make-network-process}.
2562 Here are some of the @var{keyword}---@var{value} pairs you can test in
2567 Non-@code{nil} if non-blocking connect is supported.
2568 @item (:type datagram)
2569 Non-@code{nil} if datagrams are supported.
2570 @item (:family local)
2571 Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported.
2572 @item (:family ipv6)
2573 Non-@code{nil} if IPv6 is supported.
2575 Non-@code{nil} if the system can select the port for a server.
2578 To test for the availability of a given network option, use
2579 @code{featurep} like this:
2582 (featurep 'make-network-process '@var{keyword})
2586 The accepted @var{keyword} values are @code{:bindtodevice}, etc.
2587 For the complete list, @pxref{Network Options}. This form returns
2588 non-@code{nil} if that particular network option is supported by
2589 @code{make-network-process} (or @code{set-network-process-option}).
2592 @section Misc Network Facilities
2594 These additional functions are useful for creating and operating
2595 on network connections. Note that they are supported only on some
2598 @defun network-interface-list
2599 This function returns a list describing the network interfaces
2600 of the machine you are using. The value is an alist whose
2601 elements have the form @code{(@var{name} . @var{address})}.
2602 @var{address} has the same form as the @var{local-address}
2603 and @var{remote-address} arguments to @code{make-network-process}.
2606 @defun network-interface-info ifname
2607 This function returns information about the network interface named
2608 @var{ifname}. The value is a list of the form
2609 @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
2613 The Internet protocol address.
2615 The broadcast address.
2619 The layer 2 address (Ethernet MAC address, for instance).
2621 The current flags of the interface.
2625 @defun format-network-address address &optional omit-port
2626 This function converts the Lisp representation of a network address to
2629 A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]}
2630 represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port
2631 number @var{p}. @code{format-network-address} converts that to the
2632 string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
2634 A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e}
2635 @var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along
2636 with a port number. @code{format-network-address} converts that to
2638 @code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}.
2640 If the vector does not include the port number, @var{p}, or if
2641 @var{omit-port} is non-@code{nil}, the result does not include the
2642 @code{:@var{p}} suffix.
2646 @section Communicating with Serial Ports
2647 @cindex @file{/dev/tty}
2649 @cindex serial connections
2651 Emacs can communicate with serial ports. For interactive use,
2652 @kbd{M-x serial-term} opens a terminal window. In a Lisp program,
2653 @code{make-serial-process} creates a process object.
2655 The serial port can be configured at run-time, without having to
2656 close and re-open it. The function @code{serial-process-configure}
2657 lets you change the speed, bytesize, and other parameters. In a
2658 terminal window created by @code{serial-term}, you can click on the
2659 mode line for configuration.
2661 A serial connection is represented by a process object, which can be
2662 used in a similar way to a subprocess or network process. You can send and
2663 receive data, and configure the serial port. A serial process object
2664 has no process ID, however, and you can't send signals to it, and the
2665 status codes are different from other types of processes.
2666 @code{delete-process} on the process object or @code{kill-buffer} on
2667 the process buffer close the connection, but this does not affect the
2668 device connected to the serial port.
2670 The function @code{process-type} returns the symbol @code{serial}
2671 for a process object representing a serial port connection.
2673 Serial ports are available on GNU/Linux, Unix, and MS Windows systems.
2675 @deffn Command serial-term port speed
2676 Start a terminal-emulator for a serial port in a new buffer.
2677 @var{port} is the name of the serial port to connect to. For
2678 example, this could be @file{/dev/ttyS0} on Unix. On MS Windows, this
2679 could be @file{COM1}, or @file{\\.\COM10} (double the backslashes in
2682 @c FIXME is 9600 still the most common value, or is it 115200 now?
2683 @c (Same value, 9600, appears below as well.)
2684 @var{speed} is the speed of the serial port in bits per second. 9600
2685 is a common value. The buffer is in Term mode; see @ref{Term Mode,,,
2686 emacs, The GNU Emacs Manual}, for the commands to use in that buffer.
2687 You can change the speed and the configuration in the mode line menu.
2690 @defun make-serial-process &rest args
2691 This function creates a process and a buffer. Arguments are specified
2692 as keyword/argument pairs. Here's the list of the meaningful
2693 keywords, with the first two (@var{port} and @var{speed}) being mandatory:
2696 @item :port @var{port}
2697 This is the name of the serial port. On Unix and GNU systems, this is
2698 a file name such as @file{/dev/ttyS0}. On Windows, this could be
2699 @file{COM1}, or @file{\\.\COM10} for ports higher than @file{COM9}
2700 (double the backslashes in Lisp strings).
2702 @item :speed @var{speed}
2703 The speed of the serial port in bits per second. This function calls
2704 @code{serial-process-configure} to handle the speed; see the
2705 following documentation of that function for more details.
2707 @item :name @var{name}
2708 The name of the process. If @var{name} is not given, @var{port} will
2709 serve as the process name as well.
2711 @item :buffer @var{buffer}
2712 The buffer to associate with the process. The value can be either a
2713 buffer or a string that names a buffer. Process output goes at the
2714 end of that buffer, unless you specify an output stream or filter
2715 function to handle the output. If @var{buffer} is not given, the
2716 process buffer's name is taken from the value of the @code{:name}
2719 @item :coding @var{coding}
2720 If @var{coding} is a symbol, it specifies the coding system used for
2721 both reading and writing for this process. If @var{coding} is a cons
2722 @code{(@var{decoding} . @var{encoding})}, @var{decoding} is used for
2723 reading, and @var{encoding} is used for writing. If not specified,
2724 the default is to determine the coding systems from the data itself.
2726 @item :noquery @var{query-flag}
2727 Initialize the process query flag to @var{query-flag}. @xref{Query
2728 Before Exit}. The flags defaults to @code{nil} if unspecified.
2730 @item :stop @var{bool}
2731 Start process in the stopped state if @var{bool} is
2732 non-@code{nil}. In the stopped state, a serial process does not
2733 accept incoming data, but you can send outgoing data. The stopped
2734 state is cleared by @code{continue-process} and set by
2735 @code{stop-process}.
2737 @item :filter @var{filter}
2738 Install @var{filter} as the process filter.
2740 @item :sentinel @var{sentinel}
2741 Install @var{sentinel} as the process sentinel.
2743 @item :plist @var{plist}
2744 Install @var{plist} as the initial plist of the process.
2750 These are handled by @code{serial-process-configure}, which is called
2751 by @code{make-serial-process}.
2754 The original argument list, possibly modified by later configuration,
2755 is available via the function @code{process-contact}.
2760 (make-serial-process :port "/dev/ttyS0" :speed 9600)
2764 @defun serial-process-configure &rest args
2765 @cindex baud, in serial connections
2766 @cindex bytesize, in serial connections
2767 @cindex parity, in serial connections
2768 @cindex stopbits, in serial connections
2769 @cindex flowcontrol, in serial connections
2771 This function configures a serial port connection. Arguments are
2772 specified as keyword/argument pairs. Attributes that are not given
2773 are re-initialized from the process's current configuration (available
2774 via the function @code{process-contact}), or set to reasonable default
2775 values. The following arguments are defined:
2778 @item :process @var{process}
2779 @itemx :name @var{name}
2780 @itemx :buffer @var{buffer}
2781 @itemx :port @var{port}
2782 Any of these arguments can be given to identify the process that is to
2783 be configured. If none of these arguments is given, the current
2784 buffer's process is used.
2786 @item :speed @var{speed}
2787 The speed of the serial port in bits per second, a.k.a.@: @dfn{baud
2788 rate}. The value can be any number, but most serial ports work only
2789 at a few defined values between 1200 and 115200, with 9600 being the
2790 most common value. If @var{speed} is @code{nil}, the function ignores
2791 all other arguments and does not configure the port. This may be
2792 useful for special serial ports such as Bluetooth-to-serial converters,
2793 which can only be configured through @samp{AT} commands sent through the
2794 connection. The value of @code{nil} for @var{speed} is valid only for
2795 connections that were already opened by a previous call to
2796 @code{make-serial-process} or @code{serial-term}.
2798 @item :bytesize @var{bytesize}
2799 The number of bits per byte, which can be 7 or 8. If @var{bytesize}
2800 is not given or @code{nil}, it defaults to 8.
2802 @item :parity @var{parity}
2803 The value can be @code{nil} (don't use parity), the symbol
2804 @code{odd} (use odd parity), or the symbol @code{even} (use even
2805 parity). If @var{parity} is not given, it defaults to no parity.
2807 @item :stopbits @var{stopbits}
2808 The number of stopbits used to terminate a transmission
2809 of each byte. @var{stopbits} can be 1 or 2. If @var{stopbits} is not
2810 given or @code{nil}, it defaults to 1.
2812 @item :flowcontrol @var{flowcontrol}
2813 The type of flow control to use for this connection, which is either
2814 @code{nil} (don't use flow control), the symbol @code{hw} (use RTS/CTS
2815 hardware flow control), or the symbol @code{sw} (use XON/XOFF software
2816 flow control). If @var{flowcontrol} is not given, it defaults to no
2820 Internally, @code{make-serial-process} calls
2821 @code{serial-process-configure} for the initial configuration of the
2826 @section Packing and Unpacking Byte Arrays
2827 @cindex byte packing and unpacking
2829 This section describes how to pack and unpack arrays of bytes,
2830 usually for binary network protocols. These functions convert byte arrays
2831 to alists, and vice versa. The byte array can be represented as a
2832 @c FIXME? No multibyte?
2833 unibyte string or as a vector of integers, while the alist associates
2834 symbols either with fixed-size objects or with recursive sub-alists.
2835 To use the functions referred to in this section, load the
2836 @code{bindat} library.
2837 @c It doesn't have any autoloads.
2840 @cindex deserializing
2843 Conversion from byte arrays to nested alists is also known as
2844 @dfn{deserializing} or @dfn{unpacking}, while going in the opposite
2845 direction is also known as @dfn{serializing} or @dfn{packing}.
2848 * Bindat Spec:: Describing data layout.
2849 * Bindat Functions:: Doing the unpacking and packing.
2850 * Bindat Examples:: Samples of what bindat.el can do for you!
2854 @subsection Describing Data Layout
2856 To control unpacking and packing, you write a @dfn{data layout
2857 specification}, a special nested list describing named and typed
2858 @dfn{fields}. This specification controls the length of each field to be
2859 processed, and how to pack or unpack it. We normally keep bindat specs
2860 in variables whose names end in @samp{-bindat-spec}; that kind of name
2861 is automatically recognized as risky.
2865 @cindex little endian
2866 @cindex network byte ordering
2867 A field's @dfn{type} describes the size (in bytes) of the object
2868 that the field represents and, in the case of multibyte fields, how
2869 the bytes are ordered within the field. The two possible orderings
2870 are @dfn{big endian} (also known as ``network byte ordering'') and
2871 @dfn{little endian}. For instance, the number @code{#x23cd} (decimal
2872 9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
2873 and in little endian, @code{#xcd} @code{#x23}. Here are the possible
2879 Unsigned byte, with length 1.
2884 Unsigned integer in network byte order, with length 2.
2887 Unsigned integer in network byte order, with length 3.
2892 Unsigned integer in network byte order, with length 4.
2893 Note: These values may be limited by Emacs's integer implementation limits.
2898 Unsigned integer in little endian order, with length 2, 3 and 4, respectively.
2901 String of length @var{len}.
2903 @item strz @var{len}
2904 Zero-terminated string, in a fixed-size field with length @var{len}.
2906 @item vec @var{len} [@var{type}]
2907 Vector of @var{len} elements of type @var{type}, defaulting to bytes.
2908 The @var{type} is any of the simple types above, or another vector
2909 specified as a list of the form @code{(vec @var{len} [@var{type}])}.
2913 Four-byte vector representing an Internet address. For example:
2914 @code{[127 0 0 1]} for localhost.
2916 @item bits @var{len}
2917 List of set bits in @var{len} bytes. The bytes are taken in big
2918 endian order and the bits are numbered starting with @code{8 *
2919 @var{len} @minus{} 1} and ending with zero. For example: @code{bits
2920 2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and
2921 @code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}.
2923 @item (eval @var{form})
2924 @var{form} is a Lisp expression evaluated at the moment the field is
2925 unpacked or packed. The result of the evaluation should be one of the
2926 above-listed type specifications.
2929 For a fixed-size field, the length @var{len} is given as an integer
2930 specifying the number of bytes in the field.
2932 When the length of a field is not fixed, it typically depends on the
2933 value of a preceding field. In this case, the length @var{len} can be
2934 given either as a list @code{(@var{name} ...)} identifying a
2935 @dfn{field name} in the format specified for @code{bindat-get-field}
2936 below, or by an expression @code{(eval @var{form})} where @var{form}
2937 should evaluate to an integer, specifying the field length.
2939 A field specification generally has the form @code{([@var{name}]
2940 @var{handler})}, where @var{name} is optional. Don't use names that
2941 are symbols meaningful as type specifications (above) or handler
2942 specifications (below), since that would be ambiguous. @var{name} can
2943 be a symbol or an expression @code{(eval @var{form})}, in which case
2944 @var{form} should evaluate to a symbol.
2946 @var{handler} describes how to unpack or pack the field and can be one
2951 Unpack/pack this field according to the type specification @var{type}.
2953 @item eval @var{form}
2954 Evaluate @var{form}, a Lisp expression, for side-effect only. If the
2955 field name is specified, the value is bound to that field name.
2957 @item fill @var{len}
2958 Skip @var{len} bytes. In packing, this leaves them unchanged,
2959 which normally means they remain zero. In unpacking, this means
2962 @item align @var{len}
2963 Skip to the next multiple of @var{len} bytes.
2965 @item struct @var{spec-name}
2966 Process @var{spec-name} as a sub-specification. This describes a
2967 structure nested within another structure.
2969 @item union @var{form} (@var{tag} @var{spec})@dots{}
2970 @c ??? I don't see how one would actually use this.
2971 @c ??? what kind of expression would be useful for @var{form}?
2972 Evaluate @var{form}, a Lisp expression, find the first @var{tag}
2973 that matches it, and process its associated data layout specification
2974 @var{spec}. Matching can occur in one of three ways:
2978 If a @var{tag} has the form @code{(eval @var{expr})}, evaluate
2979 @var{expr} with the variable @code{tag} dynamically bound to the value
2980 of @var{form}. A non-@code{nil} result indicates a match.
2983 @var{tag} matches if it is @code{equal} to the value of @var{form}.
2986 @var{tag} matches unconditionally if it is @code{t}.
2989 @item repeat @var{count} @var{field-specs}@dots{}
2990 Process the @var{field-specs} recursively, in order, then repeat
2991 starting from the first one, processing all the specifications @var{count}
2992 times overall. The @var{count} is given using the same formats as a
2993 field length---if an @code{eval} form is used, it is evaluated just once.
2994 For correct operation, each specification in @var{field-specs} must
2998 For the @code{(eval @var{form})} forms used in a bindat specification,
2999 the @var{form} can access and update these dynamically bound variables
3004 Value of the last field processed.
3007 The data as a byte array.
3010 Current index (within @code{bindat-raw}) for unpacking or packing.
3013 The alist containing the structured data that have been unpacked so
3014 far, or the entire structure being packed. You can use
3015 @code{bindat-get-field} to access specific fields of this structure.
3019 Inside a @code{repeat} block, these contain the maximum number of
3020 repetitions (as specified by the @var{count} parameter), and the
3021 current repetition number (counting from 0). Setting @code{count} to
3022 zero will terminate the inner-most repeat block after the current
3023 repetition has completed.
3026 @node Bindat Functions
3027 @subsection Functions to Unpack and Pack Bytes
3029 In the following documentation, @var{spec} refers to a data layout
3030 specification, @code{bindat-raw} to a byte array, and @var{struct} to an
3031 alist representing unpacked field data.
3033 @defun bindat-unpack spec bindat-raw &optional bindat-idx
3034 @c FIXME? Again, no multibyte?
3035 This function unpacks data from the unibyte string or byte
3036 array @code{bindat-raw}
3037 according to @var{spec}. Normally, this starts unpacking at the
3038 beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it
3039 specifies a zero-based starting position to use instead.
3041 The value is an alist or nested alist in which each element describes
3045 @defun bindat-get-field struct &rest name
3046 This function selects a field's data from the nested alist
3047 @var{struct}. Usually @var{struct} was returned by
3048 @code{bindat-unpack}. If @var{name} corresponds to just one argument,
3049 that means to extract a top-level field value. Multiple @var{name}
3050 arguments specify repeated lookup of sub-structures. An integer name
3051 acts as an array index.
3053 For example, if @var{name} is @code{(a b 2 c)}, that means to find
3054 field @code{c} in the third element of subfield @code{b} of field
3055 @code{a}. (This corresponds to @code{struct.a.b[2].c} in C.)
3058 Although packing and unpacking operations change the organization of
3059 data (in memory), they preserve the data's @dfn{total length}, which is
3060 the sum of all the fields' lengths, in bytes. This value is not
3061 generally inherent in either the specification or alist alone; instead,
3062 both pieces of information contribute to its calculation. Likewise, the
3063 length of a string or array being unpacked may be longer than the data's
3064 total length as described by the specification.
3066 @defun bindat-length spec struct
3067 This function returns the total length of the data in @var{struct},
3068 according to @var{spec}.
3071 @defun bindat-pack spec struct &optional bindat-raw bindat-idx
3072 This function returns a byte array packed according to @var{spec} from
3073 the data in the alist @var{struct}. It normally creates and fills a
3074 new byte array starting at the beginning. However, if @var{bindat-raw}
3075 is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to
3076 pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting
3077 offset for packing into @code{bindat-raw}.
3079 When pre-allocating, you should make sure @code{(length @var{bindat-raw})}
3080 meets or exceeds the total length to avoid an out-of-range error.
3083 @defun bindat-ip-to-string ip
3084 Convert the Internet address vector @var{ip} to a string in the usual
3086 @c FIXME? Does it do IPv6?
3089 (bindat-ip-to-string [127 0 0 1])
3090 @result{} "127.0.0.1"
3094 @node Bindat Examples
3095 @subsection Examples of Byte Unpacking and Packing
3096 @c FIXME? This seems a very long example for something that is not used
3097 @c very often. As of 24.1, gdb-mi.el is the only user of bindat.el in Emacs.
3098 @c Maybe one or both of these examples should just be moved to the
3099 @c commentary of bindat.el.
3101 Here is a complete example of byte unpacking and packing:
3106 (defvar fcookie-index-spec
3114 (:offset repeat (:count) (:foo u32)))
3115 "Description of a fortune cookie index file's contents.")
3117 (defun fcookie (cookies &optional index)
3118 "Display a random fortune cookie from file COOKIES.
3119 Optional second arg INDEX specifies the associated index
3120 filename, by default \"COOKIES.dat\". Display cookie text
3121 in buffer \"*Fortune Cookie: BASENAME*\", where BASENAME
3122 is COOKIES without the directory part."
3123 (interactive "fCookies file: ")
3124 (let* ((info (with-temp-buffer
3125 (insert-file-contents-literally
3126 (or index (concat cookies ".dat")))
3127 (bindat-unpack fcookie-index-spec
3129 (sel (random (bindat-get-field info :count)))
3130 (beg (cdar (bindat-get-field info :offset sel)))
3131 (end (or (cdar (bindat-get-field info
3133 (nth 7 (file-attributes cookies)))))
3136 (format "*Fortune Cookie: %s*"
3137 (file-name-nondirectory cookies))))
3139 (insert-file-contents-literally
3140 cookies nil beg (- end 3))))
3142 (defun fcookie-create-index (cookies &optional index delim)
3143 "Scan file COOKIES, and write out its index file.
3144 Optional arg INDEX specifies the index filename, which by
3145 default is \"COOKIES.dat\". Optional arg DELIM specifies the
3146 unibyte character that, when found on a line of its own in
3147 COOKIES, indicates the border between entries."
3148 (interactive "fCookies file: ")
3149 (setq delim (or delim ?%))
3150 (let ((delim-line (format "\n%c\n" delim))
3153 min p q len offsets)
3154 (unless (= 3 (string-bytes delim-line))
3155 (error "Delimiter cannot be represented in one byte"))
3157 (insert-file-contents-literally cookies)
3158 (while (and (setq p (point))
3159 (search-forward delim-line (point-max) t)
3160 (setq len (- (point) 3 p)))
3161 (setq count (1+ count)
3163 min (min (or min max) len)
3164 offsets (cons (1- p) offsets))))
3166 (set-buffer-multibyte nil)
3176 (:offset . ,(mapcar (lambda (o)
3177 (list (cons :foo o)))
3178 (nreverse offsets))))))
3179 (let ((coding-system-for-write 'raw-text-unix))
3180 (write-file (or index (concat cookies ".dat")))))))
3183 The following is an example of defining and unpacking a complex
3184 structure. Consider the following C structures:
3188 unsigned long dest_ip;
3189 unsigned long src_ip;
3190 unsigned short dest_port;
3191 unsigned short src_port;
3196 unsigned char opcode;
3197 unsigned short length; /* in network byte order */
3198 unsigned char id[8]; /* null-terminated string */
3199 unsigned char data[/* (length + 3) & ~3 */];
3203 struct header header;
3204 unsigned long counters[2]; /* in little endian order */
3205 unsigned char items;
3206 unsigned char filler[3];
3207 struct data item[/* items */];
3212 The corresponding data layout specification is:
3224 (length u16) ; network byte order
3230 '((header struct header-spec)
3231 (counters vec 2 u32r) ; little endian order
3234 (item repeat (items)
3235 (struct data-spec))))
3238 A binary data representation is:
3242 [ 192 168 1 100 192 168 1 101 01 28 21 32
3243 160 134 1 0 5 1 0 0 2 0 0 0
3244 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
3245 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
3248 The corresponding decoded structure is:
3251 (setq decoded (bindat-unpack packet-spec binary-data))
3254 (dest-ip . [192 168 1 100])
3255 (src-ip . [192 168 1 101])
3258 (counters . [100000 261])
3260 (item ((data . [1 2 3 4 5])
3265 ((data . [6 7 8 9 10 11 12])
3272 An example of fetching data from this structure:
3275 (bindat-get-field decoded 'item 1 'id)