2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007 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
149 @cindex arguments for shell commands
150 @cindex shell command arguments
152 Lisp programs sometimes need to run a shell and give it a command
153 that contains file names that were specified by the user. These
154 programs ought to be able to support any valid file name. But the shell
155 gives special treatment to certain characters, and if these characters
156 occur in the file name, they will confuse the shell. To handle these
157 characters, use the function @code{shell-quote-argument}:
159 @defun shell-quote-argument argument
160 This function returns a string which represents, in shell syntax,
161 an argument whose actual contents are @var{argument}. It should
162 work reliably to concatenate the return value into a shell command
163 and then pass it to a shell for execution.
165 Precisely what this function does depends on your operating system. The
166 function is designed to work with the syntax of your system's standard
167 shell; if you use an unusual shell, you will need to redefine this
171 ;; @r{This example shows the behavior on GNU and Unix systems.}
172 (shell-quote-argument "foo > bar")
173 @result{} "foo\\ \\>\\ bar"
175 ;; @r{This example shows the behavior on MS-DOS and MS-Windows.}
176 (shell-quote-argument "foo > bar")
177 @result{} "\"foo > bar\""
180 Here's an example of using @code{shell-quote-argument} to construct
185 (shell-quote-argument oldfile)
187 (shell-quote-argument newfile))
191 @node Synchronous Processes
192 @section Creating a Synchronous Process
193 @cindex synchronous subprocess
195 After a @dfn{synchronous process} is created, Emacs waits for the
196 process to terminate before continuing. Starting Dired on GNU or
197 Unix@footnote{On other systems, Emacs uses a Lisp emulation of
198 @code{ls}; see @ref{Contents of Directories}.} is an example of this: it
199 runs @code{ls} in a synchronous process, then modifies the output
200 slightly. Because the process is synchronous, the entire directory
201 listing arrives in the buffer before Emacs tries to do anything with it.
203 While Emacs waits for the synchronous subprocess to terminate, the
204 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
205 the subprocess with a @code{SIGINT} signal; but it waits until the
206 subprocess actually terminates before quitting. If during that time the
207 user types another @kbd{C-g}, that kills the subprocess instantly with
208 @code{SIGKILL} and quits immediately (except on MS-DOS, where killing
209 other processes doesn't work). @xref{Quitting}.
211 The synchronous subprocess functions return an indication of how the
214 The output from a synchronous subprocess is generally decoded using a
215 coding system, much like text read from a file. The input sent to a
216 subprocess by @code{call-process-region} is encoded using a coding
217 system, much like text written into a file. @xref{Coding Systems}.
219 @defun call-process program &optional infile destination display &rest args
220 This function calls @var{program} in a separate process and waits for
223 The standard input for the process comes from file @var{infile} if
224 @var{infile} is not @code{nil}, and from the null device otherwise.
225 The argument @var{destination} says where to put the process output.
226 Here are the possibilities:
230 Insert the output in that buffer, before point. This includes both the
231 standard output stream and the standard error stream of the process.
234 Insert the output in a buffer with that name, before point.
237 Insert the output in the current buffer, before point.
243 Discard the output, and return @code{nil} immediately without waiting
244 for the subprocess to finish.
246 In this case, the process is not truly synchronous, since it can run in
247 parallel with Emacs; but you can think of it as synchronous in that
248 Emacs is essentially finished with the subprocess as soon as this
251 MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
254 @item @code{(@var{real-destination} @var{error-destination})}
255 Keep the standard output stream separate from the standard error stream;
256 deal with the ordinary output as specified by @var{real-destination},
257 and dispose of the error output according to @var{error-destination}.
258 If @var{error-destination} is @code{nil}, that means to discard the
259 error output, @code{t} means mix it with the ordinary output, and a
260 string specifies a file name to redirect error output into.
262 You can't directly specify a buffer to put the error output in; that is
263 too difficult to implement. But you can achieve this result by sending
264 the error output to a temporary file and then inserting the file into a
268 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
269 the buffer as output is inserted. (However, if the coding system chosen
270 for decoding output is @code{undecided}, meaning deduce the encoding
271 from the actual data, then redisplay sometimes cannot continue once
272 non-@acronym{ASCII} characters are encountered. There are fundamental
273 reasons why it is hard to fix this; see @ref{Output from Processes}.)
275 Otherwise the function @code{call-process} does no redisplay, and the
276 results become visible on the screen only when Emacs redisplays that
277 buffer in the normal course of events.
279 The remaining arguments, @var{args}, are strings that specify command
280 line arguments for the program.
282 The value returned by @code{call-process} (unless you told it not to
283 wait) indicates the reason for process termination. A number gives the
284 exit status of the subprocess; 0 means success, and any other value
285 means failure. If the process terminated with a signal,
286 @code{call-process} returns a string describing the signal.
288 In the examples below, the buffer @samp{foo} is current.
292 (call-process "pwd" nil t)
295 ---------- Buffer: foo ----------
296 /usr/user/lewis/manual
297 ---------- Buffer: foo ----------
301 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
304 ---------- Buffer: bar ----------
305 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
307 ---------- Buffer: bar ----------
311 Here is a good example of the use of @code{call-process}, which used to
312 be found in the definition of @code{insert-directory}:
316 (call-process insert-directory-program nil t nil @var{switches}
318 (concat (file-name-as-directory file) ".")
324 @defun process-file program &optional infile buffer display &rest args
325 This function processes files synchronously in a separate process. It
326 is similar to @code{call-process} but may invoke a file handler based
327 on the value of the variable @code{default-directory}. The current
328 working directory of the subprocess is @code{default-directory}.
330 The arguments are handled in almost the same way as for
331 @code{call-process}, with the following differences:
333 Some file handlers may not support all combinations and forms of the
334 arguments @var{infile}, @var{buffer}, and @var{display}. For example,
335 some file handlers might behave as if @var{display} were @code{nil},
336 regardless of the value actually passed. As another example, some
337 file handlers might not support separating standard output and error
338 output by way of the @var{buffer} argument.
340 If a file handler is invoked, it determines the program to run based
341 on the first argument @var{program}. For instance, consider that a
342 handler for remote files is invoked. Then the path that is used for
343 searching the program might be different than @code{exec-path}.
345 The second argument @var{infile} may invoke a file handler. The file
346 handler could be different from the handler chosen for the
347 @code{process-file} function itself. (For example,
348 @code{default-directory} could be on a remote host, whereas
349 @var{infile} is on another remote host. Or @code{default-directory}
350 could be non-special, whereas @var{infile} is on a remote host.)
352 If @var{buffer} is a list of the form @code{(@var{real-destination}
353 @var{error-destination})}, and @var{error-destination} names a file,
354 then the same remarks as for @var{infile} apply.
356 The remaining arguments (@var{args}) will be passed to the process
357 verbatim. Emacs is not involved in processing file names that are
358 present in @var{args}. To avoid confusion, it may be best to avoid
359 absolute file names in @var{args}, but rather to specify all file
360 names as relative to @code{default-directory}. The function
361 @code{file-relative-name} is useful for constructing such relative
365 @defun call-process-region start end program &optional delete destination display &rest args
366 This function sends the text from @var{start} to @var{end} as
367 standard input to a process running @var{program}. It deletes the text
368 sent if @var{delete} is non-@code{nil}; this is useful when
369 @var{destination} is @code{t}, to insert the output in the current
370 buffer in place of the input.
372 The arguments @var{destination} and @var{display} control what to do
373 with the output from the subprocess, and whether to update the display
374 as it comes in. For details, see the description of
375 @code{call-process}, above. If @var{destination} is the integer 0,
376 @code{call-process-region} discards the output and returns @code{nil}
377 immediately, without waiting for the subprocess to finish (this only
378 works if asynchronous subprocesses are supported).
380 The remaining arguments, @var{args}, are strings that specify command
381 line arguments for the program.
383 The return value of @code{call-process-region} is just like that of
384 @code{call-process}: @code{nil} if you told it to return without
385 waiting; otherwise, a number or string which indicates how the
386 subprocess terminated.
388 In the following example, we use @code{call-process-region} to run the
389 @code{cat} utility, with standard input being the first five characters
390 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
391 standard input into its standard output. Since the argument
392 @var{destination} is @code{t}, this output is inserted in the current
397 ---------- Buffer: foo ----------
399 ---------- Buffer: foo ----------
403 (call-process-region 1 6 "cat" nil t)
406 ---------- Buffer: foo ----------
408 ---------- Buffer: foo ----------
412 The @code{shell-command-on-region} command uses
413 @code{call-process-region} like this:
419 shell-file-name ; @r{Name of program.}
420 nil ; @r{Do not delete region.}
421 buffer ; @r{Send output to @code{buffer}.}
422 nil ; @r{No redisplay during output.}
423 "-c" command) ; @r{Arguments for the shell.}
428 @defun call-process-shell-command command &optional infile destination display &rest args
429 This function executes the shell command @var{command} synchronously
430 in a separate process. The final arguments @var{args} are additional
431 arguments to add at the end of @var{command}. The other arguments
432 are handled as in @code{call-process}.
435 @defun process-file-shell-command command &optional infile destination display &rest args
436 This function is like @code{call-process-shell-command}, but uses
437 @code{process-file} internally. Depending on @code{default-directory},
438 @var{command} can be executed also on remote hosts.
441 @defun shell-command-to-string command
442 This function executes @var{command} (a string) as a shell command,
443 then returns the command's output as a string.
446 @node Asynchronous Processes
447 @section Creating an Asynchronous Process
448 @cindex asynchronous subprocess
450 After an @dfn{asynchronous process} is created, Emacs and the subprocess
451 both continue running immediately. The process thereafter runs
452 in parallel with Emacs, and the two can communicate with each other
453 using the functions described in the following sections. However,
454 communication is only partially asynchronous: Emacs sends data to the
455 process only when certain functions are called, and Emacs accepts data
456 from the process only when Emacs is waiting for input or for a time
459 Here we describe how to create an asynchronous process.
461 @defun start-process name buffer-or-name program &rest args
462 This function creates a new asynchronous subprocess and starts the
463 program @var{program} running in it. It returns a process object that
464 stands for the new subprocess in Lisp. The argument @var{name}
465 specifies the name for the process object; if a process with this name
466 already exists, then @var{name} is modified (by appending @samp{<1>},
467 etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to
468 associate with the process.
470 The remaining arguments, @var{args}, are strings that specify command
471 line arguments for the program.
473 In the example below, the first process is started and runs (rather,
474 sleeps) for 100 seconds. Meanwhile, the second process is started, and
475 given the name @samp{my-process<1>} for the sake of uniqueness. It
476 inserts the directory listing at the end of the buffer @samp{foo},
477 before the first process finishes. Then it finishes, and a message to
478 that effect is inserted in the buffer. Much later, the first process
479 finishes, and another message is inserted in the buffer for it.
483 (start-process "my-process" "foo" "sleep" "100")
484 @result{} #<process my-process>
488 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
489 @result{} #<process my-process<1>>
491 ---------- Buffer: foo ----------
493 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
494 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
496 Process my-process<1> finished
498 Process my-process finished
499 ---------- Buffer: foo ----------
504 @defun start-file-process name buffer-or-name program &rest args
505 Like @code{start-process}, this function starts a new asynchronous
506 subprocess running @var{program} in it. The corresponding process
509 If @code{default-directory} corresponds to a file handler, that
510 handler is invoked. @var{program} runs then on a remote host which is
511 identified by @code{default-directory}. The local part of
512 @code{default-directory} is the working directory of the subprocess.
514 @var{program} and @var{program-args} might be file names. They are not
515 objects of file handler invocation.
517 Depending on the implementation of the file handler, it might not be
518 possible to apply @code{process-filter} or @code{process-sentinel} to
519 the resulting process object (@pxref{Filter Functions}, @pxref{Sentinels}).
521 Some file handlers may not support @code{start-file-process} (for
522 example @code{ange-ftp-hook-function}). It returns then @code{nil}.
525 @defun start-process-shell-command name buffer-or-name command &rest command-args
526 This function is like @code{start-process} except that it uses a shell
527 to execute the specified command. The argument @var{command} is a shell
528 command name, and @var{command-args} are the arguments for the shell
529 command. The variable @code{shell-file-name} specifies which shell to
532 The point of running a program through the shell, rather than directly
533 with @code{start-process}, is so that you can employ shell features such
534 as wildcards in the arguments. It follows that if you include an
535 arbitrary user-specified arguments in the command, you should quote it
536 with @code{shell-quote-argument} first, so that any special shell
537 characters do @emph{not} have their special shell meanings. @xref{Shell
541 @defun start-file-process-shell-command name buffer-or-name command &rest command-args
542 This function is like @code{start-process-shell-command}, but uses
543 @code{start-file-process} internally. By this, @var{command} can be
544 executed also on remote hosts, depending on @code{default-directory}.
547 @defvar process-connection-type
549 @cindex @acronym{PTY}s
550 This variable controls the type of device used to communicate with
551 asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are
552 used, when available. Otherwise, pipes are used.
554 @acronym{PTY}s are usually preferable for processes visible to the user, as
555 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
556 etc.) to work between the process and its children, whereas pipes do
557 not. For subprocesses used for internal purposes by programs, it is
558 often better to use a pipe, because they are more efficient. In
559 addition, the total number of @acronym{PTY}s is limited on many systems and
560 it is good not to waste them.
562 The value of @code{process-connection-type} takes effect when
563 @code{start-process} is called. So you can specify how to communicate
564 with one subprocess by binding the variable around the call to
565 @code{start-process}.
569 (let ((process-connection-type nil)) ; @r{Use a pipe.}
570 (start-process @dots{}))
574 To determine whether a given subprocess actually got a pipe or a
575 @acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process
579 @node Deleting Processes
580 @section Deleting Processes
581 @cindex deleting processes
583 @dfn{Deleting a process} disconnects Emacs immediately from the
584 subprocess. Processes are deleted automatically after they terminate,
585 but not necessarily right away. You can delete a process explicitly
586 at any time. If you delete a terminated process explicitly before it
587 is deleted automatically, no harm results. Deleting a running
588 process sends a signal to terminate it (and its child processes if
589 any), and calls the process sentinel if it has one. @xref{Sentinels}.
591 When a process is deleted, the process object itself continues to
592 exist as long as other Lisp objects point to it. All the Lisp
593 primitives that work on process objects accept deleted processes, but
594 those that do I/O or send signals will report an error. The process
595 mark continues to point to the same place as before, usually into a
596 buffer where output from the process was being inserted.
598 @defopt delete-exited-processes
599 This variable controls automatic deletion of processes that have
600 terminated (due to calling @code{exit} or to a signal). If it is
601 @code{nil}, then they continue to exist until the user runs
602 @code{list-processes}. Otherwise, they are deleted immediately after
606 @defun delete-process process
607 This function deletes a process, killing it with a @code{SIGKILL}
608 signal. The argument may be a process, the name of a process, a
609 buffer, or the name of a buffer. (A buffer or buffer-name stands for
610 the process that @code{get-buffer-process} returns.) Calling
611 @code{delete-process} on a running process terminates it, updates the
612 process status, and runs the sentinel (if any) immediately. If the
613 process has already terminated, calling @code{delete-process} has no
614 effect on its status, or on the running of its sentinel (which will
615 happen sooner or later).
619 (delete-process "*shell*")
625 @node Process Information
626 @section Process Information
628 Several functions return information about processes.
629 @code{list-processes} is provided for interactive use.
631 @deffn Command list-processes &optional query-only
632 This command displays a listing of all living processes. In addition,
633 it finally deletes any process whose status was @samp{Exited} or
634 @samp{Signaled}. It returns @code{nil}.
636 If @var{query-only} is non-@code{nil} then it lists only processes
637 whose query flag is non-@code{nil}. @xref{Query Before Exit}.
641 This function returns a list of all processes that have not been deleted.
646 @result{} (#<process display-time> #<process shell>)
651 @defun get-process name
652 This function returns the process named @var{name}, or @code{nil} if
653 there is none. An error is signaled if @var{name} is not a string.
657 (get-process "shell")
658 @result{} #<process shell>
663 @defun process-command process
664 This function returns the command that was executed to start
665 @var{process}. This is a list of strings, the first string being the
666 program executed and the rest of the strings being the arguments that
667 were given to the program.
671 (process-command (get-process "shell"))
672 @result{} ("/bin/csh" "-i")
677 @defun process-id process
678 This function returns the @acronym{PID} of @var{process}. This is an
679 integer that distinguishes the process @var{process} from all other
680 processes running on the same computer at the current time. The
681 @acronym{PID} of a process is chosen by the operating system kernel when the
682 process is started and remains constant as long as the process exists.
685 @defun process-name process
686 This function returns the name of @var{process}.
689 @defun process-status process-name
690 This function returns the status of @var{process-name} as a symbol.
691 The argument @var{process-name} must be a process, a buffer, a
692 process name (string) or a buffer name (string).
694 The possible values for an actual subprocess are:
698 for a process that is running.
700 for a process that is stopped but continuable.
702 for a process that has exited.
704 for a process that has received a fatal signal.
706 for a network connection that is open.
708 for a network connection that is closed. Once a connection
709 is closed, you cannot reopen it, though you might be able to open
710 a new connection to the same place.
712 for a non-blocking connection that is waiting to complete.
714 for a non-blocking connection that has failed to complete.
716 for a network server that is listening.
718 if @var{process-name} is not the name of an existing process.
723 (process-status "shell")
727 (process-status (get-buffer "*shell*"))
732 @result{} #<process xx<1>>
738 For a network connection, @code{process-status} returns one of the symbols
739 @code{open} or @code{closed}. The latter means that the other side
740 closed the connection, or Emacs did @code{delete-process}.
743 @defun process-exit-status process
744 This function returns the exit status of @var{process} or the signal
745 number that killed it. (Use the result of @code{process-status} to
746 determine which of those it is.) If @var{process} has not yet
747 terminated, the value is 0.
750 @defun process-tty-name process
751 This function returns the terminal name that @var{process} is using for
752 its communication with Emacs---or @code{nil} if it is using pipes
753 instead of a terminal (see @code{process-connection-type} in
754 @ref{Asynchronous Processes}).
757 @defun process-coding-system process
758 @anchor{Coding systems for a subprocess}
759 This function returns a cons cell describing the coding systems in use
760 for decoding output from @var{process} and for encoding input to
761 @var{process} (@pxref{Coding Systems}). The value has this form:
764 (@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
768 @defun set-process-coding-system process &optional decoding-system encoding-system
769 This function specifies the coding systems to use for subsequent output
770 from and input to @var{process}. It will use @var{decoding-system} to
771 decode subprocess output, and @var{encoding-system} to encode subprocess
775 Every process also has a property list that you can use to store
776 miscellaneous values associated with the process.
778 @defun process-get process propname
779 This function returns the value of the @var{propname} property
783 @defun process-put process propname value
784 This function sets the value of the @var{propname} property
785 of @var{process} to @var{value}.
788 @defun process-plist process
789 This function returns the process plist of @var{process}.
792 @defun set-process-plist process plist
793 This function sets the process plist of @var{process} to @var{plist}.
796 @node Input to Processes
797 @section Sending Input to Processes
798 @cindex process input
800 Asynchronous subprocesses receive input when it is sent to them by
801 Emacs, which is done with the functions in this section. You must
802 specify the process to send input to, and the input data to send. The
803 data appears on the ``standard input'' of the subprocess.
805 Some operating systems have limited space for buffered input in a
806 @acronym{PTY}. On these systems, Emacs sends an @acronym{EOF}
807 periodically amidst the other characters, to force them through. For
808 most programs, these @acronym{EOF}s do no harm.
810 Subprocess input is normally encoded using a coding system before the
811 subprocess receives it, much like text written into a file. You can use
812 @code{set-process-coding-system} to specify which coding system to use
813 (@pxref{Process Information}). Otherwise, the coding system comes from
814 @code{coding-system-for-write}, if that is non-@code{nil}; or else from
815 the defaulting mechanism (@pxref{Default Coding Systems}).
817 Sometimes the system is unable to accept input for that process,
818 because the input buffer is full. When this happens, the send functions
819 wait a short while, accepting output from subprocesses, and then try
820 again. This gives the subprocess a chance to read more of its pending
821 input and make space in the buffer. It also allows filters, sentinels
822 and timers to run---so take account of that in writing your code.
824 In these functions, the @var{process} argument can be a process or
825 the name of a process, or a buffer or buffer name (which stands
826 for a process via @code{get-buffer-process}). @code{nil} means
827 the current buffer's process.
829 @defun process-send-string process string
830 This function sends @var{process} the contents of @var{string} as
831 standard input. If it is @code{nil}, the current buffer's process is used.
833 The function returns @code{nil}.
837 (process-send-string "shell<1>" "ls\n")
843 ---------- Buffer: *shell* ----------
845 introduction.texi syntax-tables.texi~
846 introduction.texi~ text.texi
847 introduction.txt text.texi~
849 ---------- Buffer: *shell* ----------
854 @defun process-send-region process start end
855 This function sends the text in the region defined by @var{start} and
856 @var{end} as standard input to @var{process}.
858 An error is signaled unless both @var{start} and @var{end} are
859 integers or markers that indicate positions in the current buffer. (It
860 is unimportant which number is larger.)
863 @defun process-send-eof &optional process
864 This function makes @var{process} see an end-of-file in its
865 input. The @acronym{EOF} comes after any text already sent to it.
867 The function returns @var{process}.
871 (process-send-eof "shell")
877 @defun process-running-child-p process
878 This function will tell you whether a subprocess has given control of
879 its terminal to its own child process. The value is @code{t} if this is
880 true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
884 @node Signals to Processes
885 @section Sending Signals to Processes
886 @cindex process signals
887 @cindex sending signals
890 @dfn{Sending a signal} to a subprocess is a way of interrupting its
891 activities. There are several different signals, each with its own
892 meaning. The set of signals and their names is defined by the operating
893 system. For example, the signal @code{SIGINT} means that the user has
894 typed @kbd{C-c}, or that some analogous thing has happened.
896 Each signal has a standard effect on the subprocess. Most signals
897 kill the subprocess, but some stop or resume execution instead. Most
898 signals can optionally be handled by programs; if the program handles
899 the signal, then we can say nothing in general about its effects.
901 You can send signals explicitly by calling the functions in this
902 section. Emacs also sends signals automatically at certain times:
903 killing a buffer sends a @code{SIGHUP} signal to all its associated
904 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
905 processes. (@code{SIGHUP} is a signal that usually indicates that the
906 user hung up the phone.)
908 Each of the signal-sending functions takes two optional arguments:
909 @var{process} and @var{current-group}.
911 The argument @var{process} must be either a process, a process
912 name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name
913 stands for a process through @code{get-buffer-process}. @code{nil}
914 stands for the process associated with the current buffer. An error
915 is signaled if @var{process} does not identify a process.
917 The argument @var{current-group} is a flag that makes a difference
918 when you are running a job-control shell as an Emacs subprocess. If it
919 is non-@code{nil}, then the signal is sent to the current process-group
920 of the terminal that Emacs uses to communicate with the subprocess. If
921 the process is a job-control shell, this means the shell's current
922 subjob. If it is @code{nil}, the signal is sent to the process group of
923 the immediate subprocess of Emacs. If the subprocess is a job-control
924 shell, this is the shell itself.
926 The flag @var{current-group} has no effect when a pipe is used to
927 communicate with the subprocess, because the operating system does not
928 support the distinction in the case of pipes. For the same reason,
929 job-control shells won't work when a pipe is used. See
930 @code{process-connection-type} in @ref{Asynchronous Processes}.
932 @defun interrupt-process &optional process current-group
933 This function interrupts the process @var{process} by sending the
934 signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt
935 character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
936 others) sends this signal. When the argument @var{current-group} is
937 non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
938 on the terminal by which Emacs talks to the subprocess.
941 @defun kill-process &optional process current-group
942 This function kills the process @var{process} by sending the
943 signal @code{SIGKILL}. This signal kills the subprocess immediately,
944 and cannot be handled by the subprocess.
947 @defun quit-process &optional process current-group
948 This function sends the signal @code{SIGQUIT} to the process
949 @var{process}. This signal is the one sent by the ``quit
950 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
954 @defun stop-process &optional process current-group
955 This function stops the process @var{process} by sending the
956 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
959 Outside of Emacs, on systems with job control, the ``stop character''
960 (usually @kbd{C-z}) normally sends this signal. When
961 @var{current-group} is non-@code{nil}, you can think of this function as
962 ``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
966 @defun continue-process &optional process current-group
967 This function resumes execution of the process @var{process} by sending
968 it the signal @code{SIGCONT}. This presumes that @var{process} was
973 @defun signal-process process signal
974 This function sends a signal to process @var{process}. The argument
975 @var{signal} specifies which signal to send; it should be an integer.
977 The @var{process} argument can be a system process @acronym{ID}; that
978 allows you to send signals to processes that are not children of
982 @node Output from Processes
983 @section Receiving Output from Processes
984 @cindex process output
985 @cindex output from processes
987 There are two ways to receive the output that a subprocess writes to
988 its standard output stream. The output can be inserted in a buffer,
989 which is called the associated buffer of the process, or a function
990 called the @dfn{filter function} can be called to act on the output. If
991 the process has no buffer and no filter function, its output is
994 When a subprocess terminates, Emacs reads any pending output,
995 then stops reading output from that subprocess. Therefore, if the
996 subprocess has children that are still live and still producing
997 output, Emacs won't receive that output.
999 Output from a subprocess can arrive only while Emacs is waiting: when
1000 reading terminal input, in @code{sit-for} and @code{sleep-for}
1001 (@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
1002 Output}). This minimizes the problem of timing errors that usually
1003 plague parallel programming. For example, you can safely create a
1004 process and only then specify its buffer or filter function; no output
1005 can arrive before you finish, if the code in between does not call any
1006 primitive that waits.
1008 @defvar process-adaptive-read-buffering
1009 On some systems, when Emacs reads the output from a subprocess, the
1010 output data is read in very small blocks, potentially resulting in
1011 very poor performance. This behavior can be remedied to some extent
1012 by setting the variable @var{process-adaptive-read-buffering} to a
1013 non-@code{nil} value (the default), as it will automatically delay reading
1014 from such processes, thus allowing them to produce more output before
1015 Emacs tries to read it.
1018 It is impossible to separate the standard output and standard error
1019 streams of the subprocess, because Emacs normally spawns the subprocess
1020 inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If
1021 you want to keep the output to those streams separate, you should
1022 redirect one of them to a file---for example, by using an appropriate
1026 * Process Buffers:: If no filter, output is put in a buffer.
1027 * Filter Functions:: Filter functions accept output from the process.
1028 * Decoding Output:: Filters can get unibyte or multibyte strings.
1029 * Accepting Output:: How to wait until process output arrives.
1032 @node Process Buffers
1033 @subsection Process Buffers
1035 A process can (and usually does) have an @dfn{associated buffer},
1036 which is an ordinary Emacs buffer that is used for two purposes: storing
1037 the output from the process, and deciding when to kill the process. You
1038 can also use the buffer to identify a process to operate on, since in
1039 normal practice only one process is associated with any given buffer.
1040 Many applications of processes also use the buffer for editing input to
1041 be sent to the process, but this is not built into Emacs Lisp.
1043 Unless the process has a filter function (@pxref{Filter Functions}),
1044 its output is inserted in the associated buffer. The position to insert
1045 the output is determined by the @code{process-mark}, which is then
1046 updated to point to the end of the text just inserted. Usually, but not
1047 always, the @code{process-mark} is at the end of the buffer.
1049 @defun process-buffer process
1050 This function returns the associated buffer of the process
1055 (process-buffer (get-process "shell"))
1056 @result{} #<buffer *shell*>
1061 @defun process-mark process
1062 This function returns the process marker for @var{process}, which is the
1063 marker that says where to insert output from the process.
1065 If @var{process} does not have a buffer, @code{process-mark} returns a
1066 marker that points nowhere.
1068 Insertion of process output in a buffer uses this marker to decide where
1069 to insert, and updates it to point after the inserted text. That is why
1070 successive batches of output are inserted consecutively.
1072 Filter functions normally should use this marker in the same fashion
1073 as is done by direct insertion of output in the buffer. A good
1074 example of a filter function that uses @code{process-mark} is found at
1075 the end of the following section.
1077 When the user is expected to enter input in the process buffer for
1078 transmission to the process, the process marker separates the new input
1079 from previous output.
1082 @defun set-process-buffer process buffer
1083 This function sets the buffer associated with @var{process} to
1084 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
1085 associated with no buffer.
1088 @defun get-buffer-process buffer-or-name
1089 This function returns a nondeleted process associated with the buffer
1090 specified by @var{buffer-or-name}. If there are several processes
1091 associated with it, this function chooses one (currently, the one most
1092 recently created, but don't count on that). Deletion of a process
1093 (see @code{delete-process}) makes it ineligible for this function to
1096 It is usually a bad idea to have more than one process associated with
1101 (get-buffer-process "*shell*")
1102 @result{} #<process shell>
1106 Killing the process's buffer deletes the process, which kills the
1107 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
1110 @node Filter Functions
1111 @subsection Process Filter Functions
1112 @cindex filter function
1113 @cindex process filter
1115 A process @dfn{filter function} is a function that receives the
1116 standard output from the associated process. If a process has a filter,
1117 then @emph{all} output from that process is passed to the filter. The
1118 process buffer is used directly for output from the process only when
1121 The filter function can only be called when Emacs is waiting for
1122 something, because process output arrives only at such times. Emacs
1123 waits when reading terminal input, in @code{sit-for} and
1124 @code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
1125 (@pxref{Accepting Output}).
1127 A filter function must accept two arguments: the associated process
1128 and a string, which is output just received from it. The function is
1129 then free to do whatever it chooses with the output.
1131 Quitting is normally inhibited within a filter function---otherwise,
1132 the effect of typing @kbd{C-g} at command level or to quit a user
1133 command would be unpredictable. If you want to permit quitting inside
1134 a filter function, bind @code{inhibit-quit} to @code{nil}. In most
1135 cases, the right way to do this is with the macro
1136 @code{with-local-quit}. @xref{Quitting}.
1138 If an error happens during execution of a filter function, it is
1139 caught automatically, so that it doesn't stop the execution of whatever
1140 program was running when the filter function was started. However, if
1141 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1142 off. This makes it possible to use the Lisp debugger to debug the
1143 filter function. @xref{Debugger}.
1145 Many filter functions sometimes or always insert the text in the
1146 process's buffer, mimicking the actions of Emacs when there is no
1147 filter. Such filter functions need to use @code{set-buffer} in order to
1148 be sure to insert in that buffer. To avoid setting the current buffer
1149 semipermanently, these filter functions must save and restore the
1150 current buffer. They should also update the process marker, and in some
1151 cases update the value of point. Here is how to do these things:
1155 (defun ordinary-insertion-filter (proc string)
1156 (with-current-buffer (process-buffer proc)
1157 (let ((moving (= (point) (process-mark proc))))
1161 ;; @r{Insert the text, advancing the process marker.}
1162 (goto-char (process-mark proc))
1164 (set-marker (process-mark proc) (point)))
1165 (if moving (goto-char (process-mark proc))))))
1170 The reason to use @code{with-current-buffer}, rather than using
1171 @code{save-excursion} to save and restore the current buffer, is so as
1172 to preserve the change in point made by the second call to
1175 To make the filter force the process buffer to be visible whenever new
1176 text arrives, insert the following line just before the
1177 @code{with-current-buffer} construct:
1180 (display-buffer (process-buffer proc))
1183 To force point to the end of the new output, no matter where it was
1184 previously, eliminate the variable @code{moving} and call
1185 @code{goto-char} unconditionally.
1187 In earlier Emacs versions, every filter function that did regular
1188 expression searching or matching had to explicitly save and restore the
1189 match data. Now Emacs does this automatically for filter functions;
1190 they never need to do it explicitly. @xref{Match Data}.
1192 A filter function that writes the output into the buffer of the
1193 process should check whether the buffer is still alive. If it tries to
1194 insert into a dead buffer, it will get an error. The expression
1195 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
1196 if the buffer is dead.
1198 The output to the function may come in chunks of any size. A program
1199 that produces the same output twice in a row may send it as one batch of
1200 200 characters one time, and five batches of 40 characters the next. If
1201 the filter looks for certain text strings in the subprocess output, make
1202 sure to handle the case where one of these strings is split across two
1203 or more batches of output.
1205 @defun set-process-filter process filter
1206 This function gives @var{process} the filter function @var{filter}. If
1207 @var{filter} is @code{nil}, it gives the process no filter.
1210 @defun process-filter process
1211 This function returns the filter function of @var{process}, or @code{nil}
1215 Here is an example of use of a filter function:
1219 (defun keep-output (process output)
1220 (setq kept (cons output kept)))
1221 @result{} keep-output
1228 (set-process-filter (get-process "shell") 'keep-output)
1229 @result{} keep-output
1232 (process-send-string "shell" "ls ~/other\n")
1235 @result{} ("lewis@@slug[8] % "
1238 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
1239 address.txt backup.psf kolstad.psf
1240 backup.bib~ david.mss resume-Dec-86.mss~
1241 backup.err david.psf resume-Dec.psf
1242 backup.mss dland syllabus.mss
1244 "#backups.mss# backup.mss~ kolstad.mss
1249 @ignore @c The code in this example doesn't show the right way to do things.
1250 Here is another, more realistic example, which demonstrates how to use
1251 the process mark to do insertion in the same fashion as is done when
1252 there is no filter function:
1256 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
1257 ;; @r{and make sure that buffer is shown in some window.}
1258 (defun my-process-filter (proc str)
1259 (let ((cur (selected-window))
1261 (pop-to-buffer my-shell-buffer)
1264 (goto-char (point-max))
1266 (set-marker (process-mark proc) (point-max))
1267 (select-window cur)))
1272 @node Decoding Output
1273 @subsection Decoding Process Output
1274 @cindex decode process output
1276 When Emacs writes process output directly into a multibyte buffer,
1277 it decodes the output according to the process output coding system.
1278 If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
1279 converts the unibyte output to multibyte using
1280 @code{string-to-multibyte}, and inserts the resulting multibyte text.
1282 You can use @code{set-process-coding-system} to specify which coding
1283 system to use (@pxref{Process Information}). Otherwise, the coding
1284 system comes from @code{coding-system-for-read}, if that is
1285 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
1288 @strong{Warning:} Coding systems such as @code{undecided} which
1289 determine the coding system from the data do not work entirely
1290 reliably with asynchronous subprocess output. This is because Emacs
1291 has to process asynchronous subprocess output in batches, as it
1292 arrives. Emacs must try to detect the proper coding system from one
1293 batch at a time, and this does not always work. Therefore, if at all
1294 possible, specify a coding system that determines both the character
1295 code conversion and the end of line conversion---that is, one like
1296 @code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
1298 @cindex filter multibyte flag, of process
1299 @cindex process filter multibyte flag
1300 When Emacs calls a process filter function, it provides the process
1301 output as a multibyte string or as a unibyte string according to the
1302 process's filter multibyte flag. If the flag is non-@code{nil}, Emacs
1303 decodes the output according to the process output coding system to
1304 produce a multibyte string, and passes that to the process. If the
1305 flag is @code{nil}, Emacs puts the output into a unibyte string, with
1306 no decoding, and passes that.
1308 When you create a process, the filter multibyte flag takes its
1309 initial value from @code{default-enable-multibyte-characters}. If you
1310 want to change the flag later on, use
1311 @code{set-process-filter-multibyte}.
1313 @defun set-process-filter-multibyte process multibyte
1314 This function sets the filter multibyte flag of @var{process}
1318 @defun process-filter-multibyte-p process
1319 This function returns the filter multibyte flag of @var{process}.
1322 @node Accepting Output
1323 @subsection Accepting Output from Processes
1324 @cindex accept input from processes
1326 Output from asynchronous subprocesses normally arrives only while
1327 Emacs is waiting for some sort of external event, such as elapsed time
1328 or terminal input. Occasionally it is useful in a Lisp program to
1329 explicitly permit output to arrive at a specific point, or even to wait
1330 until output arrives from a process.
1332 @defun accept-process-output &optional process seconds millisec just-this-one
1333 This function allows Emacs to read pending output from processes. The
1334 output is inserted in the associated buffers or given to their filter
1335 functions. If @var{process} is non-@code{nil} then this function does
1336 not return until some output has been received from @var{process}.
1339 The arguments @var{seconds} and @var{millisec} let you specify timeout
1340 periods. The former specifies a period measured in seconds and the
1341 latter specifies one measured in milliseconds. The two time periods
1342 thus specified are added together, and @code{accept-process-output}
1343 returns after that much time, whether or not there has been any
1346 The argument @var{millisec} is semi-obsolete nowadays because
1347 @var{seconds} can be a floating point number to specify waiting a
1348 fractional number of seconds. If @var{seconds} is 0, the function
1349 accepts whatever output is pending but does not wait.
1351 @c Emacs 22.1 feature
1352 If @var{process} is a process, and the argument @var{just-this-one} is
1353 non-@code{nil}, only output from that process is handled, suspending output
1354 from other processes until some output has been received from that
1355 process or the timeout expires. If @var{just-this-one} is an integer,
1356 also inhibit running timers. This feature is generally not
1357 recommended, but may be necessary for specific applications, such as
1360 The function @code{accept-process-output} returns non-@code{nil} if it
1361 did get some output, or @code{nil} if the timeout expired before output
1366 @section Sentinels: Detecting Process Status Changes
1367 @cindex process sentinel
1368 @cindex sentinel (of process)
1370 A @dfn{process sentinel} is a function that is called whenever the
1371 associated process changes status for any reason, including signals
1372 (whether sent by Emacs or caused by the process's own actions) that
1373 terminate, stop, or continue the process. The process sentinel is
1374 also called if the process exits. The sentinel receives two
1375 arguments: the process for which the event occurred, and a string
1376 describing the type of event.
1378 The string describing the event looks like one of the following:
1382 @code{"finished\n"}.
1385 @code{"exited abnormally with code @var{exitcode}\n"}.
1388 @code{"@var{name-of-signal}\n"}.
1391 @code{"@var{name-of-signal} (core dumped)\n"}.
1394 A sentinel runs only while Emacs is waiting (e.g., for terminal
1395 input, or for time to elapse, or for process output). This avoids the
1396 timing errors that could result from running them at random places in
1397 the middle of other Lisp programs. A program can wait, so that
1398 sentinels will run, by calling @code{sit-for} or @code{sleep-for}
1399 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
1400 Output}). Emacs also allows sentinels to run when the command loop is
1401 reading input. @code{delete-process} calls the sentinel when it
1402 terminates a running process.
1404 Emacs does not keep a queue of multiple reasons to call the sentinel
1405 of one process; it records just the current status and the fact that
1406 there has been a change. Therefore two changes in status, coming in
1407 quick succession, can call the sentinel just once. However, process
1408 termination will always run the sentinel exactly once. This is
1409 because the process status can't change again after termination.
1411 Emacs explicitly checks for output from the process before running
1412 the process sentinel. Once the sentinel runs due to process
1413 termination, no further output can arrive from the process.
1415 A sentinel that writes the output into the buffer of the process
1416 should check whether the buffer is still alive. If it tries to insert
1417 into a dead buffer, it will get an error. If the buffer is dead,
1418 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
1420 Quitting is normally inhibited within a sentinel---otherwise, the
1421 effect of typing @kbd{C-g} at command level or to quit a user command
1422 would be unpredictable. If you want to permit quitting inside a
1423 sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the
1424 right way to do this is with the macro @code{with-local-quit}.
1427 If an error happens during execution of a sentinel, it is caught
1428 automatically, so that it doesn't stop the execution of whatever
1429 programs was running when the sentinel was started. However, if
1430 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1431 off. This makes it possible to use the Lisp debugger to debug the
1432 sentinel. @xref{Debugger}.
1434 While a sentinel is running, the process sentinel is temporarily
1435 set to @code{nil} so that the sentinel won't run recursively.
1436 For this reason it is not possible for a sentinel to specify
1439 In earlier Emacs versions, every sentinel that did regular expression
1440 searching or matching had to explicitly save and restore the match data.
1441 Now Emacs does this automatically for sentinels; they never need to do
1442 it explicitly. @xref{Match Data}.
1444 @defun set-process-sentinel process sentinel
1445 This function associates @var{sentinel} with @var{process}. If
1446 @var{sentinel} is @code{nil}, then the process will have no sentinel.
1447 The default behavior when there is no sentinel is to insert a message in
1448 the process's buffer when the process status changes.
1450 Changes in process sentinel take effect immediately---if the sentinel
1451 is slated to be run but has not been called yet, and you specify a new
1452 sentinel, the eventual call to the sentinel will use the new one.
1456 (defun msg-me (process event)
1458 (format "Process: %s had the event `%s'" process event)))
1459 (set-process-sentinel (get-process "shell") 'msg-me)
1463 (kill-process (get-process "shell"))
1464 @print{} Process: #<process shell> had the event `killed'
1465 @result{} #<process shell>
1470 @defun process-sentinel process
1471 This function returns the sentinel of @var{process}, or @code{nil} if it
1475 @defun waiting-for-user-input-p
1476 While a sentinel or filter function is running, this function returns
1477 non-@code{nil} if Emacs was waiting for keyboard input from the user at
1478 the time the sentinel or filter function was called, @code{nil} if it
1482 @node Query Before Exit
1483 @section Querying Before Exit
1485 When Emacs exits, it terminates all its subprocesses by sending them
1486 the @code{SIGHUP} signal. Because subprocesses may be doing
1487 valuable work, Emacs normally asks the user to confirm that it is ok
1488 to terminate them. Each process has a query flag which, if
1489 non-@code{nil}, says that Emacs should ask for confirmation before
1490 exiting and thus killing that process. The default for the query flag
1491 is @code{t}, meaning @emph{do} query.
1493 @defun process-query-on-exit-flag process
1494 This returns the query flag of @var{process}.
1497 @defun set-process-query-on-exit-flag process flag
1498 This function sets the query flag of @var{process} to @var{flag}. It
1503 ;; @r{Don't query about the shell process}
1504 (set-process-query-on-exit-flag (get-process "shell") nil)
1510 @defun process-kill-without-query process &optional do-query
1511 This function clears the query flag of @var{process}, so that
1512 Emacs will not query the user on account of that process.
1514 Actually, the function does more than that: it returns the old value of
1515 the process's query flag, and sets the query flag to @var{do-query}.
1516 Please don't use this function to do those things any more---please
1517 use the newer, cleaner functions @code{process-query-on-exit-flag} and
1518 @code{set-process-query-on-exit-flag} in all but the simplest cases.
1519 The only way you should use @code{process-kill-without-query} nowadays
1524 ;; @r{Don't query about the shell process}
1525 (process-kill-without-query (get-process "shell"))
1530 @node Transaction Queues
1531 @section Transaction Queues
1532 @cindex transaction queue
1534 You can use a @dfn{transaction queue} to communicate with a subprocess
1535 using transactions. First use @code{tq-create} to create a transaction
1536 queue communicating with a specified process. Then you can call
1537 @code{tq-enqueue} to send a transaction.
1539 @defun tq-create process
1540 This function creates and returns a transaction queue communicating with
1541 @var{process}. The argument @var{process} should be a subprocess
1542 capable of sending and receiving streams of bytes. It may be a child
1543 process, or it may be a TCP connection to a server, possibly on another
1547 @defun tq-enqueue queue question regexp closure fn &optional delay-question
1548 This function sends a transaction to queue @var{queue}. Specifying the
1549 queue has the effect of specifying the subprocess to talk to.
1551 The argument @var{question} is the outgoing message that starts the
1552 transaction. The argument @var{fn} is the function to call when the
1553 corresponding answer comes back; it is called with two arguments:
1554 @var{closure}, and the answer received.
1556 The argument @var{regexp} is a regular expression that should match
1557 text at the end of the entire answer, but nothing before; that's how
1558 @code{tq-enqueue} determines where the answer ends.
1560 If the argument @var{delay-question} is non-nil, delay sending this
1561 question until the process has finished replying to any previous
1562 questions. This produces more reliable results with some processes.
1564 The return value of @code{tq-enqueue} itself is not meaningful.
1567 @defun tq-close queue
1568 Shut down transaction queue @var{queue}, waiting for all pending transactions
1569 to complete, and then terminate the connection or child process.
1572 Transaction queues are implemented by means of a filter function.
1573 @xref{Filter Functions}.
1576 @section Network Connections
1577 @cindex network connection
1581 Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
1582 connections to other processes on the same machine or other machines.
1583 A network connection is handled by Lisp much like a subprocess, and is
1584 represented by a process object. However, the process you are
1585 communicating with is not a child of the Emacs process, so it has no
1586 process @acronym{ID}, and you can't kill it or send it signals. All you
1587 can do is send and receive data. @code{delete-process} closes the
1588 connection, but does not kill the program at the other end; that
1589 program must decide what to do about closure of the connection.
1591 Lisp programs can listen for connections by creating network
1592 servers. A network server is also represented by a kind of process
1593 object, but unlike a network connection, the network server never
1594 transfers data itself. When it receives a connection request, it
1595 creates a new network connection to represent the connection just
1596 made. (The network connection inherits certain information, including
1597 the process plist, from the server.) The network server then goes
1598 back to listening for more connection requests.
1600 Network connections and servers are created by calling
1601 @code{make-network-process} with an argument list consisting of
1602 keyword/argument pairs, for example @code{:server t} to create a
1603 server process, or @code{:type 'datagram} to create a datagram
1604 connection. @xref{Low-Level Network}, for details. You can also use
1605 the @code{open-network-stream} function described below.
1607 You can distinguish process objects representing network connections
1608 and servers from those representing subprocesses with the
1609 @code{process-status} function. The possible status values for
1610 network connections are @code{open}, @code{closed}, @code{connect},
1611 and @code{failed}. For a network server, the status is always
1612 @code{listen}. None of those values is possible for a real
1613 subprocess. @xref{Process Information}.
1615 You can stop and resume operation of a network process by calling
1616 @code{stop-process} and @code{continue-process}. For a server
1617 process, being stopped means not accepting new connections. (Up to 5
1618 connection requests will be queued for when you resume the server; you
1619 can increase this limit, unless it is imposed by the operating
1620 system.) For a network stream connection, being stopped means not
1621 processing input (any arriving input waits until you resume the
1622 connection). For a datagram connection, some number of packets may be
1623 queued but input may be lost. You can use the function
1624 @code{process-command} to determine whether a network connection or
1625 server is stopped; a non-@code{nil} value means yes.
1627 @defun open-network-stream name buffer-or-name host service
1628 This function opens a TCP connection, and returns a process object
1629 that represents the connection.
1631 The @var{name} argument specifies the name for the process object. It
1632 is modified as necessary to make it unique.
1634 The @var{buffer-or-name} argument is the buffer to associate with the
1635 connection. Output from the connection is inserted in the buffer,
1636 unless you specify a filter function to handle the output. If
1637 @var{buffer-or-name} is @code{nil}, it means that the connection is not
1638 associated with any buffer.
1640 The arguments @var{host} and @var{service} specify where to connect to;
1641 @var{host} is the host name (a string), and @var{service} is the name of
1642 a defined network service (a string) or a port number (an integer).
1645 @defun process-contact process &optional key
1646 This function returns information about how a network process was set
1647 up. For a connection, when @var{key} is @code{nil}, it returns
1648 @code{(@var{hostname} @var{service})} which specifies what you
1651 If @var{key} is @code{t}, the value is the complete status information
1652 for the connection or server; that is, the list of keywords and values
1653 specified in @code{make-network-process}, except that some of the
1654 values represent the current status instead of what you specified:
1658 The associated value is the process buffer.
1660 The associated value is the process filter function.
1662 The associated value is the process sentinel function.
1664 In a connection, the address in internal format of the remote peer.
1666 The local address, in internal format.
1668 In a server, if you specified @code{t} for @var{service},
1669 this value is the actual port number.
1672 @code{:local} and @code{:remote} are included even if they were not
1673 specified explicitly in @code{make-network-process}.
1675 If @var{key} is a keyword, the function returns the value corresponding
1678 For an ordinary child process, this function always returns @code{t}.
1681 @node Network Servers
1682 @section Network Servers
1683 @cindex network servers
1685 You create a server by calling @code{make-network-process} with
1686 @code{:server t}. The server will listen for connection requests from
1687 clients. When it accepts a client connection request, that creates a
1688 new network connection, itself a process object, with the following
1693 The connection's process name is constructed by concatenating the
1694 server process' @var{name} with a client identification string. The
1695 client identification string for an IPv4 connection looks like
1696 @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a
1697 unique number in brackets, as in @samp{<@var{nnn}>}. The number
1698 is unique for each connection in the Emacs session.
1701 If the server's filter is non-@code{nil}, the connection process does
1702 not get a separate process buffer; otherwise, Emacs creates a new
1703 buffer for the purpose. The buffer name is the server's buffer name
1704 or process name, concatenated with the client identification string.
1706 The server's process buffer value is never used directly by Emacs, but
1707 it is passed to the log function, which can log connections by
1708 inserting text there.
1711 The communication type and the process filter and sentinel are
1712 inherited from those of the server. The server never directly
1713 uses its filter and sentinel; their sole purpose is to initialize
1714 connections made to the server.
1717 The connection's process contact info is set according to the client's
1718 addressing information (typically an IP address and a port number).
1719 This information is associated with the @code{process-contact}
1720 keywords @code{:host}, @code{:service}, @code{:remote}.
1723 The connection's local address is set up according to the port
1724 number used for the connection.
1727 The client process' plist is initialized from the server's plist.
1734 A datagram connection communicates with individual packets rather
1735 than streams of data. Each call to @code{process-send} sends one
1736 datagram packet (@pxref{Input to Processes}), and each datagram
1737 received results in one call to the filter function.
1739 The datagram connection doesn't have to talk with the same remote
1740 peer all the time. It has a @dfn{remote peer address} which specifies
1741 where to send datagrams to. Each time an incoming datagram is passed
1742 to the filter function, the peer address is set to the address that
1743 datagram came from; that way, if the filter function sends a datagram,
1744 it will go back to that place. You can specify the remote peer
1745 address when you create the datagram connection using the
1746 @code{:remote} keyword. You can change it later on by calling
1747 @code{set-process-datagram-address}.
1749 @defun process-datagram-address process
1750 If @var{process} is a datagram connection or server, this function
1751 returns its remote peer address.
1754 @defun set-process-datagram-address process address
1755 If @var{process} is a datagram connection or server, this function
1756 sets its remote peer address to @var{address}.
1759 @node Low-Level Network
1760 @section Low-Level Network Access
1762 You can also create network connections by operating at a lower
1763 level than that of @code{open-network-stream}, using
1764 @code{make-network-process}.
1767 * Proc: Network Processes. Using @code{make-network-process}.
1768 * Options: Network Options. Further control over network connections.
1769 * Features: Network Feature Testing.
1770 Determining which network features work on
1771 the machine you are using.
1774 @node Network Processes
1775 @subsection @code{make-network-process}
1777 The basic function for creating network connections and network
1778 servers is @code{make-network-process}. It can do either of those
1779 jobs, depending on the arguments you give it.
1781 @defun make-network-process &rest args
1782 This function creates a network connection or server and returns the
1783 process object that represents it. The arguments @var{args} are a
1784 list of keyword/argument pairs. Omitting a keyword is always
1785 equivalent to specifying it with value @code{nil}, except for
1786 @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here
1787 are the meaningful keywords:
1790 @item :name @var{name}
1791 Use the string @var{name} as the process name. It is modified if
1792 necessary to make it unique.
1794 @item :type @var{type}
1795 Specify the communication type. A value of @code{nil} specifies a
1796 stream connection (the default); @code{datagram} specifies a datagram
1797 connection. Both connections and servers can be of either type.
1799 @item :server @var{server-flag}
1800 If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
1801 create a connection. For a stream type server, @var{server-flag} may
1802 be an integer which then specifies the length of the queue of pending
1803 connections to the server. The default queue length is 5.
1805 @item :host @var{host}
1806 Specify the host to connect to. @var{host} should be a host name or
1807 Internet address, as a string, or the symbol @code{local} to specify
1808 the local host. If you specify @var{host} for a server, it must
1809 specify a valid address for the local host, and only clients
1810 connecting to that address will be accepted.
1812 @item :service @var{service}
1813 @var{service} specifies a port number to connect to, or, for a server,
1814 the port number to listen on. It should be a service name that
1815 translates to a port number, or an integer specifying the port number
1816 directly. For a server, it can also be @code{t}, which means to let
1817 the system select an unused port number.
1819 @item :family @var{family}
1820 @var{family} specifies the address (and protocol) family for
1821 communication. @code{nil} means determine the proper address family
1822 automatically for the given @var{host} and @var{service}.
1823 @code{local} specifies a Unix socket, in which case @var{host} is
1824 ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6
1827 @item :local @var{local-address}
1828 For a server process, @var{local-address} is the address to listen on.
1829 It overrides @var{family}, @var{host} and @var{service}, and you
1830 may as well not specify them.
1832 @item :remote @var{remote-address}
1833 For a connection, @var{remote-address} is the address to connect to.
1834 It overrides @var{family}, @var{host} and @var{service}, and you
1835 may as well not specify them.
1837 For a datagram server, @var{remote-address} specifies the initial
1838 setting of the remote datagram address.
1840 The format of @var{local-address} or @var{remote-address} depends on
1845 An IPv4 address is represented as a five-element vector of four 8-bit
1846 integers and one 16-bit integer
1847 @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to
1848 numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number
1852 An IPv6 address is represented as a nine-element vector of 16-bit
1853 integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f}
1854 @var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address
1855 @var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and
1856 port number @var{p}.
1859 A local address is represented as a string which specifies the address
1860 in the local address space.
1863 An ``unsupported family'' address is represented by a cons
1864 @code{(@var{f} . @var{av})}, where @var{f} is the family number and
1865 @var{av} is a vector specifying the socket address using one element
1866 per address data byte. Do not rely on this format in portable code,
1867 as it may depend on implementation defined constants, data sizes, and
1868 data structure alignment.
1871 @item :nowait @var{bool}
1872 If @var{bool} is non-@code{nil} for a stream connection, return
1873 without waiting for the connection to complete. When the connection
1874 succeeds or fails, Emacs will call the sentinel function, with a
1875 second argument matching @code{"open"} (if successful) or
1876 @code{"failed"}. The default is to block, so that
1877 @code{make-network-process} does not return until the connection
1878 has succeeded or failed.
1880 @item :stop @var{stopped}
1881 Start the network connection or server in the `stopped' state if
1882 @var{stopped} is non-@code{nil}.
1884 @item :buffer @var{buffer}
1885 Use @var{buffer} as the process buffer.
1887 @item :coding @var{coding}
1888 Use @var{coding} as the coding system for this process. To specify
1889 different coding systems for decoding data from the connection and for
1890 encoding data sent to it, specify @code{(@var{decoding} .
1891 @var{encoding})} for @var{coding}.
1893 If you don't specify this keyword at all, the default
1894 is to determine the coding systems from the data.
1896 @item :noquery @var{query-flag}
1897 Initialize the process query flag to @var{query-flag}.
1898 @xref{Query Before Exit}.
1900 @item :filter @var{filter}
1901 Initialize the process filter to @var{filter}.
1903 @item :filter-multibyte @var{bool}
1904 If @var{bool} is non-@code{nil}, strings given to the process filter
1905 are multibyte, otherwise they are unibyte. If you don't specify this
1906 keyword at all, the default is that the strings are multibyte if
1907 @code{default-enable-multibyte-characters} is non-@code{nil}.
1909 @item :sentinel @var{sentinel}
1910 Initialize the process sentinel to @var{sentinel}.
1912 @item :log @var{log}
1913 Initialize the log function of a server process to @var{log}. The log
1914 function is called each time the server accepts a network connection
1915 from a client. The arguments passed to the log function are
1916 @var{server}, @var{connection}, and @var{message}, where @var{server}
1917 is the server process, @var{connection} is the new process for the
1918 connection, and @var{message} is a string describing what has
1921 @item :plist @var{plist}
1922 Initialize the process plist to @var{plist}.
1925 The original argument list, modified with the actual connection
1926 information, is available via the @code{process-contact} function.
1929 @node Network Options
1930 @subsection Network Options
1932 The following network options can be specified when you create a
1933 network process. Except for @code{:reuseaddr}, you can also set or
1934 modify these options later, using @code{set-network-process-option}.
1936 For a server process, the options specified with
1937 @code{make-network-process} are not inherited by the client
1938 connections, so you will need to set the necessary options for each
1939 child connection as it is created.
1942 @item :bindtodevice @var{device-name}
1943 If @var{device-name} is a non-empty string identifying a network
1944 interface name (see @code{network-interface-list}), only handle
1945 packets received on that interface. If @var{device-name} is @code{nil}
1946 (the default), handle packets received on any interface.
1948 Using this option may require special privileges on some systems.
1950 @item :broadcast @var{broadcast-flag}
1951 If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
1952 process will receive datagram packet sent to a broadcast address, and
1953 be able to send packets to a broadcast address. Ignored for a stream
1956 @item :dontroute @var{dontroute-flag}
1957 If @var{dontroute-flag} is non-@code{nil}, the process can only send
1958 to hosts on the same network as the local host.
1960 @item :keepalive @var{keepalive-flag}
1961 If @var{keepalive-flag} is non-@code{nil} for a stream connection,
1962 enable exchange of low-level keep-alive messages.
1964 @item :linger @var{linger-arg}
1965 If @var{linger-arg} is non-@code{nil}, wait for successful
1966 transmission of all queued packets on the connection before it is
1967 deleted (see @code{delete-process}). If @var{linger-arg} is an
1968 integer, it specifies the maximum time in seconds to wait for queued
1969 packets to be sent before closing the connection. Default is
1970 @code{nil} which means to discard unsent queued packets when the
1973 @item :oobinline @var{oobinline-flag}
1974 If @var{oobinline-flag} is non-@code{nil} for a stream connection,
1975 receive out-of-band data in the normal data stream. Otherwise, ignore
1978 @item :priority @var{priority}
1979 Set the priority for packets sent on this connection to the integer
1980 @var{priority}. The interpretation of this number is protocol
1981 specific, such as setting the TOS (type of service) field on IP
1982 packets sent on this connection. It may also have system dependent
1983 effects, such as selecting a specific output queue on the network
1986 @item :reuseaddr @var{reuseaddr-flag}
1987 If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
1988 server process, allow this server to reuse a specific port number (see
1989 @code{:service}) unless another process on this host is already
1990 listening on that port. If @var{reuseaddr-flag} is @code{nil}, there
1991 may be a period of time after the last use of that port (by any
1992 process on the host), where it is not possible to make a new server on
1996 @defun set-network-process-option process option value
1997 This function sets or modifies a network option for network process
1998 @var{process}. See @code{make-network-process} for details of options
1999 @var{option} and their corresponding values @var{value}.
2001 The current setting of an option is available via the
2002 @code{process-contact} function.
2005 @node Network Feature Testing
2006 @subsection Testing Availability of Network Features
2008 To test for the availability of a given network feature, use
2009 @code{featurep} like this:
2012 (featurep 'make-network-process '(@var{keyword} @var{value}))
2016 The result of the first form is @code{t} if it works to specify
2017 @var{keyword} with value @var{value} in @code{make-network-process}.
2018 The result of the second form is @code{t} if @var{keyword} is
2019 supported by @code{make-network-process}. Here are some of the
2020 @var{keyword}---@var{value} pairs you can test in
2025 Non-@code{nil} if non-blocking connect is supported.
2026 @item (:type datagram)
2027 Non-@code{nil} if datagrams are supported.
2028 @item (:family local)
2029 Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported.
2030 @item (:family ipv6)
2031 Non-@code{nil} if IPv6 is supported.
2033 Non-@code{nil} if the system can select the port for a server.
2036 To test for the availability of a given network option, use
2037 @code{featurep} like this:
2040 (featurep 'make-network-process '@var{keyword})
2044 Here are some of the options you can test in this way.
2055 That particular network option is supported by
2056 @code{make-network-process} and @code{set-network-process-option}.
2060 @section Misc Network Facilities
2062 These additional functions are useful for creating and operating
2063 on network connections.
2065 @defun network-interface-list
2066 This function returns a list describing the network interfaces
2067 of the machine you are using. The value is an alist whose
2068 elements have the form @code{(@var{name} . @var{address})}.
2069 @var{address} has the same form as the @var{local-address}
2070 and @var{remote-address} arguments to @code{make-network-process}.
2073 @defun network-interface-info ifname
2074 This function returns information about the network interface named
2075 @var{ifname}. The value is a list of the form
2076 @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
2080 The Internet protocol address.
2082 The broadcast address.
2086 The layer 2 address (Ethernet MAC address, for instance).
2088 The current flags of the interface.
2092 @defun format-network-address address &optional omit-port
2093 This function converts the Lisp representation of a network address to
2096 A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]}
2097 represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port
2098 number @var{p}. @code{format-network-address} converts that to the
2099 string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
2101 A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e}
2102 @var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along
2103 with a port number. @code{format-network-address} converts that to
2105 @code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}.
2107 If the vector does not include the port number, @var{p}, or if
2108 @var{omit-port} is non-@code{nil}, the result does not include the
2109 @code{:@var{p}} suffix.
2113 @section Packing and Unpacking Byte Arrays
2114 @cindex byte packing and unpacking
2116 This section describes how to pack and unpack arrays of bytes,
2117 usually for binary network protocols. These functions convert byte arrays
2118 to alists, and vice versa. The byte array can be represented as a
2119 unibyte string or as a vector of integers, while the alist associates
2120 symbols either with fixed-size objects or with recursive sub-alists.
2123 @cindex deserializing
2126 Conversion from byte arrays to nested alists is also known as
2127 @dfn{deserializing} or @dfn{unpacking}, while going in the opposite
2128 direction is also known as @dfn{serializing} or @dfn{packing}.
2131 * Bindat Spec:: Describing data layout.
2132 * Bindat Functions:: Doing the unpacking and packing.
2133 * Bindat Examples:: Samples of what bindat.el can do for you!
2137 @subsection Describing Data Layout
2139 To control unpacking and packing, you write a @dfn{data layout
2140 specification}, a special nested list describing named and typed
2141 @dfn{fields}. This specification controls length of each field to be
2142 processed, and how to pack or unpack it. We normally keep bindat specs
2143 in variables whose names end in @samp{-bindat-spec}; that kind of name
2144 is automatically recognized as ``risky.''
2148 @cindex little endian
2149 @cindex network byte ordering
2150 A field's @dfn{type} describes the size (in bytes) of the object
2151 that the field represents and, in the case of multibyte fields, how
2152 the bytes are ordered within the field. The two possible orderings
2153 are ``big endian'' (also known as ``network byte ordering'') and
2154 ``little endian.'' For instance, the number @code{#x23cd} (decimal
2155 9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
2156 and in little endian, @code{#xcd} @code{#x23}. Here are the possible
2162 Unsigned byte, with length 1.
2167 Unsigned integer in network byte order, with length 2.
2170 Unsigned integer in network byte order, with length 3.
2175 Unsigned integer in network byte order, with length 4.
2176 Note: These values may be limited by Emacs' integer implementation limits.
2181 Unsigned integer in little endian order, with length 2, 3 and 4, respectively.
2184 String of length @var{len}.
2186 @item strz @var{len}
2187 Zero-terminated string, in a fixed-size field with length @var{len}.
2189 @item vec @var{len} [@var{type}]
2190 Vector of @var{len} elements of type @var{type}, or bytes if not
2191 @var{type} is specified.
2192 The @var{type} is any of the simple types above, or another vector
2193 specified as a list @code{(vec @var{len} [@var{type}])}.
2196 Four-byte vector representing an Internet address. For example:
2197 @code{[127 0 0 1]} for localhost.
2199 @item bits @var{len}
2200 List of set bits in @var{len} bytes. The bytes are taken in big
2201 endian order and the bits are numbered starting with @code{8 *
2202 @var{len} @minus{} 1} and ending with zero. For example: @code{bits
2203 2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and
2204 @code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}.
2206 @item (eval @var{form})
2207 @var{form} is a Lisp expression evaluated at the moment the field is
2208 unpacked or packed. The result of the evaluation should be one of the
2209 above-listed type specifications.
2212 For a fixed-size field, the length @var{len} is given as an integer
2213 specifying the number of bytes in the field.
2215 When the length of a field is not fixed, it typically depends on the
2216 value of a preceding field. In this case, the length @var{len} can be
2217 given either as a list @code{(@var{name} ...)} identifying a
2218 @dfn{field name} in the format specified for @code{bindat-get-field}
2219 below, or by an expression @code{(eval @var{form})} where @var{form}
2220 should evaluate to an integer, specifying the field length.
2222 A field specification generally has the form @code{([@var{name}]
2223 @var{handler})}. The square braces indicate that @var{name} is
2224 optional. (Don't use names that are symbols meaningful as type
2225 specifications (above) or handler specifications (below), since that
2226 would be ambiguous.) @var{name} can be a symbol or the expression
2227 @code{(eval @var{form})}, in which case @var{form} should evaluate to
2230 @var{handler} describes how to unpack or pack the field and can be one
2235 Unpack/pack this field according to the type specification @var{type}.
2237 @item eval @var{form}
2238 Evaluate @var{form}, a Lisp expression, for side-effect only. If the
2239 field name is specified, the value is bound to that field name.
2241 @item fill @var{len}
2242 Skip @var{len} bytes. In packing, this leaves them unchanged,
2243 which normally means they remain zero. In unpacking, this means
2246 @item align @var{len}
2247 Skip to the next multiple of @var{len} bytes.
2249 @item struct @var{spec-name}
2250 Process @var{spec-name} as a sub-specification. This describes a
2251 structure nested within another structure.
2253 @item union @var{form} (@var{tag} @var{spec})@dots{}
2254 @c ??? I don't see how one would actually use this.
2255 @c ??? what kind of expression would be useful for @var{form}?
2256 Evaluate @var{form}, a Lisp expression, find the first @var{tag}
2257 that matches it, and process its associated data layout specification
2258 @var{spec}. Matching can occur in one of three ways:
2262 If a @var{tag} has the form @code{(eval @var{expr})}, evaluate
2263 @var{expr} with the variable @code{tag} dynamically bound to the value
2264 of @var{form}. A non-@code{nil} result indicates a match.
2267 @var{tag} matches if it is @code{equal} to the value of @var{form}.
2270 @var{tag} matches unconditionally if it is @code{t}.
2273 @item repeat @var{count} @var{field-specs}@dots{}
2274 Process the @var{field-specs} recursively, in order, then repeat
2275 starting from the first one, processing all the specs @var{count}
2276 times overall. The @var{count} is given using the same formats as a
2277 field length---if an @code{eval} form is used, it is evaluated just once.
2278 For correct operation, each spec in @var{field-specs} must include a name.
2281 For the @code{(eval @var{form})} forms used in a bindat specification,
2282 the @var{form} can access and update these dynamically bound variables
2287 Value of the last field processed.
2290 The data as a byte array.
2293 Current index (within @code{bindat-raw}) for unpacking or packing.
2296 The alist containing the structured data that have been unpacked so
2297 far, or the entire structure being packed. You can use
2298 @code{bindat-get-field} to access specific fields of this structure.
2302 Inside a @code{repeat} block, these contain the maximum number of
2303 repetitions (as specified by the @var{count} parameter), and the
2304 current repetition number (counting from 0). Setting @code{count} to
2305 zero will terminate the inner-most repeat block after the current
2306 repetition has completed.
2309 @node Bindat Functions
2310 @subsection Functions to Unpack and Pack Bytes
2312 In the following documentation, @var{spec} refers to a data layout
2313 specification, @code{bindat-raw} to a byte array, and @var{struct} to an
2314 alist representing unpacked field data.
2316 @defun bindat-unpack spec bindat-raw &optional bindat-idx
2317 This function unpacks data from the unibyte string or byte
2318 array @code{bindat-raw}
2319 according to @var{spec}. Normally this starts unpacking at the
2320 beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it
2321 specifies a zero-based starting position to use instead.
2323 The value is an alist or nested alist in which each element describes
2327 @defun bindat-get-field struct &rest name
2328 This function selects a field's data from the nested alist
2329 @var{struct}. Usually @var{struct} was returned by
2330 @code{bindat-unpack}. If @var{name} corresponds to just one argument,
2331 that means to extract a top-level field value. Multiple @var{name}
2332 arguments specify repeated lookup of sub-structures. An integer name
2333 acts as an array index.
2335 For example, if @var{name} is @code{(a b 2 c)}, that means to find
2336 field @code{c} in the third element of subfield @code{b} of field
2337 @code{a}. (This corresponds to @code{struct.a.b[2].c} in C.)
2340 Although packing and unpacking operations change the organization of
2341 data (in memory), they preserve the data's @dfn{total length}, which is
2342 the sum of all the fields' lengths, in bytes. This value is not
2343 generally inherent in either the specification or alist alone; instead,
2344 both pieces of information contribute to its calculation. Likewise, the
2345 length of a string or array being unpacked may be longer than the data's
2346 total length as described by the specification.
2348 @defun bindat-length spec struct
2349 This function returns the total length of the data in @var{struct},
2350 according to @var{spec}.
2353 @defun bindat-pack spec struct &optional bindat-raw bindat-idx
2354 This function returns a byte array packed according to @var{spec} from
2355 the data in the alist @var{struct}. Normally it creates and fills a
2356 new byte array starting at the beginning. However, if @var{bindat-raw}
2357 is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to
2358 pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting
2359 offset for packing into @code{bindat-raw}.
2361 When pre-allocating, you should make sure @code{(length @var{bindat-raw})}
2362 meets or exceeds the total length to avoid an out-of-range error.
2365 @defun bindat-ip-to-string ip
2366 Convert the Internet address vector @var{ip} to a string in the usual
2370 (bindat-ip-to-string [127 0 0 1])
2371 @result{} "127.0.0.1"
2375 @node Bindat Examples
2376 @subsection Examples of Byte Unpacking and Packing
2378 Here is a complete example of byte unpacking and packing:
2381 (defvar fcookie-index-spec
2389 (:offset repeat (:count)
2391 "Description of a fortune cookie index file's contents.")
2393 (defun fcookie (cookies &optional index)
2394 "Display a random fortune cookie from file COOKIES.
2395 Optional second arg INDEX specifies the associated index
2396 filename, which is by default constructed by appending
2397 \".dat\" to COOKIES. Display cookie text in possibly
2398 new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
2399 is COOKIES without the directory part."
2400 (interactive "fCookies file: ")
2401 (let* ((info (with-temp-buffer
2402 (insert-file-contents-literally
2403 (or index (concat cookies ".dat")))
2404 (bindat-unpack fcookie-index-spec
2406 (sel (random (bindat-get-field info :count)))
2407 (beg (cdar (bindat-get-field info :offset sel)))
2408 (end (or (cdar (bindat-get-field info
2410 (nth 7 (file-attributes cookies)))))
2413 (format "*Fortune Cookie: %s*"
2414 (file-name-nondirectory cookies))))
2416 (insert-file-contents-literally
2417 cookies nil beg (- end 3))))
2419 (defun fcookie-create-index (cookies &optional index delim)
2420 "Scan file COOKIES, and write out its index file.
2421 Optional second arg INDEX specifies the index filename,
2422 which is by default constructed by appending \".dat\" to
2423 COOKIES. Optional third arg DELIM specifies the unibyte
2424 character which, when found on a line of its own in
2425 COOKIES, indicates the border between entries."
2426 (interactive "fCookies file: ")
2427 (setq delim (or delim ?%))
2428 (let ((delim-line (format "\n%c\n" delim))
2431 min p q len offsets)
2432 (unless (= 3 (string-bytes delim-line))
2433 (error "Delimiter cannot be represented in one byte"))
2435 (insert-file-contents-literally cookies)
2436 (while (and (setq p (point))
2437 (search-forward delim-line (point-max) t)
2438 (setq len (- (point) 3 p)))
2439 (setq count (1+ count)
2441 min (min (or min max) len)
2442 offsets (cons (1- p) offsets))))
2444 (set-buffer-multibyte nil)
2454 (:offset . ,(mapcar (lambda (o)
2455 (list (cons :foo o)))
2456 (nreverse offsets))))))
2457 (let ((coding-system-for-write 'raw-text-unix))
2458 (write-file (or index (concat cookies ".dat")))))))
2461 Following is an example of defining and unpacking a complex structure.
2462 Consider the following C structures:
2466 unsigned long dest_ip;
2467 unsigned long src_ip;
2468 unsigned short dest_port;
2469 unsigned short src_port;
2474 unsigned char opcode;
2475 unsigned short length; /* In network byte order */
2476 unsigned char id[8]; /* null-terminated string */
2477 unsigned char data[/* (length + 3) & ~3 */];
2481 struct header header;
2482 unsigned long counters[2]; /* In little endian order */
2483 unsigned char items;
2484 unsigned char filler[3];
2485 struct data item[/* items */];
2490 The corresponding data layout specification:
2502 (length u16) ;; network byte order
2508 '((header struct header-spec)
2509 (counters vec 2 u32r) ;; little endian order
2512 (item repeat (items)
2513 (struct data-spec))))
2516 A binary data representation:
2520 [ 192 168 1 100 192 168 1 101 01 28 21 32
2521 160 134 1 0 5 1 0 0 2 0 0 0
2522 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
2523 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
2526 The corresponding decoded structure:
2529 (setq decoded (bindat-unpack packet-spec binary-data))
2532 (dest-ip . [192 168 1 100])
2533 (src-ip . [192 168 1 101])
2536 (counters . [100000 261])
2538 (item ((data . [1 2 3 4 5])
2543 ((data . [6 7 8 9 10 11 12])
2550 Fetching data from this structure:
2553 (bindat-get-field decoded 'item 1 'id)
2558 arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a