2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
4 @c 2004, 2005, 2006 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/processes
7 @node Processes, Display, Abbrevs, Top
10 @cindex parent process
14 In the terminology of operating systems, a @dfn{process} is a space in
15 which a program can execute. Emacs runs in a process. Emacs Lisp
16 programs can invoke other programs in processes of their own. These are
17 called @dfn{subprocesses} or @dfn{child processes} of the Emacs process,
18 which is their @dfn{parent process}.
20 A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous},
21 depending on how it is created. When you create a synchronous
22 subprocess, the Lisp program waits for the subprocess to terminate
23 before continuing execution. When you create an asynchronous
24 subprocess, it can run in parallel with the Lisp program. This kind of
25 subprocess is represented within Emacs by a Lisp object which is also
26 called a ``process''. Lisp programs can use this object to communicate
27 with the subprocess or to control it. For example, you can send
28 signals, obtain status information, receive output from the process, or
31 @defun processp object
32 This function returns @code{t} if @var{object} is a process,
37 * Subprocess Creation:: Functions that start subprocesses.
38 * Shell Arguments:: Quoting an argument to pass it to a shell.
39 * Synchronous Processes:: Details of using synchronous subprocesses.
40 * Asynchronous Processes:: Starting up an asynchronous subprocess.
41 * Deleting Processes:: Eliminating an asynchronous subprocess.
42 * Process Information:: Accessing run-status and other attributes.
43 * Input to Processes:: Sending input to an asynchronous subprocess.
44 * Signals to Processes:: Stopping, continuing or interrupting
45 an asynchronous subprocess.
46 * Output from Processes:: Collecting output from an asynchronous subprocess.
47 * Sentinels:: Sentinels run when process run-status changes.
48 * Query Before Exit:: Whether to query if exiting will kill a process.
49 * Transaction Queues:: Transaction-based communication with subprocesses.
50 * Network:: Opening network connections.
51 * Network Servers:: Network servers let Emacs accept net connections.
52 * Datagrams:: UDP network connections.
53 * Low-Level Network:: Lower-level but more general function
54 to create connections and servers.
55 * Misc Network:: Additional relevant functions for network connections.
56 * Byte Packing:: Using bindat to pack and unpack binary data.
59 @node Subprocess Creation
60 @section Functions that Create Subprocesses
62 There are three functions that create a new subprocess in which to run
63 a program. One of them, @code{start-process}, creates an asynchronous
64 process and returns a process object (@pxref{Asynchronous Processes}).
65 The other two, @code{call-process} and @code{call-process-region},
66 create a synchronous process and do not return a process object
67 (@pxref{Synchronous Processes}).
69 Synchronous and asynchronous processes are explained in the following
70 sections. Since the three functions are all called in a similar
71 fashion, their common arguments are described here.
73 @cindex execute program
74 @cindex @code{PATH} environment variable
75 @cindex @code{HOME} environment variable
76 In all cases, the function's @var{program} argument specifies the
77 program to be run. An error is signaled if the file is not found or
78 cannot be executed. If the file name is relative, the variable
79 @code{exec-path} contains a list of directories to search. Emacs
80 initializes @code{exec-path} when it starts up, based on the value of
81 the environment variable @code{PATH}. The standard file name
82 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as
83 usual in @code{exec-path}, but environment variable substitutions
84 (@samp{$HOME}, etc.) are not recognized; use
85 @code{substitute-in-file-name} to perform them (@pxref{File Name
86 Expansion}). @code{nil} in this list refers to
87 @code{default-directory}.
89 Executing a program can also try adding suffixes to the specified
93 This variable is a list of suffixes (strings) to try adding to the
94 specified program file name. The list should include @code{""} if you
95 want the name to be tried exactly as specified. The default value is
99 @strong{Please note:} The argument @var{program} contains only the
100 name of the program; it may not contain any command-line arguments. You
101 must use @var{args} to provide those.
103 Each of the subprocess-creating functions has a @var{buffer-or-name}
104 argument which specifies where the standard output from the program will
105 go. It should be a buffer or a buffer name; if it is a buffer name,
106 that will create the buffer if it does not already exist. It can also
107 be @code{nil}, which says to discard the output unless a filter function
108 handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
109 Normally, you should avoid having multiple processes send output to the
110 same buffer because their output would be intermixed randomly.
112 @cindex program arguments
113 All three of the subprocess-creating functions have a @code{&rest}
114 argument, @var{args}. The @var{args} must all be strings, and they are
115 supplied to @var{program} as separate command line arguments. Wildcard
116 characters and other shell constructs have no special meanings in these
117 strings, since the strings are passed directly to the specified program.
119 The subprocess gets its current directory from the value of
120 @code{default-directory} (@pxref{File Name Expansion}).
122 @cindex environment variables, subprocesses
123 The subprocess inherits its environment from Emacs, but you can
124 specify overrides for it with @code{process-environment}. @xref{System
127 @defvar exec-directory
129 The value of this variable is a string, the name of a directory that
130 contains programs that come with GNU Emacs, programs intended for Emacs
131 to invoke. The program @code{movemail} is an example of such a program;
132 Rmail uses it to fetch new mail from an inbox.
136 The value of this variable is a list of directories to search for
137 programs to run in subprocesses. Each element is either the name of a
138 directory (i.e., a string), or @code{nil}, which stands for the default
139 directory (which is the value of @code{default-directory}).
140 @cindex program directories
142 The value of @code{exec-path} is used by @code{call-process} and
143 @code{start-process} when the @var{program} argument is not an absolute
147 @node Shell Arguments
148 @section Shell Arguments
150 Lisp programs sometimes need to run a shell and give it a command
151 that contains file names that were specified by the user. These
152 programs ought to be able to support any valid file name. But the shell
153 gives special treatment to certain characters, and if these characters
154 occur in the file name, they will confuse the shell. To handle these
155 characters, use the function @code{shell-quote-argument}:
157 @defun shell-quote-argument argument
158 This function returns a string which represents, in shell syntax,
159 an argument whose actual contents are @var{argument}. It should
160 work reliably to concatenate the return value into a shell command
161 and then pass it to a shell for execution.
163 Precisely what this function does depends on your operating system. The
164 function is designed to work with the syntax of your system's standard
165 shell; if you use an unusual shell, you will need to redefine this
169 ;; @r{This example shows the behavior on GNU and Unix systems.}
170 (shell-quote-argument "foo > bar")
171 @result{} "foo\\ \\>\\ bar"
173 ;; @r{This example shows the behavior on MS-DOS and MS-Windows.}
174 (shell-quote-argument "foo > bar")
175 @result{} "\"foo > bar\""
178 Here's an example of using @code{shell-quote-argument} to construct
183 (shell-quote-argument oldfile)
185 (shell-quote-argument newfile))
189 @node Synchronous Processes
190 @section Creating a Synchronous Process
191 @cindex synchronous subprocess
193 After a @dfn{synchronous process} is created, Emacs waits for the
194 process to terminate before continuing. Starting Dired on GNU or
195 Unix@footnote{On other systems, Emacs uses a Lisp emulation of
196 @code{ls}; see @ref{Contents of Directories}.} is an example of this: it
197 runs @code{ls} in a synchronous process, then modifies the output
198 slightly. Because the process is synchronous, the entire directory
199 listing arrives in the buffer before Emacs tries to do anything with it.
201 While Emacs waits for the synchronous subprocess to terminate, the
202 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
203 the subprocess with a @code{SIGINT} signal; but it waits until the
204 subprocess actually terminates before quitting. If during that time the
205 user types another @kbd{C-g}, that kills the subprocess instantly with
206 @code{SIGKILL} and quits immediately (except on MS-DOS, where killing
207 other processes doesn't work). @xref{Quitting}.
209 The synchronous subprocess functions return an indication of how the
212 The output from a synchronous subprocess is generally decoded using a
213 coding system, much like text read from a file. The input sent to a
214 subprocess by @code{call-process-region} is encoded using a coding
215 system, much like text written into a file. @xref{Coding Systems}.
217 @defun call-process program &optional infile destination display &rest args
218 This function calls @var{program} in a separate process and waits for
221 The standard input for the process comes from file @var{infile} if
222 @var{infile} is not @code{nil}, and from the null device otherwise.
223 The argument @var{destination} says where to put the process output.
224 Here are the possibilities:
228 Insert the output in that buffer, before point. This includes both the
229 standard output stream and the standard error stream of the process.
232 Insert the output in a buffer with that name, before point.
235 Insert the output in the current buffer, before point.
241 Discard the output, and return @code{nil} immediately without waiting
242 for the subprocess to finish.
244 In this case, the process is not truly synchronous, since it can run in
245 parallel with Emacs; but you can think of it as synchronous in that
246 Emacs is essentially finished with the subprocess as soon as this
249 MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
252 @item @code{(@var{real-destination} @var{error-destination})}
253 Keep the standard output stream separate from the standard error stream;
254 deal with the ordinary output as specified by @var{real-destination},
255 and dispose of the error output according to @var{error-destination}.
256 If @var{error-destination} is @code{nil}, that means to discard the
257 error output, @code{t} means mix it with the ordinary output, and a
258 string specifies a file name to redirect error output into.
260 You can't directly specify a buffer to put the error output in; that is
261 too difficult to implement. But you can achieve this result by sending
262 the error output to a temporary file and then inserting the file into a
266 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
267 the buffer as output is inserted. (However, if the coding system chosen
268 for decoding output is @code{undecided}, meaning deduce the encoding
269 from the actual data, then redisplay sometimes cannot continue once
270 non-@acronym{ASCII} characters are encountered. There are fundamental
271 reasons why it is hard to fix this; see @ref{Output from Processes}.)
273 Otherwise the function @code{call-process} does no redisplay, and the
274 results become visible on the screen only when Emacs redisplays that
275 buffer in the normal course of events.
277 The remaining arguments, @var{args}, are strings that specify command
278 line arguments for the program.
280 The value returned by @code{call-process} (unless you told it not to
281 wait) indicates the reason for process termination. A number gives the
282 exit status of the subprocess; 0 means success, and any other value
283 means failure. If the process terminated with a signal,
284 @code{call-process} returns a string describing the signal.
286 In the examples below, the buffer @samp{foo} is current.
290 (call-process "pwd" nil t)
293 ---------- Buffer: foo ----------
294 /usr/user/lewis/manual
295 ---------- Buffer: foo ----------
299 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
302 ---------- Buffer: bar ----------
303 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
305 ---------- Buffer: bar ----------
309 Here is a good example of the use of @code{call-process}, which used to
310 be found in the definition of @code{insert-directory}:
314 (call-process insert-directory-program nil t nil @var{switches}
316 (concat (file-name-as-directory file) ".")
322 @defun process-file program &optional infile buffer display &rest args
323 This function processes files synchronously in a separate process. It
324 is similar to @code{call-process} but may invoke a file handler based
325 on the value of the variable @code{default-directory}. The current
326 working directory of the subprocess is @code{default-directory}.
328 The arguments are handled in almost the same way as for
329 @code{call-process}, with the following differences:
331 Some file handlers may not support all combinations and forms of the
332 arguments @var{infile}, @var{buffer}, and @var{display}. For example,
333 some file handlers might behave as if @var{display} were @code{nil},
334 regardless of the value actually passed. As another example, some
335 file handlers might not support separating standard output and error
336 output by way of the @var{buffer} argument.
338 If a file handler is invoked, it determines the program to run based
339 on the first argument @var{program}. For instance, consider that a
340 handler for remote files is invoked. Then the path that is used for
341 searching the program might be different than @code{exec-path}.
343 The second argument @var{infile} may invoke a file handler. The file
344 handler could be different from the handler chosen for the
345 @code{process-file} function itself. (For example,
346 @code{default-directory} could be on a remote host, whereas
347 @var{infile} is on another remote host. Or @code{default-directory}
348 could be non-special, whereas @var{infile} is on a remote host.)
350 If @var{buffer} has the form @code{(@var{real-destination}
351 @var{error-destination})}, and @var{error-destination} names a file,
352 then the same remarks as for @var{infile} apply.
354 The remaining arguments (@var{args}) will be passed to the process
355 verbatim. Emacs is not involved in processing file names that are
356 present in @var{args}. To avoid confusion, it may be best to avoid
357 absolute file names in @var{args}, but rather to specify all file
358 names as relative to @code{default-directory}. The function
359 @code{file-relative-name} is useful for constructing such relative
363 @defun call-process-region start end program &optional delete destination display &rest args
364 This function sends the text from @var{start} to @var{end} as
365 standard input to a process running @var{program}. It deletes the text
366 sent if @var{delete} is non-@code{nil}; this is useful when
367 @var{destination} is @code{t}, to insert the output in the current
368 buffer in place of the input.
370 The arguments @var{destination} and @var{display} control what to do
371 with the output from the subprocess, and whether to update the display
372 as it comes in. For details, see the description of
373 @code{call-process}, above. If @var{destination} is the integer 0,
374 @code{call-process-region} discards the output and returns @code{nil}
375 immediately, without waiting for the subprocess to finish (this only
376 works if asynchronous subprocesses are supported).
378 The remaining arguments, @var{args}, are strings that specify command
379 line arguments for the program.
381 The return value of @code{call-process-region} is just like that of
382 @code{call-process}: @code{nil} if you told it to return without
383 waiting; otherwise, a number or string which indicates how the
384 subprocess terminated.
386 In the following example, we use @code{call-process-region} to run the
387 @code{cat} utility, with standard input being the first five characters
388 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
389 standard input into its standard output. Since the argument
390 @var{destination} is @code{t}, this output is inserted in the current
395 ---------- Buffer: foo ----------
397 ---------- Buffer: foo ----------
401 (call-process-region 1 6 "cat" nil t)
404 ---------- Buffer: foo ----------
406 ---------- Buffer: foo ----------
410 The @code{shell-command-on-region} command uses
411 @code{call-process-region} like this:
417 shell-file-name ; @r{Name of program.}
418 nil ; @r{Do not delete region.}
419 buffer ; @r{Send output to @code{buffer}.}
420 nil ; @r{No redisplay during output.}
421 "-c" command) ; @r{Arguments for the shell.}
426 @defun call-process-shell-command command &optional infile destination display &rest args
427 This function executes the shell command @var{command} synchronously
428 in a separate process. The final arguments @var{args} are additional
429 arguments to add at the end of @var{command}. The other arguments
430 are handled as in @code{call-process}.
433 @defun shell-command-to-string command
434 This function executes @var{command} (a string) as a shell command,
435 then returns the command's output as a string.
438 @node Asynchronous Processes
439 @section Creating an Asynchronous Process
440 @cindex asynchronous subprocess
442 After an @dfn{asynchronous process} is created, Emacs and the subprocess
443 both continue running immediately. The process thereafter runs
444 in parallel with Emacs, and the two can communicate with each other
445 using the functions described in the following sections. However,
446 communication is only partially asynchronous: Emacs sends data to the
447 process only when certain functions are called, and Emacs accepts data
448 from the process only when Emacs is waiting for input or for a time
451 Here we describe how to create an asynchronous process.
453 @defun start-process name buffer-or-name program &rest args
454 This function creates a new asynchronous subprocess and starts the
455 program @var{program} running in it. It returns a process object that
456 stands for the new subprocess in Lisp. The argument @var{name}
457 specifies the name for the process object; if a process with this name
458 already exists, then @var{name} is modified (by appending @samp{<1>},
459 etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to
460 associate with the process.
462 The remaining arguments, @var{args}, are strings that specify command
463 line arguments for the program.
465 In the example below, the first process is started and runs (rather,
466 sleeps) for 100 seconds. Meanwhile, the second process is started, and
467 given the name @samp{my-process<1>} for the sake of uniqueness. It
468 inserts the directory listing at the end of the buffer @samp{foo},
469 before the first process finishes. Then it finishes, and a message to
470 that effect is inserted in the buffer. Much later, the first process
471 finishes, and another message is inserted in the buffer for it.
475 (start-process "my-process" "foo" "sleep" "100")
476 @result{} #<process my-process>
480 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
481 @result{} #<process my-process<1>>
483 ---------- Buffer: foo ----------
485 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
486 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
488 Process my-process<1> finished
490 Process my-process finished
491 ---------- Buffer: foo ----------
496 @defun start-process-shell-command name buffer-or-name command &rest command-args
497 This function is like @code{start-process} except that it uses a shell
498 to execute the specified command. The argument @var{command} is a shell
499 command name, and @var{command-args} are the arguments for the shell
500 command. The variable @code{shell-file-name} specifies which shell to
503 The point of running a program through the shell, rather than directly
504 with @code{start-process}, is so that you can employ shell features such
505 as wildcards in the arguments. It follows that if you include an
506 arbitrary user-specified arguments in the command, you should quote it
507 with @code{shell-quote-argument} first, so that any special shell
508 characters do @emph{not} have their special shell meanings. @xref{Shell
512 @defvar process-connection-type
514 @cindex @acronym{PTY}s
515 This variable controls the type of device used to communicate with
516 asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are
517 used, when available. Otherwise, pipes are used.
519 @acronym{PTY}s are usually preferable for processes visible to the user, as
520 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
521 etc.) to work between the process and its children, whereas pipes do
522 not. For subprocesses used for internal purposes by programs, it is
523 often better to use a pipe, because they are more efficient. In
524 addition, the total number of @acronym{PTY}s is limited on many systems and
525 it is good not to waste them.
527 The value of @code{process-connection-type} takes effect when
528 @code{start-process} is called. So you can specify how to communicate
529 with one subprocess by binding the variable around the call to
530 @code{start-process}.
534 (let ((process-connection-type nil)) ; @r{Use a pipe.}
535 (start-process @dots{}))
539 To determine whether a given subprocess actually got a pipe or a
540 @acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process
544 @node Deleting Processes
545 @section Deleting Processes
546 @cindex deleting processes
548 @dfn{Deleting a process} disconnects Emacs immediately from the
549 subprocess. Processes are deleted automatically after they terminate,
550 but not necessarily right away. You can delete a process explicitly
551 at any time. If you delete a terminated process explicitly before it
552 is deleted automatically, no harm results. Deleting a running
553 process sends a signal to terminate it (and its child processes if
554 any), and calls the process sentinel if it has one. @xref{Sentinels}.
556 When a process is deleted, the process object itself continues to
557 exist as long as other Lisp objects point to it. All the Lisp
558 primitives that work on process objects accept deleted processes, but
559 those that do I/O or send signals will report an error. The process
560 mark continues to point to the same place as before, usually into a
561 buffer where output from the process was being inserted.
563 @defopt delete-exited-processes
564 This variable controls automatic deletion of processes that have
565 terminated (due to calling @code{exit} or to a signal). If it is
566 @code{nil}, then they continue to exist until the user runs
567 @code{list-processes}. Otherwise, they are deleted immediately after
571 @defun delete-process process
572 This function deletes a process, killing it with a @code{SIGKILL}
573 signal. The argument may be a process, the name of a process, a
574 buffer, or the name of a buffer. (A buffer or buffer-name stands for
575 the process that @code{get-buffer-process} returns.) Calling
576 @code{delete-process} on a running process terminates it, updates the
577 process status, and runs the sentinel (if any) immediately. If the
578 process has already terminated, calling @code{delete-process} has no
579 effect on its status, or on the running of its sentinel (which will
580 happen sooner or later).
584 (delete-process "*shell*")
590 @node Process Information
591 @section Process Information
593 Several functions return information about processes.
594 @code{list-processes} is provided for interactive use.
596 @deffn Command list-processes &optional query-only
597 This command displays a listing of all living processes. In addition,
598 it finally deletes any process whose status was @samp{Exited} or
599 @samp{Signaled}. It returns @code{nil}.
601 If @var{query-only} is non-@code{nil} then it lists only processes
602 whose query flag is non-@code{nil}. @xref{Query Before Exit}.
606 This function returns a list of all processes that have not been deleted.
611 @result{} (#<process display-time> #<process shell>)
616 @defun get-process name
617 This function returns the process named @var{name}, or @code{nil} if
618 there is none. An error is signaled if @var{name} is not a string.
622 (get-process "shell")
623 @result{} #<process shell>
628 @defun process-command process
629 This function returns the command that was executed to start
630 @var{process}. This is a list of strings, the first string being the
631 program executed and the rest of the strings being the arguments that
632 were given to the program.
636 (process-command (get-process "shell"))
637 @result{} ("/bin/csh" "-i")
642 @defun process-id process
643 This function returns the @acronym{PID} of @var{process}. This is an
644 integer that distinguishes the process @var{process} from all other
645 processes running on the same computer at the current time. The
646 @acronym{PID} of a process is chosen by the operating system kernel when the
647 process is started and remains constant as long as the process exists.
650 @defun process-name process
651 This function returns the name of @var{process}.
654 @defun process-status process-name
655 This function returns the status of @var{process-name} as a symbol.
656 The argument @var{process-name} must be a process, a buffer, a
657 process name (string) or a buffer name (string).
659 The possible values for an actual subprocess are:
663 for a process that is running.
665 for a process that is stopped but continuable.
667 for a process that has exited.
669 for a process that has received a fatal signal.
671 for a network connection that is open.
673 for a network connection that is closed. Once a connection
674 is closed, you cannot reopen it, though you might be able to open
675 a new connection to the same place.
677 for a non-blocking connection that is waiting to complete.
679 for a non-blocking connection that has failed to complete.
681 for a network server that is listening.
683 if @var{process-name} is not the name of an existing process.
688 (process-status "shell")
692 (process-status (get-buffer "*shell*"))
697 @result{} #<process xx<1>>
703 For a network connection, @code{process-status} returns one of the symbols
704 @code{open} or @code{closed}. The latter means that the other side
705 closed the connection, or Emacs did @code{delete-process}.
708 @defun process-exit-status process
709 This function returns the exit status of @var{process} or the signal
710 number that killed it. (Use the result of @code{process-status} to
711 determine which of those it is.) If @var{process} has not yet
712 terminated, the value is 0.
715 @defun process-tty-name process
716 This function returns the terminal name that @var{process} is using for
717 its communication with Emacs---or @code{nil} if it is using pipes
718 instead of a terminal (see @code{process-connection-type} in
719 @ref{Asynchronous Processes}).
722 @defun process-coding-system process
723 @anchor{Coding systems for a subprocess}
724 This function returns a cons cell describing the coding systems in use
725 for decoding output from @var{process} and for encoding input to
726 @var{process} (@pxref{Coding Systems}). The value has this form:
729 (@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
733 @defun set-process-coding-system process &optional decoding-system encoding-system
734 This function specifies the coding systems to use for subsequent output
735 from and input to @var{process}. It will use @var{decoding-system} to
736 decode subprocess output, and @var{encoding-system} to encode subprocess
740 Every process also has a property list that you can use to store
741 miscellaneous values associated with the process.
743 @defun process-get process propname
744 This function returns the value of the @var{propname} property
748 @defun process-put process propname value
749 This function sets the value of the @var{propname} property
750 of @var{process} to @var{value}.
753 @defun process-plist process
754 This function returns the process plist of @var{process}.
757 @defun set-process-plist process plist
758 This function sets the process plist of @var{process} to @var{plist}.
761 @node Input to Processes
762 @section Sending Input to Processes
763 @cindex process input
765 Asynchronous subprocesses receive input when it is sent to them by
766 Emacs, which is done with the functions in this section. You must
767 specify the process to send input to, and the input data to send. The
768 data appears on the ``standard input'' of the subprocess.
770 Some operating systems have limited space for buffered input in a
771 @acronym{PTY}. On these systems, Emacs sends an @acronym{EOF}
772 periodically amidst the other characters, to force them through. For
773 most programs, these @acronym{EOF}s do no harm.
775 Subprocess input is normally encoded using a coding system before the
776 subprocess receives it, much like text written into a file. You can use
777 @code{set-process-coding-system} to specify which coding system to use
778 (@pxref{Process Information}). Otherwise, the coding system comes from
779 @code{coding-system-for-write}, if that is non-@code{nil}; or else from
780 the defaulting mechanism (@pxref{Default Coding Systems}).
782 Sometimes the system is unable to accept input for that process,
783 because the input buffer is full. When this happens, the send functions
784 wait a short while, accepting output from subprocesses, and then try
785 again. This gives the subprocess a chance to read more of its pending
786 input and make space in the buffer. It also allows filters, sentinels
787 and timers to run---so take account of that in writing your code.
789 In these functions, the @var{process} argument can be a process or
790 the name of a process, or a buffer or buffer name (which stands
791 for a process via @code{get-buffer-process}). @code{nil} means
792 the current buffer's process.
794 @defun process-send-string process string
795 This function sends @var{process} the contents of @var{string} as
796 standard input. If it is @code{nil}, the current buffer's process is used.
798 The function returns @code{nil}.
802 (process-send-string "shell<1>" "ls\n")
808 ---------- Buffer: *shell* ----------
810 introduction.texi syntax-tables.texi~
811 introduction.texi~ text.texi
812 introduction.txt text.texi~
814 ---------- Buffer: *shell* ----------
819 @defun process-send-region process start end
820 This function sends the text in the region defined by @var{start} and
821 @var{end} as standard input to @var{process}.
823 An error is signaled unless both @var{start} and @var{end} are
824 integers or markers that indicate positions in the current buffer. (It
825 is unimportant which number is larger.)
828 @defun process-send-eof &optional process
829 This function makes @var{process} see an end-of-file in its
830 input. The @acronym{EOF} comes after any text already sent to it.
832 The function returns @var{process}.
836 (process-send-eof "shell")
842 @defun process-running-child-p process
843 @tindex process-running-child-p process
844 This function will tell you whether a subprocess has given control of
845 its terminal to its own child process. The value is @code{t} if this is
846 true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
850 @node Signals to Processes
851 @section Sending Signals to Processes
852 @cindex process signals
853 @cindex sending signals
856 @dfn{Sending a signal} to a subprocess is a way of interrupting its
857 activities. There are several different signals, each with its own
858 meaning. The set of signals and their names is defined by the operating
859 system. For example, the signal @code{SIGINT} means that the user has
860 typed @kbd{C-c}, or that some analogous thing has happened.
862 Each signal has a standard effect on the subprocess. Most signals
863 kill the subprocess, but some stop or resume execution instead. Most
864 signals can optionally be handled by programs; if the program handles
865 the signal, then we can say nothing in general about its effects.
867 You can send signals explicitly by calling the functions in this
868 section. Emacs also sends signals automatically at certain times:
869 killing a buffer sends a @code{SIGHUP} signal to all its associated
870 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
871 processes. (@code{SIGHUP} is a signal that usually indicates that the
872 user hung up the phone.)
874 Each of the signal-sending functions takes two optional arguments:
875 @var{process} and @var{current-group}.
877 The argument @var{process} must be either a process, a process
878 name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name
879 stands for a process through @code{get-buffer-process}. @code{nil}
880 stands for the process associated with the current buffer. An error
881 is signaled if @var{process} does not identify a process.
883 The argument @var{current-group} is a flag that makes a difference
884 when you are running a job-control shell as an Emacs subprocess. If it
885 is non-@code{nil}, then the signal is sent to the current process-group
886 of the terminal that Emacs uses to communicate with the subprocess. If
887 the process is a job-control shell, this means the shell's current
888 subjob. If it is @code{nil}, the signal is sent to the process group of
889 the immediate subprocess of Emacs. If the subprocess is a job-control
890 shell, this is the shell itself.
892 The flag @var{current-group} has no effect when a pipe is used to
893 communicate with the subprocess, because the operating system does not
894 support the distinction in the case of pipes. For the same reason,
895 job-control shells won't work when a pipe is used. See
896 @code{process-connection-type} in @ref{Asynchronous Processes}.
898 @defun interrupt-process &optional process current-group
899 This function interrupts the process @var{process} by sending the
900 signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt
901 character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
902 others) sends this signal. When the argument @var{current-group} is
903 non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
904 on the terminal by which Emacs talks to the subprocess.
907 @defun kill-process &optional process current-group
908 This function kills the process @var{process} by sending the
909 signal @code{SIGKILL}. This signal kills the subprocess immediately,
910 and cannot be handled by the subprocess.
913 @defun quit-process &optional process current-group
914 This function sends the signal @code{SIGQUIT} to the process
915 @var{process}. This signal is the one sent by the ``quit
916 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
920 @defun stop-process &optional process current-group
921 This function stops the process @var{process} by sending the
922 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
925 Outside of Emacs, on systems with job control, the ``stop character''
926 (usually @kbd{C-z}) normally sends this signal. When
927 @var{current-group} is non-@code{nil}, you can think of this function as
928 ``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
932 @defun continue-process &optional process current-group
933 This function resumes execution of the process @var{process} by sending
934 it the signal @code{SIGCONT}. This presumes that @var{process} was
939 @defun signal-process process signal
940 This function sends a signal to process @var{process}. The argument
941 @var{signal} specifies which signal to send; it should be an integer.
943 The @var{process} argument can be a system process @acronym{ID}; that
944 allows you to send signals to processes that are not children of
948 @node Output from Processes
949 @section Receiving Output from Processes
950 @cindex process output
951 @cindex output from processes
953 There are two ways to receive the output that a subprocess writes to
954 its standard output stream. The output can be inserted in a buffer,
955 which is called the associated buffer of the process, or a function
956 called the @dfn{filter function} can be called to act on the output. If
957 the process has no buffer and no filter function, its output is
960 When a subprocess terminates, Emacs reads any pending output,
961 then stops reading output from that subprocess. Therefore, if the
962 subprocess has children that are still live and still producing
963 output, Emacs won't receive that output.
965 Output from a subprocess can arrive only while Emacs is waiting: when
966 reading terminal input, in @code{sit-for} and @code{sleep-for}
967 (@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
968 Output}). This minimizes the problem of timing errors that usually
969 plague parallel programming. For example, you can safely create a
970 process and only then specify its buffer or filter function; no output
971 can arrive before you finish, if the code in between does not call any
972 primitive that waits.
974 @defvar process-adaptive-read-buffering
975 On some systems, when Emacs reads the output from a subprocess, the
976 output data is read in very small blocks, potentially resulting in
977 very poor performance. This behavior can be remedied to some extent
978 by setting the variable @var{process-adaptive-read-buffering} to a
979 non-@code{nil} value (the default), as it will automatically delay reading
980 from such processes, thus allowing them to produce more output before
981 Emacs tries to read it.
984 It is impossible to separate the standard output and standard error
985 streams of the subprocess, because Emacs normally spawns the subprocess
986 inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If
987 you want to keep the output to those streams separate, you should
988 redirect one of them to a file---for example, by using an appropriate
992 * Process Buffers:: If no filter, output is put in a buffer.
993 * Filter Functions:: Filter functions accept output from the process.
994 * Decoding Output:: Filters can get unibyte or multibyte strings.
995 * Accepting Output:: How to wait until process output arrives.
998 @node Process Buffers
999 @subsection Process Buffers
1001 A process can (and usually does) have an @dfn{associated buffer},
1002 which is an ordinary Emacs buffer that is used for two purposes: storing
1003 the output from the process, and deciding when to kill the process. You
1004 can also use the buffer to identify a process to operate on, since in
1005 normal practice only one process is associated with any given buffer.
1006 Many applications of processes also use the buffer for editing input to
1007 be sent to the process, but this is not built into Emacs Lisp.
1009 Unless the process has a filter function (@pxref{Filter Functions}),
1010 its output is inserted in the associated buffer. The position to insert
1011 the output is determined by the @code{process-mark}, which is then
1012 updated to point to the end of the text just inserted. Usually, but not
1013 always, the @code{process-mark} is at the end of the buffer.
1015 @defun process-buffer process
1016 This function returns the associated buffer of the process
1021 (process-buffer (get-process "shell"))
1022 @result{} #<buffer *shell*>
1027 @defun process-mark process
1028 This function returns the process marker for @var{process}, which is the
1029 marker that says where to insert output from the process.
1031 If @var{process} does not have a buffer, @code{process-mark} returns a
1032 marker that points nowhere.
1034 Insertion of process output in a buffer uses this marker to decide where
1035 to insert, and updates it to point after the inserted text. That is why
1036 successive batches of output are inserted consecutively.
1038 Filter functions normally should use this marker in the same fashion
1039 as is done by direct insertion of output in the buffer. A good
1040 example of a filter function that uses @code{process-mark} is found at
1041 the end of the following section.
1043 When the user is expected to enter input in the process buffer for
1044 transmission to the process, the process marker separates the new input
1045 from previous output.
1048 @defun set-process-buffer process buffer
1049 This function sets the buffer associated with @var{process} to
1050 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
1051 associated with no buffer.
1054 @defun get-buffer-process buffer-or-name
1055 This function returns a nondeleted process associated with the buffer
1056 specified by @var{buffer-or-name}. If there are several processes
1057 associated with it, this function chooses one (currently, the one most
1058 recently created, but don't count on that). Deletion of a process
1059 (see @code{delete-process}) makes it ineligible for this function to
1062 It is usually a bad idea to have more than one process associated with
1067 (get-buffer-process "*shell*")
1068 @result{} #<process shell>
1072 Killing the process's buffer deletes the process, which kills the
1073 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
1076 @node Filter Functions
1077 @subsection Process Filter Functions
1078 @cindex filter function
1079 @cindex process filter
1081 A process @dfn{filter function} is a function that receives the
1082 standard output from the associated process. If a process has a filter,
1083 then @emph{all} output from that process is passed to the filter. The
1084 process buffer is used directly for output from the process only when
1087 The filter function can only be called when Emacs is waiting for
1088 something, because process output arrives only at such times. Emacs
1089 waits when reading terminal input, in @code{sit-for} and
1090 @code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
1091 (@pxref{Accepting Output}).
1093 A filter function must accept two arguments: the associated process
1094 and a string, which is output just received from it. The function is
1095 then free to do whatever it chooses with the output.
1097 Quitting is normally inhibited within a filter function---otherwise,
1098 the effect of typing @kbd{C-g} at command level or to quit a user
1099 command would be unpredictable. If you want to permit quitting inside
1100 a filter function, bind @code{inhibit-quit} to @code{nil}. In most
1101 cases, the right way to do this is with the macro
1102 @code{with-local-quit}. @xref{Quitting}.
1104 If an error happens during execution of a filter function, it is
1105 caught automatically, so that it doesn't stop the execution of whatever
1106 program was running when the filter function was started. However, if
1107 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1108 off. This makes it possible to use the Lisp debugger to debug the
1109 filter function. @xref{Debugger}.
1111 Many filter functions sometimes or always insert the text in the
1112 process's buffer, mimicking the actions of Emacs when there is no
1113 filter. Such filter functions need to use @code{set-buffer} in order to
1114 be sure to insert in that buffer. To avoid setting the current buffer
1115 semipermanently, these filter functions must save and restore the
1116 current buffer. They should also update the process marker, and in some
1117 cases update the value of point. Here is how to do these things:
1121 (defun ordinary-insertion-filter (proc string)
1122 (with-current-buffer (process-buffer proc)
1123 (let ((moving (= (point) (process-mark proc))))
1127 ;; @r{Insert the text, advancing the process marker.}
1128 (goto-char (process-mark proc))
1130 (set-marker (process-mark proc) (point)))
1131 (if moving (goto-char (process-mark proc))))))
1136 The reason to use @code{with-current-buffer}, rather than using
1137 @code{save-excursion} to save and restore the current buffer, is so as
1138 to preserve the change in point made by the second call to
1141 To make the filter force the process buffer to be visible whenever new
1142 text arrives, insert the following line just before the
1143 @code{with-current-buffer} construct:
1146 (display-buffer (process-buffer proc))
1149 To force point to the end of the new output, no matter where it was
1150 previously, eliminate the variable @code{moving} and call
1151 @code{goto-char} unconditionally.
1153 In earlier Emacs versions, every filter function that did regular
1154 expression searching or matching had to explicitly save and restore the
1155 match data. Now Emacs does this automatically for filter functions;
1156 they never need to do it explicitly. @xref{Match Data}.
1158 A filter function that writes the output into the buffer of the
1159 process should check whether the buffer is still alive. If it tries to
1160 insert into a dead buffer, it will get an error. The expression
1161 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
1162 if the buffer is dead.
1164 The output to the function may come in chunks of any size. A program
1165 that produces the same output twice in a row may send it as one batch of
1166 200 characters one time, and five batches of 40 characters the next. If
1167 the filter looks for certain text strings in the subprocess output, make
1168 sure to handle the case where one of these strings is split across two
1169 or more batches of output.
1171 @defun set-process-filter process filter
1172 This function gives @var{process} the filter function @var{filter}. If
1173 @var{filter} is @code{nil}, it gives the process no filter.
1176 @defun process-filter process
1177 This function returns the filter function of @var{process}, or @code{nil}
1181 Here is an example of use of a filter function:
1185 (defun keep-output (process output)
1186 (setq kept (cons output kept)))
1187 @result{} keep-output
1194 (set-process-filter (get-process "shell") 'keep-output)
1195 @result{} keep-output
1198 (process-send-string "shell" "ls ~/other\n")
1201 @result{} ("lewis@@slug[8] % "
1204 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
1205 address.txt backup.psf kolstad.psf
1206 backup.bib~ david.mss resume-Dec-86.mss~
1207 backup.err david.psf resume-Dec.psf
1208 backup.mss dland syllabus.mss
1210 "#backups.mss# backup.mss~ kolstad.mss
1215 @ignore @c The code in this example doesn't show the right way to do things.
1216 Here is another, more realistic example, which demonstrates how to use
1217 the process mark to do insertion in the same fashion as is done when
1218 there is no filter function:
1222 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
1223 ;; @r{and make sure that buffer is shown in some window.}
1224 (defun my-process-filter (proc str)
1225 (let ((cur (selected-window))
1227 (pop-to-buffer my-shell-buffer)
1230 (goto-char (point-max))
1232 (set-marker (process-mark proc) (point-max))
1233 (select-window cur)))
1238 @node Decoding Output
1239 @subsection Decoding Process Output
1241 When Emacs writes process output directly into a multibyte buffer,
1242 it decodes the output according to the process output coding system.
1243 If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
1244 converts the unibyte output to multibyte using
1245 @code{string-to-multibyte}, and inserts the resulting multibyte text.
1247 You can use @code{set-process-coding-system} to specify which coding
1248 system to use (@pxref{Process Information}). Otherwise, the coding
1249 system comes from @code{coding-system-for-read}, if that is
1250 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
1253 @strong{Warning:} Coding systems such as @code{undecided} which
1254 determine the coding system from the data do not work entirely
1255 reliably with asynchronous subprocess output. This is because Emacs
1256 has to process asynchronous subprocess output in batches, as it
1257 arrives. Emacs must try to detect the proper coding system from one
1258 batch at a time, and this does not always work. Therefore, if at all
1259 possible, specify a coding system that determines both the character
1260 code conversion and the end of line conversion---that is, one like
1261 @code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
1263 @cindex filter multibyte flag, of process
1264 @cindex process filter multibyte flag
1265 When Emacs calls a process filter function, it provides the process
1266 output as a multibyte string or as a unibyte string according to the
1267 process's filter multibyte flag. If the flag is non-@code{nil}, Emacs
1268 decodes the output according to the process output coding system to
1269 produce a multibyte string, and passes that to the process. If the
1270 flag is @code{nil}, Emacs puts the output into a unibyte string, with
1271 no decoding, and passes that.
1273 When you create a process, the filter multibyte flag takes its
1274 initial value from @code{default-enable-multibyte-characters}. If you
1275 want to change the flag later on, use
1276 @code{set-process-filter-multibyte}.
1278 @defun set-process-filter-multibyte process multibyte
1279 This function sets the filter multibyte flag of @var{process}
1283 @defun process-filter-multibyte-p process
1284 This function returns the filter multibyte flag of @var{process}.
1287 @node Accepting Output
1288 @subsection Accepting Output from Processes
1290 Output from asynchronous subprocesses normally arrives only while
1291 Emacs is waiting for some sort of external event, such as elapsed time
1292 or terminal input. Occasionally it is useful in a Lisp program to
1293 explicitly permit output to arrive at a specific point, or even to wait
1294 until output arrives from a process.
1296 @defun accept-process-output &optional process seconds millisec just-this-one
1297 This function allows Emacs to read pending output from processes. The
1298 output is inserted in the associated buffers or given to their filter
1299 functions. If @var{process} is non-@code{nil} then this function does
1300 not return until some output has been received from @var{process}.
1303 The arguments @var{seconds} and @var{millisec} let you specify timeout
1304 periods. The former specifies a period measured in seconds and the
1305 latter specifies one measured in milliseconds. The two time periods
1306 thus specified are added together, and @code{accept-process-output}
1307 returns after that much time whether or not there has been any
1310 The argument @var{seconds} need not be an integer. If it is a floating
1311 point number, this function waits for a fractional number of seconds.
1313 @c Emacs 22.1 feature
1314 If @var{process} is a process, and the argument @var{just-this-one} is
1315 non-@code{nil}, only output from that process is handled, suspending output
1316 from other processes until some output has been received from that
1317 process or the timeout expires. If @var{just-this-one} is an integer,
1318 also inhibit running timers. This feature is generally not
1319 recommended, but may be necessary for specific applications, such as
1322 The function @code{accept-process-output} returns non-@code{nil} if it
1323 did get some output, or @code{nil} if the timeout expired before output
1328 @section Sentinels: Detecting Process Status Changes
1329 @cindex process sentinel
1332 A @dfn{process sentinel} is a function that is called whenever the
1333 associated process changes status for any reason, including signals
1334 (whether sent by Emacs or caused by the process's own actions) that
1335 terminate, stop, or continue the process. The process sentinel is
1336 also called if the process exits. The sentinel receives two
1337 arguments: the process for which the event occurred, and a string
1338 describing the type of event.
1340 The string describing the event looks like one of the following:
1344 @code{"finished\n"}.
1347 @code{"exited abnormally with code @var{exitcode}\n"}.
1350 @code{"@var{name-of-signal}\n"}.
1353 @code{"@var{name-of-signal} (core dumped)\n"}.
1356 A sentinel runs only while Emacs is waiting (e.g., for terminal
1357 input, or for time to elapse, or for process output). This avoids the
1358 timing errors that could result from running them at random places in
1359 the middle of other Lisp programs. A program can wait, so that
1360 sentinels will run, by calling @code{sit-for} or @code{sleep-for}
1361 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
1362 Output}). Emacs also allows sentinels to run when the command loop is
1363 reading input. @code{delete-process} calls the sentinel when it
1364 terminates a running process.
1366 Emacs does not keep a queue of multiple reasons to call the sentinel
1367 of one process; it records just the current status and the fact that
1368 there has been a change. Therefore two changes in status, coming in
1369 quick succession, can call the sentinel just once. However, process
1370 termination will always run the sentinel exactly once. This is
1371 because the process status can't change again after termination.
1373 Emacs explicitly checks for output from the process before running
1374 the process sentinel. Once the sentinel runs due to process
1375 termination, no further output can arrive from the process.
1377 A sentinel that writes the output into the buffer of the process
1378 should check whether the buffer is still alive. If it tries to insert
1379 into a dead buffer, it will get an error. If the buffer is dead,
1380 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
1382 Quitting is normally inhibited within a sentinel---otherwise, the
1383 effect of typing @kbd{C-g} at command level or to quit a user command
1384 would be unpredictable. If you want to permit quitting inside a
1385 sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the
1386 right way to do this is with the macro @code{with-local-quit}.
1389 If an error happens during execution of a sentinel, it is caught
1390 automatically, so that it doesn't stop the execution of whatever
1391 programs was running when the sentinel was started. However, if
1392 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1393 off. This makes it possible to use the Lisp debugger to debug the
1394 sentinel. @xref{Debugger}.
1396 While a sentinel is running, the process sentinel is temporarily
1397 set to @code{nil} so that the sentinel won't run recursively.
1398 For this reason it is not possible for a sentinel to specify
1401 In earlier Emacs versions, every sentinel that did regular expression
1402 searching or matching had to explicitly save and restore the match data.
1403 Now Emacs does this automatically for sentinels; they never need to do
1404 it explicitly. @xref{Match Data}.
1406 @defun set-process-sentinel process sentinel
1407 This function associates @var{sentinel} with @var{process}. If
1408 @var{sentinel} is @code{nil}, then the process will have no sentinel.
1409 The default behavior when there is no sentinel is to insert a message in
1410 the process's buffer when the process status changes.
1412 Changes in process sentinel take effect immediately---if the sentinel
1413 is slated to be run but has not been called yet, and you specify a new
1414 sentinel, the eventual call to the sentinel will use the new one.
1418 (defun msg-me (process event)
1420 (format "Process: %s had the event `%s'" process event)))
1421 (set-process-sentinel (get-process "shell") 'msg-me)
1425 (kill-process (get-process "shell"))
1426 @print{} Process: #<process shell> had the event `killed'
1427 @result{} #<process shell>
1432 @defun process-sentinel process
1433 This function returns the sentinel of @var{process}, or @code{nil} if it
1437 @defun waiting-for-user-input-p
1438 While a sentinel or filter function is running, this function returns
1439 non-@code{nil} if Emacs was waiting for keyboard input from the user at
1440 the time the sentinel or filter function was called, @code{nil} if it
1444 @node Query Before Exit
1445 @section Querying Before Exit
1447 When Emacs exits, it terminates all its subprocesses by sending them
1448 the @code{SIGHUP} signal. Because subprocesses may be doing
1449 valuable work, Emacs normally asks the user to confirm that it is ok
1450 to terminate them. Each process has a query flag which, if
1451 non-@code{nil}, says that Emacs should ask for confirmation before
1452 exiting and thus killing that process. The default for the query flag
1453 is @code{t}, meaning @emph{do} query.
1455 @tindex process-query-on-exit-flag
1456 @defun process-query-on-exit-flag process
1457 This returns the query flag of @var{process}.
1460 @tindex set-process-query-on-exit-flag
1461 @defun set-process-query-on-exit-flag process flag
1462 This function sets the query flag of @var{process} to @var{flag}. It
1467 ;; @r{Don't query about the shell process}
1468 (set-process-query-on-exit-flag (get-process "shell") nil)
1474 @defun process-kill-without-query process &optional do-query
1475 This function clears the query flag of @var{process}, so that
1476 Emacs will not query the user on account of that process.
1478 Actually, the function does more than that: it returns the old value of
1479 the process's query flag, and sets the query flag to @var{do-query}.
1480 Please don't use this function to do those things any more---please
1481 use the newer, cleaner functions @code{process-query-on-exit-flag} and
1482 @code{set-process-query-on-exit-flag} in all but the simplest cases.
1483 The only way you should use @code{process-kill-without-query} nowadays
1488 ;; @r{Don't query about the shell process}
1489 (process-kill-without-query (get-process "shell"))
1494 @node Transaction Queues
1495 @section Transaction Queues
1496 @cindex transaction queue
1498 You can use a @dfn{transaction queue} to communicate with a subprocess
1499 using transactions. First use @code{tq-create} to create a transaction
1500 queue communicating with a specified process. Then you can call
1501 @code{tq-enqueue} to send a transaction.
1503 @defun tq-create process
1504 This function creates and returns a transaction queue communicating with
1505 @var{process}. The argument @var{process} should be a subprocess
1506 capable of sending and receiving streams of bytes. It may be a child
1507 process, or it may be a TCP connection to a server, possibly on another
1511 @defun tq-enqueue queue question regexp closure fn &optional delay-question
1512 This function sends a transaction to queue @var{queue}. Specifying the
1513 queue has the effect of specifying the subprocess to talk to.
1515 The argument @var{question} is the outgoing message that starts the
1516 transaction. The argument @var{fn} is the function to call when the
1517 corresponding answer comes back; it is called with two arguments:
1518 @var{closure}, and the answer received.
1520 The argument @var{regexp} is a regular expression that should match
1521 text at the end of the entire answer, but nothing before; that's how
1522 @code{tq-enqueue} determines where the answer ends.
1524 If the argument @var{delay-question} is non-nil, delay sending this
1525 question until the process has finished replying to any previous
1526 questions. This produces more reliable results with some processes."
1528 The return value of @code{tq-enqueue} itself is not meaningful.
1531 @defun tq-close queue
1532 Shut down transaction queue @var{queue}, waiting for all pending transactions
1533 to complete, and then terminate the connection or child process.
1536 Transaction queues are implemented by means of a filter function.
1537 @xref{Filter Functions}.
1540 @section Network Connections
1541 @cindex network connection
1545 Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
1546 connections to other processes on the same machine or other machines.
1547 A network connection is handled by Lisp much like a subprocess, and is
1548 represented by a process object. However, the process you are
1549 communicating with is not a child of the Emacs process, so it has no
1550 process @acronym{ID}, and you can't kill it or send it signals. All you
1551 can do is send and receive data. @code{delete-process} closes the
1552 connection, but does not kill the program at the other end; that
1553 program must decide what to do about closure of the connection.
1555 Lisp programs can listen for connections by creating network
1556 servers. A network server is also represented by a kind of process
1557 object, but unlike a network connection, the network server never
1558 transfers data itself. When it receives a connection request, it
1559 creates a new network connection to represent the connection just
1560 made. (The network connection inherits certain information, including
1561 the process plist, from the server.) The network server then goes
1562 back to listening for more connection requests.
1564 Network connections and servers are created by calling
1565 @code{make-network-process} with an argument list consisting of
1566 keyword/argument pairs, for example @code{:server t} to create a
1567 server process, or @code{:type 'datagram} to create a datagram
1568 connection. @xref{Low-Level Network}, for details. You can also use
1569 the @code{open-network-stream} function described below.
1571 You can distinguish process objects representing network connections
1572 and servers from those representing subprocesses with the
1573 @code{process-status} function. The possible status values for
1574 network connections are @code{open}, @code{closed}, @code{connect},
1575 and @code{failed}. For a network server, the status is always
1576 @code{listen}. None of those values is possible for a real
1577 subprocess. @xref{Process Information}.
1579 You can stop and resume operation of a network process by calling
1580 @code{stop-process} and @code{continue-process}. For a server
1581 process, being stopped means not accepting new connections. (Up to 5
1582 connection requests will be queued for when you resume the server; you
1583 can increase this limit, unless it is imposed by the operating
1584 system.) For a network stream connection, being stopped means not
1585 processing input (any arriving input waits until you resume the
1586 connection). For a datagram connection, some number of packets may be
1587 queued but input may be lost. You can use the function
1588 @code{process-command} to determine whether a network connection or
1589 server is stopped; a non-@code{nil} value means yes.
1591 @defun open-network-stream name buffer-or-name host service
1592 This function opens a TCP connection, and returns a process object
1593 that represents the connection.
1595 The @var{name} argument specifies the name for the process object. It
1596 is modified as necessary to make it unique.
1598 The @var{buffer-or-name} argument is the buffer to associate with the
1599 connection. Output from the connection is inserted in the buffer,
1600 unless you specify a filter function to handle the output. If
1601 @var{buffer-or-name} is @code{nil}, it means that the connection is not
1602 associated with any buffer.
1604 The arguments @var{host} and @var{service} specify where to connect to;
1605 @var{host} is the host name (a string), and @var{service} is the name of
1606 a defined network service (a string) or a port number (an integer).
1609 @defun process-contact process &optional key
1610 This function returns information about how a network process was set
1611 up. For a connection, when @var{key} is @code{nil}, it returns
1612 @code{(@var{hostname} @var{service})} which specifies what you
1615 If @var{key} is @code{t}, the value is the complete status information
1616 for the connection or server; that is, the list of keywords and values
1617 specified in @code{make-network-process}, except that some of the
1618 values represent the current status instead of what you specified:
1622 The associated value is the process buffer.
1624 The associated value is the process filter function.
1626 The associated value is the process sentinel function.
1628 In a connection, this is the address in internal format of the remote peer.
1630 The local address, in internal format.
1632 In a server, if you specified @code{t} for @var{service},
1633 this value is the actual port number.
1636 @code{:local} and @code{:remote} are included even if they were not
1637 specified explicitly in @code{make-network-process}.
1639 If @var{key} is a keyword, the function returns the value corresponding
1642 For an ordinary child process, this function always returns @code{t}.
1645 @node Network Servers
1646 @section Network Servers
1648 You create a server by calling @code{make-network-process} with
1649 @code{:server t}. The server will listen for connection requests from
1650 clients. When it accepts a client connection request, that creates a
1651 new network connection, itself a process object, with the following
1656 The connection's process name is constructed by concatenating the
1657 server process' @var{name} with a client identification string. The
1658 client identification string for an IPv4 connection looks like
1659 @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a
1660 unique number in brackets, as in @samp{<@var{nnn}>}. The number
1661 is unique for each connection in the Emacs session.
1664 If the server's filter is non-@code{nil}, the connection process does
1665 not get a separate process buffer; otherwise, Emacs creates a new
1666 buffer for the purpose. The buffer name is the server's buffer name
1667 or process name, concatenated with the client identification string.
1669 The server's process buffer value is never used directly by Emacs, but
1670 it is passed to the log function, which can log connections by
1671 inserting text there.
1674 The communication type and the process filter and sentinel are
1675 inherited from those of the server. The server never directly
1676 uses its filter and sentinel; their sole purpose is to initialize
1677 connections made to the server.
1680 The connection's process contact info is set according to the client's
1681 addressing information (typically an IP address and a port number).
1682 This information is associated with the @code{process-contact}
1683 keywords @code{:host}, @code{:service}, @code{:remote}.
1686 The connection's local address is set up according to the port
1687 number used for the connection.
1690 The client process' plist is initialized from the server's plist.
1697 A datagram connection communicates with individual packets rather
1698 than streams of data. Each call to @code{process-send} sends one
1699 datagram packet (@pxref{Input to Processes}), and each datagram
1700 received results in one call to the filter function.
1702 The datagram connection doesn't have to talk with the same remote
1703 peer all the time. It has a @dfn{remote peer address} which specifies
1704 where to send datagrams to. Each time an incoming datagram is passed
1705 to the filter function, the peer address is set to the address that
1706 datagram came from; that way, if the filter function sends a datagram,
1707 it will go back to that place. You can specify the remote peer
1708 address when you create the datagram connection using the
1709 @code{:remote} keyword. You can change it later on by calling
1710 @code{set-process-datagram-address}.
1712 @defun process-datagram-address process
1713 If @var{process} is a datagram connection or server, this function
1714 returns its remote peer address.
1717 @defun set-process-datagram-address process address
1718 If @var{process} is a datagram connection or server, this function
1719 sets its remote peer address to @var{address}.
1722 @node Low-Level Network
1723 @section Low-Level Network Access
1725 You can also create network connections by operating at a lower
1726 level that that of @code{open-network-stream}, using
1727 @code{make-network-process}.
1730 * Make Network:: Using @code{make-network-process}.
1731 * Network Options:: Further control over network connections.
1732 * Network Feature Testing:: Determining which network features work on
1733 the machine you are using.
1737 @subsection @code{make-network-process}
1739 The basic function for creating network connections and network
1740 servers is @code{make-network-process}. It can do either of those
1741 jobs, depending on the arguments you give it.
1743 @defun make-network-process &rest args
1744 This function creates a network connection or server and returns the
1745 process object that represents it. The arguments @var{args} are a
1746 list of keyword/argument pairs. Omitting a keyword is always
1747 equivalent to specifying it with value @code{nil}, except for
1748 @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here
1749 are the meaningful keywords:
1752 @item :name @var{name}
1753 Use the string @var{name} as the process name. It is modified if
1754 necessary to make it unique.
1756 @item :type @var{type}
1757 Specify the communication type. A value of @code{nil} specifies a
1758 stream connection (the default); @code{datagram} specifies a datagram
1759 connection. Both connections and servers can be of either type.
1761 @item :server @var{server-flag}
1762 If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
1763 create a connection. For a stream type server, @var{server-flag} may
1764 be an integer which then specifies the length of the queue of pending
1765 connections to the server. The default queue length is 5.
1767 @item :host @var{host}
1768 Specify the host to connect to. @var{host} should be a host name or
1769 internet address, as a string, or the symbol @code{local} to specify
1770 the local host. If you specify @var{host} for a server, it must
1771 specify a valid address for the local host, and only clients
1772 connecting to that address will be accepted.
1774 @item :service @var{service}
1775 @var{service} specifies a port number to connect to, or, for a server,
1776 the port number to listen on. It should be a service name that
1777 translates to a port number, or an integer specifying the port number
1778 directly. For a server, it can also be @code{t}, which means to let
1779 the system select an unused port number.
1781 @item :family @var{family}
1782 @var{family} specifies the address (and protocol) family for
1783 communication. @code{nil} means determine the proper address family
1784 automatically for the given @var{host} and @var{service}.
1785 @code{local} specifies a Unix socket, in which case @var{host} is
1786 ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6
1789 @item :local @var{local-address}
1790 For a server process, @var{local-address} is the address to listen on.
1791 It overrides @var{family}, @var{host} and @var{service}, and you
1792 may as well not specify them.
1794 @item :remote @var{remote-address}
1795 For a connection, @var{remote-address} is the address to connect to.
1796 It overrides @var{family}, @var{host} and @var{service}, and you
1797 may as well not specify them.
1799 For a datagram server, @var{remote-address} specifies the initial
1800 setting of the remote datagram address.
1802 The format of @var{local-address} or @var{remote-address} depends on
1807 An IPv4 address is represented as a five-element vector of four 8-bit
1808 integers and one 16-bit integer
1809 @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to
1810 numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number
1814 An IPv6 address is represented as a nine-element vector of 16-bit
1815 integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f}
1816 @var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address
1817 @var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and
1818 port number @var{p}.
1821 A local address is represented as a string which specifies the address
1822 in the local address space.
1825 An ``unsupported family'' address is represented by a cons
1826 @code{(@var{f} . @var{av})}, where @var{f} is the family number and
1827 @var{av} is a vector specifying the socket address using one element
1828 per address data byte. Do not rely on this format in portable code,
1829 as it may depend on implementation defined constants, data sizes, and
1830 data structure alignment.
1833 @item :nowait @var{bool}
1834 If @var{bool} is non-@code{nil} for a stream connection, return
1835 without waiting for the connection to complete. When the connection
1836 succeeds or fails, Emacs will call the sentinel function, with a
1837 second argument matching @code{"open"} (if successful) or
1838 @code{"failed"}. The default is to block, so that
1839 @code{make-network-process} does not return until the connection
1840 has succeeded or failed.
1842 @item :stop @var{stopped}
1843 Start the network connection or server in the `stopped' state if
1844 @var{stopped} is non-@code{nil}.
1846 @item :buffer @var{buffer}
1847 Use @var{buffer} as the process buffer.
1849 @item :coding @var{coding}
1850 Use @var{coding} as the coding system for this process. To specify
1851 different coding systems for decoding data from the connection and for
1852 encoding data sent to it, specify @code{(@var{decoding} .
1853 @var{encoding})} for @var{coding}.
1855 If you don't specify this keyword at all, the default
1856 is to determine the coding systems from the data.
1858 @item :noquery @var{query-flag}
1859 Initialize the process query flag to @var{query-flag}.
1860 @xref{Query Before Exit}.
1862 @item :filter @var{filter}
1863 Initialize the process filter to @var{filter}.
1865 @item :filter-multibyte @var{bool}
1866 If @var{bool} is non-@code{nil}, strings given to the process filter
1867 are multibyte, otherwise they are unibyte. If you don't specify this
1868 keyword at all, the default is that the strings are multibyte if
1869 @code{default-enable-multibyte-characters} is non-@code{nil}.
1871 @item :sentinel @var{sentinel}
1872 Initialize the process sentinel to @var{sentinel}.
1874 @item :log @var{log}
1875 Initialize the log function of a server process to @var{log}. The log
1876 function is called each time the server accepts a network connection
1877 from a client. The arguments passed to the log function are
1878 @var{server}, @var{connection}, and @var{message}, where @var{server}
1879 is the server process, @var{connection} is the new process for the
1880 connection, and @var{message} is a string describing what has
1883 @item :plist @var{plist}
1884 Initialize the process plist to @var{plist}.
1887 The original argument list, modified with the actual connection
1888 information, is available via the @code{process-contact} function.
1891 @node Network Options
1892 @subsection Network Options
1894 The following network options can be specified when you create a
1895 network process. Except for @code{:reuseaddr}, you can also set or
1896 modify these options later, using @code{set-network-process-option}.
1898 For a server process, the options specified with
1899 @code{make-network-process} are not inherited by the client
1900 connections, so you will need to set the necessary options for each
1901 child connection as it is created.
1904 @item :bindtodevice @var{device-name}
1905 If @var{device-name} is a non-empty string identifying a network
1906 interface name (see @code{network-interface-list}), only handle
1907 packets received on that interface. If @var{device-name} is @code{nil}
1908 (the default), handle packets received on any interface.
1910 Using this option may require special privileges on some systems.
1912 @item :broadcast @var{broadcast-flag}
1913 If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
1914 process will receive datagram packet sent to a broadcast address, and
1915 be able to send packets to a broadcast address. Ignored for a stream
1918 @item :dontroute @var{dontroute-flag}
1919 If @var{dontroute-flag} is non-@code{nil}, the process can only send
1920 to hosts on the same network as the local host.
1922 @item :keepalive @var{keepalive-flag}
1923 If @var{keepalive-flag} is non-@code{nil} for a stream connection,
1924 enable exchange of low-level keep-alive messages.
1926 @item :linger @var{linger-arg}
1927 If @var{linger-arg} is non-@code{nil}, wait for successful
1928 transmission of all queued packets on the connection before it is
1929 deleted (see @code{delete-process}). If @var{linger-arg} is an
1930 integer, it specifies the maximum time in seconds to wait for queued
1931 packets to be sent before closing the connection. Default is
1932 @code{nil} which means to discard unsent queued packets when the
1935 @item :oobinline @var{oobinline-flag}
1936 If @var{oobinline-flag} is non-@code{nil} for a stream connection,
1937 receive out-of-band data in the normal data stream. Otherwise, ignore
1940 @item :priority @var{priority}
1941 Set the priority for packets sent on this connection to the integer
1942 @var{priority}. The interpretation of this number is protocol
1943 specific, such as setting the TOS (type of service) field on IP
1944 packets sent on this connection. It may also have system dependent
1945 effects, such as selecting a specific output queue on the network
1948 @item :reuseaddr @var{reuseaddr-flag}
1949 If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
1950 server process, allow this server to reuse a specific port number (see
1951 @code{:service}) unless another process on this host is already
1952 listening on that port. If @var{reuseaddr-flag} is @code{nil}, there
1953 may be a period of time after the last use of that port (by any
1954 process on the host), where it is not possible to make a new server on
1958 @defun set-network-process-option process option value
1959 This function sets or modifies a network option for network process
1960 @var{process}. See @code{make-network-process} for details of options
1961 @var{option} and their corresponding values @var{value}.
1963 The current setting of an option is available via the
1964 @code{process-contact} function.
1967 @node Network Feature Testing
1968 @subsection Testing Availability of Network Features
1970 To test for the availability of a given network feature, use
1971 @code{featurep} like this:
1974 (featurep 'make-network-process '(@var{keyword} @var{value}))
1978 The result of the first form is @code{t} if it works to specify
1979 @var{keyword} with value @var{value} in @code{make-network-process}.
1980 The result of the second form is @code{t} if @var{keyword} is
1981 supported by @code{make-network-process}. Here are some of the
1982 @var{keyword}---@var{value} pairs you can test in
1987 Non-@code{nil} if non-blocking connect is supported.
1988 @item (:type datagram)
1989 Non-@code{nil} if datagrams are supported.
1990 @item (:family local)
1991 Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported.
1992 @item (:family ipv6)
1993 Non-@code{nil} if IPv6 is supported.
1995 Non-@code{nil} if the system can select the port for a server.
1998 To test for the availability of a given network option, use
1999 @code{featurep} like this:
2002 (featurep 'make-network-process '@var{keyword})
2006 Here are some of the options you can test in this way.
2017 That particular network option is supported by
2018 @code{make-network-process} and @code{set-network-process-option}.
2022 @section Misc Network Facilities
2024 These additional functions are useful for creating and operating
2025 on network connections.
2027 @defun network-interface-list
2028 This function returns a list describing the network interfaces
2029 of the machine you are using. The value is an alist whose
2030 elements have the form @code{(@var{name} . @var{address})}.
2031 @var{address} has the same form as the @var{local-address}
2032 and @var{remote-address} arguments to @code{make-network-process}.
2035 @defun network-interface-info ifname
2036 This function returns information about the network interface named
2037 @var{ifname}. The value is a list of the form
2038 @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
2042 The internet protocol address.
2044 The broadcast address.
2048 The layer 2 address (Ethernet MAC address, for instance).
2050 The current flags of the interface.
2054 @defun format-network-address address &optional omit-port
2055 This function converts the Lisp representation of a network address to
2058 A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]}
2059 represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port
2060 number @var{p}. @code{format-network-address} converts that to the
2061 string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
2063 A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e}
2064 @var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address and port
2065 number. @code{format-network-address} converts that to the string
2066 @code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}.
2068 If the vector does not include the port number, @var{p}, or if
2069 @var{omit-port} is non-@code{nil}, the result does not include the
2070 @code{:@var{p}} suffix.
2074 @section Packing and Unpacking Byte Arrays
2076 This section describes how to pack and unpack arrays of bytes,
2077 usually for binary network protocols. These functions convert byte arrays
2078 to alists, and vice versa. The byte array can be represented as a
2079 unibyte string or as a vector of integers, while the alist associates
2080 symbols either with fixed-size objects or with recursive sub-alists.
2083 @cindex deserializing
2086 Conversion from byte arrays to nested alists is also known as
2087 @dfn{deserializing} or @dfn{unpacking}, while going in the opposite
2088 direction is also known as @dfn{serializing} or @dfn{packing}.
2091 * Bindat Spec:: Describing data layout.
2092 * Bindat Functions:: Doing the unpacking and packing.
2093 * Bindat Examples:: Samples of what bindat.el can do for you!
2097 @subsection Describing Data Layout
2099 To control unpacking and packing, you write a @dfn{data layout
2100 specification}, a special nested list describing named and typed
2101 @dfn{fields}. This specification controls length of each field to be
2102 processed, and how to pack or unpack it.
2106 @cindex little endian
2107 @cindex network byte ordering
2108 A field's @dfn{type} describes the size (in bytes) of the object
2109 that the field represents and, in the case of multibyte fields, how
2110 the bytes are ordered within the field. The two possible orderings
2111 are ``big endian'' (also known as ``network byte ordering'') and
2112 ``little endian''. For instance, the number @code{#x23cd} (decimal
2113 9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
2114 and in little endian, @code{#xcd} @code{#x23}. Here are the possible
2120 Unsigned byte, with length 1.
2125 Unsigned integer in network byte order, with length 2.
2128 Unsigned integer in network byte order, with length 3.
2133 Unsigned integer in network byte order, with length 4.
2134 Note: These values may be limited by Emacs' integer implementation limits.
2139 Unsigned integer in little endian order, with length 2, 3 and 4, respectively.
2142 String of length @var{len}.
2144 @item strz @var{len}
2145 Zero-terminated string of length @var{len}.
2148 Vector of @var{len} bytes.
2151 Four-byte vector representing an Internet address. For example:
2152 @code{[127 0 0 1]} for localhost.
2154 @item bits @var{len}
2155 List of set bits in @var{len} bytes. The bytes are taken in big
2156 endian order and the bits are numbered starting with @code{8 *
2157 @var{len} @minus{} 1} and ending with zero. For example: @code{bits
2158 2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and
2159 @code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}.
2161 @item (eval @var{form})
2162 @var{form} is a Lisp expression evaluated at the moment the field is
2163 unpacked or packed. The result of the evaluation should be one of the
2164 above-listed type specifications.
2167 A field specification generally has the form @code{([@var{name}]
2168 @var{handler})}. The square braces indicate that @var{name} is
2169 optional. (Don't use names that are symbols meaningful as type
2170 specifications (above) or handler specifications (below), since that
2171 would be ambiguous.) @var{name} can be a symbol or the expression
2172 @code{(eval @var{form})}, in which case @var{form} should evaluate to
2175 @var{handler} describes how to unpack or pack the field and can be one
2180 Unpack/pack this field according to the type specification @var{type}.
2182 @item eval @var{form}
2183 Evaluate @var{form}, a Lisp expression, for side-effect only. If the
2184 field name is specified, the value is bound to that field name.
2185 @var{form} can access and update these dynamically bound variables:
2189 The data as a byte array.
2192 Current position of the unpacking or packing operation.
2198 Value of the last field processed.
2201 @item fill @var{len}
2202 Skip @var{len} bytes. In packing, this leaves them unchanged,
2203 which normally means they remain zero. In unpacking, this means
2206 @item align @var{len}
2207 Skip to the next multiple of @var{len} bytes.
2209 @item struct @var{spec-name}
2210 Process @var{spec-name} as a sub-specification. This describes a
2211 structure nested within another structure.
2213 @item union @var{form} (@var{tag} @var{spec})@dots{}
2214 @c ??? I don't see how one would actually use this.
2215 @c ??? what kind of expression would be useful for @var{form}?
2216 Evaluate @var{form}, a Lisp expression, find the first @var{tag}
2217 that matches it, and process its associated data layout specification
2218 @var{spec}. Matching can occur in one of three ways:
2222 If a @var{tag} has the form @code{(eval @var{expr})}, evaluate
2223 @var{expr} with the variable @code{tag} dynamically bound to the value
2224 of @var{form}. A non-@code{nil} result indicates a match.
2227 @var{tag} matches if it is @code{equal} to the value of @var{form}.
2230 @var{tag} matches unconditionally if it is @code{t}.
2233 @item repeat @var{count} @var{field-spec}@dots{}
2234 @var{count} may be an integer, or a list of one element naming a
2235 previous field. For correct operation, each @var{field-spec} must
2237 @c ??? What does it MEAN?
2240 @node Bindat Functions
2241 @subsection Functions to Unpack and Pack Bytes
2243 In the following documentation, @var{spec} refers to a data layout
2244 specification, @code{raw-data} to a byte array, and @var{struct} to an
2245 alist representing unpacked field data.
2247 @defun bindat-unpack spec raw-data &optional pos
2248 This function unpacks data from the byte array @code{raw-data}
2249 according to @var{spec}. Normally this starts unpacking at the
2250 beginning of the byte array, but if @var{pos} is non-@code{nil}, it
2251 specifies a zero-based starting position to use instead.
2253 The value is an alist or nested alist in which each element describes
2257 @defun bindat-get-field struct &rest name
2258 This function selects a field's data from the nested alist
2259 @var{struct}. Usually @var{struct} was returned by
2260 @code{bindat-unpack}. If @var{name} corresponds to just one argument,
2261 that means to extract a top-level field value. Multiple @var{name}
2262 arguments specify repeated lookup of sub-structures. An integer name
2263 acts as an array index.
2265 For example, if @var{name} is @code{(a b 2 c)}, that means to find
2266 field @code{c} in the third element of subfield @code{b} of field
2267 @code{a}. (This corresponds to @code{struct.a.b[2].c} in C.)
2270 @defun bindat-length spec struct
2271 @c ??? I don't understand this at all -- rms
2272 This function returns the length in bytes of @var{struct}, according
2276 @defun bindat-pack spec struct &optional raw-data pos
2277 This function returns a byte array packed according to @var{spec} from
2278 the data in the alist @var{struct}. Normally it creates and fills a
2279 new byte array starting at the beginning. However, if @var{raw-data}
2280 is non-@code{nil}, it specifies a pre-allocated string or vector to
2281 pack into. If @var{pos} is non-@code{nil}, it specifies the starting
2282 offset for packing into @code{raw-data}.
2284 @c ??? Isn't this a bug? Shouldn't it always be unibyte?
2285 Note: The result is a multibyte string; use @code{string-make-unibyte}
2286 on it to make it unibyte if necessary.
2289 @defun bindat-ip-to-string ip
2290 Convert the Internet address vector @var{ip} to a string in the usual
2294 (bindat-ip-to-string [127 0 0 1])
2295 @result{} "127.0.0.1"
2299 @node Bindat Examples
2300 @subsection Examples of Byte Unpacking and Packing
2302 Here is a complete example of byte unpacking and packing:
2305 (defvar fcookie-index-spec
2313 (:offset repeat (:count)
2315 "Description of a fortune cookie index file's contents.")
2317 (defun fcookie (cookies &optional index)
2318 "Display a random fortune cookie from file COOKIES.
2319 Optional second arg INDEX specifies the associated index
2320 filename, which is by default constructed by appending
2321 \".dat\" to COOKIES. Display cookie text in possibly
2322 new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
2323 is COOKIES without the directory part."
2324 (interactive "fCookies file: ")
2325 (let* ((info (with-temp-buffer
2326 (insert-file-contents-literally
2327 (or index (concat cookies ".dat")))
2328 (bindat-unpack fcookie-index-spec
2330 (sel (random (bindat-get-field info :count)))
2331 (beg (cdar (bindat-get-field info :offset sel)))
2332 (end (or (cdar (bindat-get-field info
2334 (nth 7 (file-attributes cookies)))))
2337 (format "*Fortune Cookie: %s*"
2338 (file-name-nondirectory cookies))))
2340 (insert-file-contents-literally
2341 cookies nil beg (- end 3))))
2343 (defun fcookie-create-index (cookies &optional index delim)
2344 "Scan file COOKIES, and write out its index file.
2345 Optional second arg INDEX specifies the index filename,
2346 which is by default constructed by appending \".dat\" to
2347 COOKIES. Optional third arg DELIM specifies the unibyte
2348 character which, when found on a line of its own in
2349 COOKIES, indicates the border between entries."
2350 (interactive "fCookies file: ")
2351 (setq delim (or delim ?%))
2352 (let ((delim-line (format "\n%c\n" delim))
2355 min p q len offsets)
2356 (unless (= 3 (string-bytes delim-line))
2357 (error "Delimiter cannot be represented in one byte"))
2359 (insert-file-contents-literally cookies)
2360 (while (and (setq p (point))
2361 (search-forward delim-line (point-max) t)
2362 (setq len (- (point) 3 p)))
2363 (setq count (1+ count)
2365 min (min (or min max) len)
2366 offsets (cons (1- p) offsets))))
2368 (set-buffer-multibyte nil)
2370 (string-make-unibyte
2379 (:offset . ,(mapcar (lambda (o)
2380 (list (cons :foo o)))
2381 (nreverse offsets)))))))
2382 (let ((coding-system-for-write 'raw-text-unix))
2383 (write-file (or index (concat cookies ".dat")))))))
2386 Following is an example of defining and unpacking a complex structure.
2387 Consider the following C structures:
2391 unsigned long dest_ip;
2392 unsigned long src_ip;
2393 unsigned short dest_port;
2394 unsigned short src_port;
2399 unsigned char opcode;
2400 unsigned long length; /* In little endian order */
2401 unsigned char id[8]; /* null-terminated string */
2402 unsigned char data[/* (length + 3) & ~3 */];
2406 struct header header;
2407 unsigned char items;
2408 unsigned char filler[3];
2409 struct data item[/* items */];
2414 The corresponding data layout specification:
2426 (length u16r) ;; little endian order
2432 '((header struct header-spec)
2435 (item repeat (items)
2436 (struct data-spec))))
2439 A binary data representation:
2443 [ 192 168 1 100 192 168 1 101 01 28 21 32 2 0 0 0
2444 2 3 5 0 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
2445 1 4 7 0 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
2448 The corresponding decoded structure:
2451 (setq decoded (bindat-unpack packet-spec binary-data))
2454 (dest-ip . [192 168 1 100])
2455 (src-ip . [192 168 1 101])
2459 (item ((data . [1 2 3 4 5])
2464 ((data . [6 7 8 9 10 11 12])
2471 Fetching data from this structure:
2474 (bindat-get-field decoded 'item 1 'id)
2479 arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a