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, 2008 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 * Serial Ports:: Communicating with serial ports.
57 * Byte Packing:: Using bindat to pack and unpack binary data.
60 @node Subprocess Creation
61 @section Functions that Create Subprocesses
63 There are three functions that create a new subprocess in which to run
64 a program. One of them, @code{start-process}, creates an asynchronous
65 process and returns a process object (@pxref{Asynchronous Processes}).
66 The other two, @code{call-process} and @code{call-process-region},
67 create a synchronous process and do not return a process object
68 (@pxref{Synchronous Processes}).
70 Synchronous and asynchronous processes are explained in the following
71 sections. Since the three functions are all called in a similar
72 fashion, their common arguments are described here.
74 @cindex execute program
75 @cindex @code{PATH} environment variable
76 @cindex @code{HOME} environment variable
77 In all cases, the function's @var{program} argument specifies the
78 program to be run. An error is signaled if the file is not found or
79 cannot be executed. If the file name is relative, the variable
80 @code{exec-path} contains a list of directories to search. Emacs
81 initializes @code{exec-path} when it starts up, based on the value of
82 the environment variable @code{PATH}. The standard file name
83 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as
84 usual in @code{exec-path}, but environment variable substitutions
85 (@samp{$HOME}, etc.) are not recognized; use
86 @code{substitute-in-file-name} to perform them (@pxref{File Name
87 Expansion}). @code{nil} in this list refers to
88 @code{default-directory}.
90 Executing a program can also try adding suffixes to the specified
94 This variable is a list of suffixes (strings) to try adding to the
95 specified program file name. The list should include @code{""} if you
96 want the name to be tried exactly as specified. The default value is
100 @strong{Please note:} The argument @var{program} contains only the
101 name of the program; it may not contain any command-line arguments. You
102 must use @var{args} to provide those.
104 Each of the subprocess-creating functions has a @var{buffer-or-name}
105 argument which specifies where the standard output from the program will
106 go. It should be a buffer or a buffer name; if it is a buffer name,
107 that will create the buffer if it does not already exist. It can also
108 be @code{nil}, which says to discard the output unless a filter function
109 handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
110 Normally, you should avoid having multiple processes send output to the
111 same buffer because their output would be intermixed randomly.
113 @cindex program arguments
114 All three of the subprocess-creating functions have a @code{&rest}
115 argument, @var{args}. The @var{args} must all be strings, and they are
116 supplied to @var{program} as separate command line arguments. Wildcard
117 characters and other shell constructs have no special meanings in these
118 strings, since the strings are passed directly to the specified program.
120 The subprocess gets its current directory from the value of
121 @code{default-directory} (@pxref{File Name Expansion}).
123 @cindex environment variables, subprocesses
124 The subprocess inherits its environment from Emacs, but you can
125 specify overrides for it with @code{process-environment}. @xref{System
128 @defvar exec-directory
130 The value of this variable is a string, the name of a directory that
131 contains programs that come with GNU Emacs, programs intended for Emacs
132 to invoke. The program @code{movemail} is an example of such a program;
133 Rmail uses it to fetch new mail from an inbox.
137 The value of this variable is a list of directories to search for
138 programs to run in subprocesses. Each element is either the name of a
139 directory (i.e., a string), or @code{nil}, which stands for the default
140 directory (which is the value of @code{default-directory}).
141 @cindex program directories
143 The value of @code{exec-path} is used by @code{call-process} and
144 @code{start-process} when the @var{program} argument is not an absolute
148 @node Shell Arguments
149 @section Shell Arguments
150 @cindex arguments for shell commands
151 @cindex shell command arguments
153 Lisp programs sometimes need to run a shell and give it a command
154 that contains file names that were specified by the user. These
155 programs ought to be able to support any valid file name. But the shell
156 gives special treatment to certain characters, and if these characters
157 occur in the file name, they will confuse the shell. To handle these
158 characters, use the function @code{shell-quote-argument}:
160 @defun shell-quote-argument argument
161 This function returns a string which represents, in shell syntax,
162 an argument whose actual contents are @var{argument}. It should
163 work reliably to concatenate the return value into a shell command
164 and then pass it to a shell for execution.
166 Precisely what this function does depends on your operating system. The
167 function is designed to work with the syntax of your system's standard
168 shell; if you use an unusual shell, you will need to redefine this
172 ;; @r{This example shows the behavior on GNU and Unix systems.}
173 (shell-quote-argument "foo > bar")
174 @result{} "foo\\ \\>\\ bar"
176 ;; @r{This example shows the behavior on MS-DOS and MS-Windows.}
177 (shell-quote-argument "foo > bar")
178 @result{} "\"foo > bar\""
181 Here's an example of using @code{shell-quote-argument} to construct
186 (shell-quote-argument oldfile)
188 (shell-quote-argument newfile))
192 @node Synchronous Processes
193 @section Creating a Synchronous Process
194 @cindex synchronous subprocess
196 After a @dfn{synchronous process} is created, Emacs waits for the
197 process to terminate before continuing. Starting Dired on GNU or
198 Unix@footnote{On other systems, Emacs uses a Lisp emulation of
199 @code{ls}; see @ref{Contents of Directories}.} is an example of this: it
200 runs @code{ls} in a synchronous process, then modifies the output
201 slightly. Because the process is synchronous, the entire directory
202 listing arrives in the buffer before Emacs tries to do anything with it.
204 While Emacs waits for the synchronous subprocess to terminate, the
205 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
206 the subprocess with a @code{SIGINT} signal; but it waits until the
207 subprocess actually terminates before quitting. If during that time the
208 user types another @kbd{C-g}, that kills the subprocess instantly with
209 @code{SIGKILL} and quits immediately (except on MS-DOS, where killing
210 other processes doesn't work). @xref{Quitting}.
212 The synchronous subprocess functions return an indication of how the
215 The output from a synchronous subprocess is generally decoded using a
216 coding system, much like text read from a file. The input sent to a
217 subprocess by @code{call-process-region} is encoded using a coding
218 system, much like text written into a file. @xref{Coding Systems}.
220 @defun call-process program &optional infile destination display &rest args
221 This function calls @var{program} in a separate process and waits for
224 The standard input for the process comes from file @var{infile} if
225 @var{infile} is not @code{nil}, and from the null device otherwise.
226 The argument @var{destination} says where to put the process output.
227 Here are the possibilities:
231 Insert the output in that buffer, before point. This includes both the
232 standard output stream and the standard error stream of the process.
235 Insert the output in a buffer with that name, before point.
238 Insert the output in the current buffer, before point.
244 Discard the output, and return @code{nil} immediately without waiting
245 for the subprocess to finish.
247 In this case, the process is not truly synchronous, since it can run in
248 parallel with Emacs; but you can think of it as synchronous in that
249 Emacs is essentially finished with the subprocess as soon as this
252 MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
255 @item @code{(@var{real-destination} @var{error-destination})}
256 Keep the standard output stream separate from the standard error stream;
257 deal with the ordinary output as specified by @var{real-destination},
258 and dispose of the error output according to @var{error-destination}.
259 If @var{error-destination} is @code{nil}, that means to discard the
260 error output, @code{t} means mix it with the ordinary output, and a
261 string specifies a file name to redirect error output into.
263 You can't directly specify a buffer to put the error output in; that is
264 too difficult to implement. But you can achieve this result by sending
265 the error output to a temporary file and then inserting the file into a
269 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
270 the buffer as output is inserted. (However, if the coding system chosen
271 for decoding output is @code{undecided}, meaning deduce the encoding
272 from the actual data, then redisplay sometimes cannot continue once
273 non-@acronym{ASCII} characters are encountered. There are fundamental
274 reasons why it is hard to fix this; see @ref{Output from Processes}.)
276 Otherwise the function @code{call-process} does no redisplay, and the
277 results become visible on the screen only when Emacs redisplays that
278 buffer in the normal course of events.
280 The remaining arguments, @var{args}, are strings that specify command
281 line arguments for the program.
283 The value returned by @code{call-process} (unless you told it not to
284 wait) indicates the reason for process termination. A number gives the
285 exit status of the subprocess; 0 means success, and any other value
286 means failure. If the process terminated with a signal,
287 @code{call-process} returns a string describing the signal.
289 In the examples below, the buffer @samp{foo} is current.
293 (call-process "pwd" nil t)
296 ---------- Buffer: foo ----------
297 /usr/user/lewis/manual
298 ---------- Buffer: foo ----------
302 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
305 ---------- Buffer: bar ----------
306 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
308 ---------- Buffer: bar ----------
312 Here is a good example of the use of @code{call-process}, which used to
313 be found in the definition of @code{insert-directory}:
317 (call-process insert-directory-program nil t nil @var{switches}
319 (concat (file-name-as-directory file) ".")
325 @defun process-file program &optional infile buffer display &rest args
326 This function processes files synchronously in a separate process. It
327 is similar to @code{call-process} but may invoke a file handler based
328 on the value of the variable @code{default-directory}. The current
329 working directory of the subprocess is @code{default-directory}.
331 The arguments are handled in almost the same way as for
332 @code{call-process}, with the following differences:
334 Some file handlers may not support all combinations and forms of the
335 arguments @var{infile}, @var{buffer}, and @var{display}. For example,
336 some file handlers might behave as if @var{display} were @code{nil},
337 regardless of the value actually passed. As another example, some
338 file handlers might not support separating standard output and error
339 output by way of the @var{buffer} argument.
341 If a file handler is invoked, it determines the program to run based
342 on the first argument @var{program}. For instance, consider that a
343 handler for remote files is invoked. Then the path that is used for
344 searching the program might be different than @code{exec-path}.
346 The second argument @var{infile} may invoke a file handler. The file
347 handler could be different from the handler chosen for the
348 @code{process-file} function itself. (For example,
349 @code{default-directory} could be on a remote host, whereas
350 @var{infile} is on another remote host. Or @code{default-directory}
351 could be non-special, whereas @var{infile} is on a remote host.)
353 If @var{buffer} is a list of the form @code{(@var{real-destination}
354 @var{error-destination})}, and @var{error-destination} names a file,
355 then the same remarks as for @var{infile} apply.
357 The remaining arguments (@var{args}) will be passed to the process
358 verbatim. Emacs is not involved in processing file names that are
359 present in @var{args}. To avoid confusion, it may be best to avoid
360 absolute file names in @var{args}, but rather to specify all file
361 names as relative to @code{default-directory}. The function
362 @code{file-relative-name} is useful for constructing such relative
366 @defun call-process-region start end program &optional delete destination display &rest args
367 This function sends the text from @var{start} to @var{end} as
368 standard input to a process running @var{program}. It deletes the text
369 sent if @var{delete} is non-@code{nil}; this is useful when
370 @var{destination} is @code{t}, to insert the output in the current
371 buffer in place of the input.
373 The arguments @var{destination} and @var{display} control what to do
374 with the output from the subprocess, and whether to update the display
375 as it comes in. For details, see the description of
376 @code{call-process}, above. If @var{destination} is the integer 0,
377 @code{call-process-region} discards the output and returns @code{nil}
378 immediately, without waiting for the subprocess to finish (this only
379 works if asynchronous subprocesses are supported).
381 The remaining arguments, @var{args}, are strings that specify command
382 line arguments for the program.
384 The return value of @code{call-process-region} is just like that of
385 @code{call-process}: @code{nil} if you told it to return without
386 waiting; otherwise, a number or string which indicates how the
387 subprocess terminated.
389 In the following example, we use @code{call-process-region} to run the
390 @code{cat} utility, with standard input being the first five characters
391 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
392 standard input into its standard output. Since the argument
393 @var{destination} is @code{t}, this output is inserted in the current
398 ---------- Buffer: foo ----------
400 ---------- Buffer: foo ----------
404 (call-process-region 1 6 "cat" nil t)
407 ---------- Buffer: foo ----------
409 ---------- Buffer: foo ----------
413 The @code{shell-command-on-region} command uses
414 @code{call-process-region} like this:
420 shell-file-name ; @r{Name of program.}
421 nil ; @r{Do not delete region.}
422 buffer ; @r{Send output to @code{buffer}.}
423 nil ; @r{No redisplay during output.}
424 "-c" command) ; @r{Arguments for the shell.}
429 @defun call-process-shell-command command &optional infile destination display &rest args
430 This function executes the shell command @var{command} synchronously
431 in a separate process. The final arguments @var{args} are additional
432 arguments to add at the end of @var{command}. The other arguments
433 are handled as in @code{call-process}.
436 @defun process-file-shell-command command &optional infile destination display &rest args
437 This function is like @code{call-process-shell-command}, but uses
438 @code{process-file} internally. Depending on @code{default-directory},
439 @var{command} can be executed also on remote hosts.
442 @defun shell-command-to-string command
443 This function executes @var{command} (a string) as a shell command,
444 then returns the command's output as a string.
447 @node Asynchronous Processes
448 @section Creating an Asynchronous Process
449 @cindex asynchronous subprocess
451 After an @dfn{asynchronous process} is created, Emacs and the subprocess
452 both continue running immediately. The process thereafter runs
453 in parallel with Emacs, and the two can communicate with each other
454 using the functions described in the following sections. However,
455 communication is only partially asynchronous: Emacs sends data to the
456 process only when certain functions are called, and Emacs accepts data
457 from the process only when Emacs is waiting for input or for a time
460 Here we describe how to create an asynchronous process.
462 @defun start-process name buffer-or-name program &rest args
463 This function creates a new asynchronous subprocess and starts the
464 program @var{program} running in it. It returns a process object that
465 stands for the new subprocess in Lisp. The argument @var{name}
466 specifies the name for the process object; if a process with this name
467 already exists, then @var{name} is modified (by appending @samp{<1>},
468 etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to
469 associate with the process.
471 The remaining arguments, @var{args}, are strings that specify command
472 line arguments for the program.
474 In the example below, the first process is started and runs (rather,
475 sleeps) for 100 seconds. Meanwhile, the second process is started, and
476 given the name @samp{my-process<1>} for the sake of uniqueness. It
477 inserts the directory listing at the end of the buffer @samp{foo},
478 before the first process finishes. Then it finishes, and a message to
479 that effect is inserted in the buffer. Much later, the first process
480 finishes, and another message is inserted in the buffer for it.
484 (start-process "my-process" "foo" "sleep" "100")
485 @result{} #<process my-process>
489 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
490 @result{} #<process my-process<1>>
492 ---------- Buffer: foo ----------
494 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
495 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
497 Process my-process<1> finished
499 Process my-process finished
500 ---------- Buffer: foo ----------
505 @defun start-file-process name buffer-or-name program &rest args
506 Like @code{start-process}, this function starts a new asynchronous
507 subprocess running @var{program} in it, and returns its process
508 object---when @code{default-directory} is not a magic file name.
510 If @code{default-directory} is magic, the function invokes its file
511 handler instead. This handler ought to run @var{program}, perhaps on
512 the local host, perhaps on a remote host that corresponds to
513 @code{default-directory}. In the latter case, the local part of
514 @code{default-directory} becomes the working directory of the process.
516 This function does not try to invoke file name handlers for
517 @var{program} or for the @var{program-args}.
519 Depending on the implementation of the file handler, it might not be
520 possible to apply @code{process-filter} or @code{process-sentinel} to
521 the resulting process object (@pxref{Filter Functions}, @pxref{Sentinels}).
523 Some file handlers may not support @code{start-file-process} (for
524 example @code{ange-ftp-hook-function}). In such cases, the function
525 does nothing and returns @code{nil}.
528 @defun start-process-shell-command name buffer-or-name command &rest command-args
529 This function is like @code{start-process} except that it uses a shell
530 to execute the specified command. The argument @var{command} is a shell
531 command name, and @var{command-args} are the arguments for the shell
532 command. The variable @code{shell-file-name} specifies which shell to
535 The point of running a program through the shell, rather than directly
536 with @code{start-process}, is so that you can employ shell features such
537 as wildcards in the arguments. It follows that if you include an
538 arbitrary user-specified arguments in the command, you should quote it
539 with @code{shell-quote-argument} first, so that any special shell
540 characters do @emph{not} have their special shell meanings. @xref{Shell
544 @defun start-file-process-shell-command name buffer-or-name command &rest command-args
545 This function is like @code{start-process-shell-command}, but uses
546 @code{start-file-process} internally. By this, @var{command} can be
547 executed also on remote hosts, depending on @code{default-directory}.
550 @defvar process-connection-type
552 @cindex @acronym{PTY}s
553 This variable controls the type of device used to communicate with
554 asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are
555 used, when available. Otherwise, pipes are used.
557 @acronym{PTY}s are usually preferable for processes visible to the user, as
558 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
559 etc.) to work between the process and its children, whereas pipes do
560 not. For subprocesses used for internal purposes by programs, it is
561 often better to use a pipe, because they are more efficient. In
562 addition, the total number of @acronym{PTY}s is limited on many systems and
563 it is good not to waste them.
565 The value of @code{process-connection-type} takes effect when
566 @code{start-process} is called. So you can specify how to communicate
567 with one subprocess by binding the variable around the call to
568 @code{start-process}.
572 (let ((process-connection-type nil)) ; @r{Use a pipe.}
573 (start-process @dots{}))
577 To determine whether a given subprocess actually got a pipe or a
578 @acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process
582 @node Deleting Processes
583 @section Deleting Processes
584 @cindex deleting processes
586 @dfn{Deleting a process} disconnects Emacs immediately from the
587 subprocess. Processes are deleted automatically after they terminate,
588 but not necessarily right away. You can delete a process explicitly
589 at any time. If you delete a terminated process explicitly before it
590 is deleted automatically, no harm results. Deleting a running
591 process sends a signal to terminate it (and its child processes if
592 any), and calls the process sentinel if it has one. @xref{Sentinels}.
594 When a process is deleted, the process object itself continues to
595 exist as long as other Lisp objects point to it. All the Lisp
596 primitives that work on process objects accept deleted processes, but
597 those that do I/O or send signals will report an error. The process
598 mark continues to point to the same place as before, usually into a
599 buffer where output from the process was being inserted.
601 @defopt delete-exited-processes
602 This variable controls automatic deletion of processes that have
603 terminated (due to calling @code{exit} or to a signal). If it is
604 @code{nil}, then they continue to exist until the user runs
605 @code{list-processes}. Otherwise, they are deleted immediately after
609 @defun delete-process process
610 This function deletes a process, killing it with a @code{SIGKILL}
611 signal. The argument may be a process, the name of a process, a
612 buffer, or the name of a buffer. (A buffer or buffer-name stands for
613 the process that @code{get-buffer-process} returns.) Calling
614 @code{delete-process} on a running process terminates it, updates the
615 process status, and runs the sentinel (if any) immediately. If the
616 process has already terminated, calling @code{delete-process} has no
617 effect on its status, or on the running of its sentinel (which will
618 happen sooner or later).
622 (delete-process "*shell*")
628 @node Process Information
629 @section Process Information
631 Several functions return information about processes.
632 @code{list-processes} is provided for interactive use.
634 @deffn Command list-processes &optional query-only
635 This command displays a listing of all living processes. In addition,
636 it finally deletes any process whose status was @samp{Exited} or
637 @samp{Signaled}. It returns @code{nil}.
639 If @var{query-only} is non-@code{nil} then it lists only processes
640 whose query flag is non-@code{nil}. @xref{Query Before Exit}.
644 This function returns a list of all processes that have not been deleted.
649 @result{} (#<process display-time> #<process shell>)
654 @defun get-process name
655 This function returns the process named @var{name}, or @code{nil} if
656 there is none. An error is signaled if @var{name} is not a string.
660 (get-process "shell")
661 @result{} #<process shell>
666 @defun process-command process
667 This function returns the command that was executed to start
668 @var{process}. This is a list of strings, the first string being the
669 program executed and the rest of the strings being the arguments that
670 were given to the program.
674 (process-command (get-process "shell"))
675 @result{} ("/bin/csh" "-i")
680 @defun process-contact process &optional key
682 This function returns information about how a network or serial
683 process was set up. For a network process, when @var{key} is
684 @code{nil}, it returns @code{(@var{hostname} @var{service})} which
685 specifies what you connected to. For a serial process, when @var{key}
686 is @code{nil}, it returns @code{(@var{port} @var{speed})}. For an
687 ordinary child process, this function always returns @code{t}.
689 If @var{key} is @code{t}, the value is the complete status information
690 for the connection, server, or serial port; that is, the list of
691 keywords and values specified in @code{make-network-process} or
692 @code{make-serial-process}, except that some of the values represent
693 the current status instead of what you specified.
695 For a network process:
699 The associated value is the process buffer.
701 The associated value is the process filter function.
703 The associated value is the process sentinel function.
705 In a connection, the address in internal format of the remote peer.
707 The local address, in internal format.
709 In a server, if you specified @code{t} for @var{service},
710 this value is the actual port number.
713 @code{:local} and @code{:remote} are included even if they were not
714 specified explicitly in @code{make-network-process}.
716 For a serial process, see @code{make-serial-process} and
717 @code{serial-process-configure} for a list of keys.
719 If @var{key} is a keyword, the function returns the value corresponding
723 @defun process-id process
724 This function returns the @acronym{PID} of @var{process}. This is an
725 integer that distinguishes the process @var{process} from all other
726 processes running on the same computer at the current time. The
727 @acronym{PID} of a process is chosen by the operating system kernel when the
728 process is started and remains constant as long as the process exists.
731 @defun process-name process
732 This function returns the name of @var{process}.
735 @defun process-status process-name
736 This function returns the status of @var{process-name} as a symbol.
737 The argument @var{process-name} must be a process, a buffer, a
738 process name (string) or a buffer name (string).
740 The possible values for an actual subprocess are:
744 for a process that is running.
746 for a process that is stopped but continuable.
748 for a process that has exited.
750 for a process that has received a fatal signal.
752 for a network connection that is open.
754 for a network connection that is closed. Once a connection
755 is closed, you cannot reopen it, though you might be able to open
756 a new connection to the same place.
758 for a non-blocking connection that is waiting to complete.
760 for a non-blocking connection that has failed to complete.
762 for a network server that is listening.
764 if @var{process-name} is not the name of an existing process.
769 (process-status "shell")
773 (process-status (get-buffer "*shell*"))
778 @result{} #<process xx<1>>
784 For a network connection, @code{process-status} returns one of the symbols
785 @code{open} or @code{closed}. The latter means that the other side
786 closed the connection, or Emacs did @code{delete-process}.
789 @defun process-type process
790 This function returns the symbol @code{network} for a network
791 connection or server, @code{serial} for a serial port connection, or
792 @code{real} for a real subprocess.
795 @defun process-exit-status process
796 This function returns the exit status of @var{process} or the signal
797 number that killed it. (Use the result of @code{process-status} to
798 determine which of those it is.) If @var{process} has not yet
799 terminated, the value is 0.
802 @defun process-tty-name process
803 This function returns the terminal name that @var{process} is using for
804 its communication with Emacs---or @code{nil} if it is using pipes
805 instead of a terminal (see @code{process-connection-type} in
806 @ref{Asynchronous Processes}).
809 @defun process-coding-system process
810 @anchor{Coding systems for a subprocess}
811 This function returns a cons cell describing the coding systems in use
812 for decoding output from @var{process} and for encoding input to
813 @var{process} (@pxref{Coding Systems}). The value has this form:
816 (@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
820 @defun set-process-coding-system process &optional decoding-system encoding-system
821 This function specifies the coding systems to use for subsequent output
822 from and input to @var{process}. It will use @var{decoding-system} to
823 decode subprocess output, and @var{encoding-system} to encode subprocess
827 Every process also has a property list that you can use to store
828 miscellaneous values associated with the process.
830 @defun process-get process propname
831 This function returns the value of the @var{propname} property
835 @defun process-put process propname value
836 This function sets the value of the @var{propname} property
837 of @var{process} to @var{value}.
840 @defun process-plist process
841 This function returns the process plist of @var{process}.
844 @defun set-process-plist process plist
845 This function sets the process plist of @var{process} to @var{plist}.
848 @node Input to Processes
849 @section Sending Input to Processes
850 @cindex process input
852 Asynchronous subprocesses receive input when it is sent to them by
853 Emacs, which is done with the functions in this section. You must
854 specify the process to send input to, and the input data to send. The
855 data appears on the ``standard input'' of the subprocess.
857 Some operating systems have limited space for buffered input in a
858 @acronym{PTY}. On these systems, Emacs sends an @acronym{EOF}
859 periodically amidst the other characters, to force them through. For
860 most programs, these @acronym{EOF}s do no harm.
862 Subprocess input is normally encoded using a coding system before the
863 subprocess receives it, much like text written into a file. You can use
864 @code{set-process-coding-system} to specify which coding system to use
865 (@pxref{Process Information}). Otherwise, the coding system comes from
866 @code{coding-system-for-write}, if that is non-@code{nil}; or else from
867 the defaulting mechanism (@pxref{Default Coding Systems}).
869 Sometimes the system is unable to accept input for that process,
870 because the input buffer is full. When this happens, the send functions
871 wait a short while, accepting output from subprocesses, and then try
872 again. This gives the subprocess a chance to read more of its pending
873 input and make space in the buffer. It also allows filters, sentinels
874 and timers to run---so take account of that in writing your code.
876 In these functions, the @var{process} argument can be a process or
877 the name of a process, or a buffer or buffer name (which stands
878 for a process via @code{get-buffer-process}). @code{nil} means
879 the current buffer's process.
881 @defun process-send-string process string
882 This function sends @var{process} the contents of @var{string} as
883 standard input. If it is @code{nil}, the current buffer's process is used.
885 The function returns @code{nil}.
889 (process-send-string "shell<1>" "ls\n")
895 ---------- Buffer: *shell* ----------
897 introduction.texi syntax-tables.texi~
898 introduction.texi~ text.texi
899 introduction.txt text.texi~
901 ---------- Buffer: *shell* ----------
906 @defun process-send-region process start end
907 This function sends the text in the region defined by @var{start} and
908 @var{end} as standard input to @var{process}.
910 An error is signaled unless both @var{start} and @var{end} are
911 integers or markers that indicate positions in the current buffer. (It
912 is unimportant which number is larger.)
915 @defun process-send-eof &optional process
916 This function makes @var{process} see an end-of-file in its
917 input. The @acronym{EOF} comes after any text already sent to it.
919 The function returns @var{process}.
923 (process-send-eof "shell")
929 @defun process-running-child-p process
930 This function will tell you whether a subprocess has given control of
931 its terminal to its own child process. The value is @code{t} if this is
932 true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
936 @node Signals to Processes
937 @section Sending Signals to Processes
938 @cindex process signals
939 @cindex sending signals
942 @dfn{Sending a signal} to a subprocess is a way of interrupting its
943 activities. There are several different signals, each with its own
944 meaning. The set of signals and their names is defined by the operating
945 system. For example, the signal @code{SIGINT} means that the user has
946 typed @kbd{C-c}, or that some analogous thing has happened.
948 Each signal has a standard effect on the subprocess. Most signals
949 kill the subprocess, but some stop or resume execution instead. Most
950 signals can optionally be handled by programs; if the program handles
951 the signal, then we can say nothing in general about its effects.
953 You can send signals explicitly by calling the functions in this
954 section. Emacs also sends signals automatically at certain times:
955 killing a buffer sends a @code{SIGHUP} signal to all its associated
956 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
957 processes. (@code{SIGHUP} is a signal that usually indicates that the
958 user hung up the phone.)
960 Each of the signal-sending functions takes two optional arguments:
961 @var{process} and @var{current-group}.
963 The argument @var{process} must be either a process, a process
964 name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name
965 stands for a process through @code{get-buffer-process}. @code{nil}
966 stands for the process associated with the current buffer. An error
967 is signaled if @var{process} does not identify a process.
969 The argument @var{current-group} is a flag that makes a difference
970 when you are running a job-control shell as an Emacs subprocess. If it
971 is non-@code{nil}, then the signal is sent to the current process-group
972 of the terminal that Emacs uses to communicate with the subprocess. If
973 the process is a job-control shell, this means the shell's current
974 subjob. If it is @code{nil}, the signal is sent to the process group of
975 the immediate subprocess of Emacs. If the subprocess is a job-control
976 shell, this is the shell itself.
978 The flag @var{current-group} has no effect when a pipe is used to
979 communicate with the subprocess, because the operating system does not
980 support the distinction in the case of pipes. For the same reason,
981 job-control shells won't work when a pipe is used. See
982 @code{process-connection-type} in @ref{Asynchronous Processes}.
984 @defun interrupt-process &optional process current-group
985 This function interrupts the process @var{process} by sending the
986 signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt
987 character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
988 others) sends this signal. When the argument @var{current-group} is
989 non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
990 on the terminal by which Emacs talks to the subprocess.
993 @defun kill-process &optional process current-group
994 This function kills the process @var{process} by sending the
995 signal @code{SIGKILL}. This signal kills the subprocess immediately,
996 and cannot be handled by the subprocess.
999 @defun quit-process &optional process current-group
1000 This function sends the signal @code{SIGQUIT} to the process
1001 @var{process}. This signal is the one sent by the ``quit
1002 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
1006 @defun stop-process &optional process current-group
1007 This function stops the process @var{process} by sending the
1008 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
1011 Outside of Emacs, on systems with job control, the ``stop character''
1012 (usually @kbd{C-z}) normally sends this signal. When
1013 @var{current-group} is non-@code{nil}, you can think of this function as
1014 ``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
1018 @defun continue-process &optional process current-group
1019 This function resumes execution of the process @var{process} by sending
1020 it the signal @code{SIGCONT}. This presumes that @var{process} was
1025 @defun signal-process process signal
1026 This function sends a signal to process @var{process}. The argument
1027 @var{signal} specifies which signal to send; it should be an integer.
1029 The @var{process} argument can be a system process @acronym{ID}; that
1030 allows you to send signals to processes that are not children of
1034 @node Output from Processes
1035 @section Receiving Output from Processes
1036 @cindex process output
1037 @cindex output from processes
1039 There are two ways to receive the output that a subprocess writes to
1040 its standard output stream. The output can be inserted in a buffer,
1041 which is called the associated buffer of the process, or a function
1042 called the @dfn{filter function} can be called to act on the output. If
1043 the process has no buffer and no filter function, its output is
1046 When a subprocess terminates, Emacs reads any pending output,
1047 then stops reading output from that subprocess. Therefore, if the
1048 subprocess has children that are still live and still producing
1049 output, Emacs won't receive that output.
1051 Output from a subprocess can arrive only while Emacs is waiting: when
1052 reading terminal input, in @code{sit-for} and @code{sleep-for}
1053 (@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
1054 Output}). This minimizes the problem of timing errors that usually
1055 plague parallel programming. For example, you can safely create a
1056 process and only then specify its buffer or filter function; no output
1057 can arrive before you finish, if the code in between does not call any
1058 primitive that waits.
1060 @defvar process-adaptive-read-buffering
1061 On some systems, when Emacs reads the output from a subprocess, the
1062 output data is read in very small blocks, potentially resulting in
1063 very poor performance. This behavior can be remedied to some extent
1064 by setting the variable @var{process-adaptive-read-buffering} to a
1065 non-@code{nil} value (the default), as it will automatically delay reading
1066 from such processes, thus allowing them to produce more output before
1067 Emacs tries to read it.
1070 It is impossible to separate the standard output and standard error
1071 streams of the subprocess, because Emacs normally spawns the subprocess
1072 inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If
1073 you want to keep the output to those streams separate, you should
1074 redirect one of them to a file---for example, by using an appropriate
1078 * Process Buffers:: If no filter, output is put in a buffer.
1079 * Filter Functions:: Filter functions accept output from the process.
1080 * Decoding Output:: Filters can get unibyte or multibyte strings.
1081 * Accepting Output:: How to wait until process output arrives.
1084 @node Process Buffers
1085 @subsection Process Buffers
1087 A process can (and usually does) have an @dfn{associated buffer},
1088 which is an ordinary Emacs buffer that is used for two purposes: storing
1089 the output from the process, and deciding when to kill the process. You
1090 can also use the buffer to identify a process to operate on, since in
1091 normal practice only one process is associated with any given buffer.
1092 Many applications of processes also use the buffer for editing input to
1093 be sent to the process, but this is not built into Emacs Lisp.
1095 Unless the process has a filter function (@pxref{Filter Functions}),
1096 its output is inserted in the associated buffer. The position to insert
1097 the output is determined by the @code{process-mark}, which is then
1098 updated to point to the end of the text just inserted. Usually, but not
1099 always, the @code{process-mark} is at the end of the buffer.
1101 @defun process-buffer process
1102 This function returns the associated buffer of the process
1107 (process-buffer (get-process "shell"))
1108 @result{} #<buffer *shell*>
1113 @defun process-mark process
1114 This function returns the process marker for @var{process}, which is the
1115 marker that says where to insert output from the process.
1117 If @var{process} does not have a buffer, @code{process-mark} returns a
1118 marker that points nowhere.
1120 Insertion of process output in a buffer uses this marker to decide where
1121 to insert, and updates it to point after the inserted text. That is why
1122 successive batches of output are inserted consecutively.
1124 Filter functions normally should use this marker in the same fashion
1125 as is done by direct insertion of output in the buffer. A good
1126 example of a filter function that uses @code{process-mark} is found at
1127 the end of the following section.
1129 When the user is expected to enter input in the process buffer for
1130 transmission to the process, the process marker separates the new input
1131 from previous output.
1134 @defun set-process-buffer process buffer
1135 This function sets the buffer associated with @var{process} to
1136 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
1137 associated with no buffer.
1140 @defun get-buffer-process buffer-or-name
1141 This function returns a nondeleted process associated with the buffer
1142 specified by @var{buffer-or-name}. If there are several processes
1143 associated with it, this function chooses one (currently, the one most
1144 recently created, but don't count on that). Deletion of a process
1145 (see @code{delete-process}) makes it ineligible for this function to
1148 It is usually a bad idea to have more than one process associated with
1153 (get-buffer-process "*shell*")
1154 @result{} #<process shell>
1158 Killing the process's buffer deletes the process, which kills the
1159 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
1162 @node Filter Functions
1163 @subsection Process Filter Functions
1164 @cindex filter function
1165 @cindex process filter
1167 A process @dfn{filter function} is a function that receives the
1168 standard output from the associated process. If a process has a filter,
1169 then @emph{all} output from that process is passed to the filter. The
1170 process buffer is used directly for output from the process only when
1173 The filter function can only be called when Emacs is waiting for
1174 something, because process output arrives only at such times. Emacs
1175 waits when reading terminal input, in @code{sit-for} and
1176 @code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
1177 (@pxref{Accepting Output}).
1179 A filter function must accept two arguments: the associated process
1180 and a string, which is output just received from it. The function is
1181 then free to do whatever it chooses with the output.
1183 Quitting is normally inhibited within a filter function---otherwise,
1184 the effect of typing @kbd{C-g} at command level or to quit a user
1185 command would be unpredictable. If you want to permit quitting inside
1186 a filter function, bind @code{inhibit-quit} to @code{nil}. In most
1187 cases, the right way to do this is with the macro
1188 @code{with-local-quit}. @xref{Quitting}.
1190 If an error happens during execution of a filter function, it is
1191 caught automatically, so that it doesn't stop the execution of whatever
1192 program was running when the filter function was started. However, if
1193 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1194 off. This makes it possible to use the Lisp debugger to debug the
1195 filter function. @xref{Debugger}.
1197 Many filter functions sometimes or always insert the text in the
1198 process's buffer, mimicking the actions of Emacs when there is no
1199 filter. Such filter functions need to use @code{set-buffer} in order to
1200 be sure to insert in that buffer. To avoid setting the current buffer
1201 semipermanently, these filter functions must save and restore the
1202 current buffer. They should also update the process marker, and in some
1203 cases update the value of point. Here is how to do these things:
1207 (defun ordinary-insertion-filter (proc string)
1208 (with-current-buffer (process-buffer proc)
1209 (let ((moving (= (point) (process-mark proc))))
1213 ;; @r{Insert the text, advancing the process marker.}
1214 (goto-char (process-mark proc))
1216 (set-marker (process-mark proc) (point)))
1217 (if moving (goto-char (process-mark proc))))))
1222 The reason to use @code{with-current-buffer}, rather than using
1223 @code{save-excursion} to save and restore the current buffer, is so as
1224 to preserve the change in point made by the second call to
1227 To make the filter force the process buffer to be visible whenever new
1228 text arrives, insert the following line just before the
1229 @code{with-current-buffer} construct:
1232 (display-buffer (process-buffer proc))
1235 To force point to the end of the new output, no matter where it was
1236 previously, eliminate the variable @code{moving} and call
1237 @code{goto-char} unconditionally.
1239 In earlier Emacs versions, every filter function that did regular
1240 expression searching or matching had to explicitly save and restore the
1241 match data. Now Emacs does this automatically for filter functions;
1242 they never need to do it explicitly. @xref{Match Data}.
1244 A filter function that writes the output into the buffer of the
1245 process should check whether the buffer is still alive. If it tries to
1246 insert into a dead buffer, it will get an error. The expression
1247 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
1248 if the buffer is dead.
1250 The output to the function may come in chunks of any size. A program
1251 that produces the same output twice in a row may send it as one batch of
1252 200 characters one time, and five batches of 40 characters the next. If
1253 the filter looks for certain text strings in the subprocess output, make
1254 sure to handle the case where one of these strings is split across two
1255 or more batches of output.
1257 @defun set-process-filter process filter
1258 This function gives @var{process} the filter function @var{filter}. If
1259 @var{filter} is @code{nil}, it gives the process no filter.
1262 @defun process-filter process
1263 This function returns the filter function of @var{process}, or @code{nil}
1267 Here is an example of use of a filter function:
1271 (defun keep-output (process output)
1272 (setq kept (cons output kept)))
1273 @result{} keep-output
1280 (set-process-filter (get-process "shell") 'keep-output)
1281 @result{} keep-output
1284 (process-send-string "shell" "ls ~/other\n")
1287 @result{} ("lewis@@slug[8] % "
1290 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
1291 address.txt backup.psf kolstad.psf
1292 backup.bib~ david.mss resume-Dec-86.mss~
1293 backup.err david.psf resume-Dec.psf
1294 backup.mss dland syllabus.mss
1296 "#backups.mss# backup.mss~ kolstad.mss
1301 @ignore @c The code in this example doesn't show the right way to do things.
1302 Here is another, more realistic example, which demonstrates how to use
1303 the process mark to do insertion in the same fashion as is done when
1304 there is no filter function:
1308 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
1309 ;; @r{and make sure that buffer is shown in some window.}
1310 (defun my-process-filter (proc str)
1311 (let ((cur (selected-window))
1313 (pop-to-buffer my-shell-buffer)
1316 (goto-char (point-max))
1318 (set-marker (process-mark proc) (point-max))
1319 (select-window cur)))
1324 @node Decoding Output
1325 @subsection Decoding Process Output
1326 @cindex decode process output
1328 When Emacs writes process output directly into a multibyte buffer,
1329 it decodes the output according to the process output coding system.
1330 If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
1331 converts the unibyte output to multibyte using
1332 @code{string-to-multibyte}, and inserts the resulting multibyte text.
1334 You can use @code{set-process-coding-system} to specify which coding
1335 system to use (@pxref{Process Information}). Otherwise, the coding
1336 system comes from @code{coding-system-for-read}, if that is
1337 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
1340 @strong{Warning:} Coding systems such as @code{undecided} which
1341 determine the coding system from the data do not work entirely
1342 reliably with asynchronous subprocess output. This is because Emacs
1343 has to process asynchronous subprocess output in batches, as it
1344 arrives. Emacs must try to detect the proper coding system from one
1345 batch at a time, and this does not always work. Therefore, if at all
1346 possible, specify a coding system that determines both the character
1347 code conversion and the end of line conversion---that is, one like
1348 @code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
1350 @c Let's keep the index entries that were there for
1351 @c set-process-filter-multibyte and process-filter-multibyte-p,
1352 @cindex filter multibyte flag, of process
1353 @cindex process filter multibyte flag
1354 When Emacs calls a process filter function, it provides the process
1355 output as a multibyte string or as a unibyte string according to the
1356 process's filter coding system. Emacs
1357 decodes the output according to the process output coding system,
1358 which usually produces a multibyte string, except for coding systems
1359 such as @code{binary} and @code{raw-text}
1361 @node Accepting Output
1362 @subsection Accepting Output from Processes
1363 @cindex accept input from processes
1365 Output from asynchronous subprocesses normally arrives only while
1366 Emacs is waiting for some sort of external event, such as elapsed time
1367 or terminal input. Occasionally it is useful in a Lisp program to
1368 explicitly permit output to arrive at a specific point, or even to wait
1369 until output arrives from a process.
1371 @defun accept-process-output &optional process seconds millisec just-this-one
1372 This function allows Emacs to read pending output from processes. The
1373 output is inserted in the associated buffers or given to their filter
1374 functions. If @var{process} is non-@code{nil} then this function does
1375 not return until some output has been received from @var{process}.
1378 The arguments @var{seconds} and @var{millisec} let you specify timeout
1379 periods. The former specifies a period measured in seconds and the
1380 latter specifies one measured in milliseconds. The two time periods
1381 thus specified are added together, and @code{accept-process-output}
1382 returns after that much time, whether or not there has been any
1385 The argument @var{millisec} is semi-obsolete nowadays because
1386 @var{seconds} can be a floating point number to specify waiting a
1387 fractional number of seconds. If @var{seconds} is 0, the function
1388 accepts whatever output is pending but does not wait.
1390 @c Emacs 22.1 feature
1391 If @var{process} is a process, and the argument @var{just-this-one} is
1392 non-@code{nil}, only output from that process is handled, suspending output
1393 from other processes until some output has been received from that
1394 process or the timeout expires. If @var{just-this-one} is an integer,
1395 also inhibit running timers. This feature is generally not
1396 recommended, but may be necessary for specific applications, such as
1399 The function @code{accept-process-output} returns non-@code{nil} if it
1400 did get some output, or @code{nil} if the timeout expired before output
1405 @section Sentinels: Detecting Process Status Changes
1406 @cindex process sentinel
1407 @cindex sentinel (of process)
1409 A @dfn{process sentinel} is a function that is called whenever the
1410 associated process changes status for any reason, including signals
1411 (whether sent by Emacs or caused by the process's own actions) that
1412 terminate, stop, or continue the process. The process sentinel is
1413 also called if the process exits. The sentinel receives two
1414 arguments: the process for which the event occurred, and a string
1415 describing the type of event.
1417 The string describing the event looks like one of the following:
1421 @code{"finished\n"}.
1424 @code{"exited abnormally with code @var{exitcode}\n"}.
1427 @code{"@var{name-of-signal}\n"}.
1430 @code{"@var{name-of-signal} (core dumped)\n"}.
1433 A sentinel runs only while Emacs is waiting (e.g., for terminal
1434 input, or for time to elapse, or for process output). This avoids the
1435 timing errors that could result from running them at random places in
1436 the middle of other Lisp programs. A program can wait, so that
1437 sentinels will run, by calling @code{sit-for} or @code{sleep-for}
1438 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
1439 Output}). Emacs also allows sentinels to run when the command loop is
1440 reading input. @code{delete-process} calls the sentinel when it
1441 terminates a running process.
1443 Emacs does not keep a queue of multiple reasons to call the sentinel
1444 of one process; it records just the current status and the fact that
1445 there has been a change. Therefore two changes in status, coming in
1446 quick succession, can call the sentinel just once. However, process
1447 termination will always run the sentinel exactly once. This is
1448 because the process status can't change again after termination.
1450 Emacs explicitly checks for output from the process before running
1451 the process sentinel. Once the sentinel runs due to process
1452 termination, no further output can arrive from the process.
1454 A sentinel that writes the output into the buffer of the process
1455 should check whether the buffer is still alive. If it tries to insert
1456 into a dead buffer, it will get an error. If the buffer is dead,
1457 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
1459 Quitting is normally inhibited within a sentinel---otherwise, the
1460 effect of typing @kbd{C-g} at command level or to quit a user command
1461 would be unpredictable. If you want to permit quitting inside a
1462 sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the
1463 right way to do this is with the macro @code{with-local-quit}.
1466 If an error happens during execution of a sentinel, it is caught
1467 automatically, so that it doesn't stop the execution of whatever
1468 programs was running when the sentinel was started. However, if
1469 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
1470 off. This makes it possible to use the Lisp debugger to debug the
1471 sentinel. @xref{Debugger}.
1473 While a sentinel is running, the process sentinel is temporarily
1474 set to @code{nil} so that the sentinel won't run recursively.
1475 For this reason it is not possible for a sentinel to specify
1478 In earlier Emacs versions, every sentinel that did regular expression
1479 searching or matching had to explicitly save and restore the match data.
1480 Now Emacs does this automatically for sentinels; they never need to do
1481 it explicitly. @xref{Match Data}.
1483 @defun set-process-sentinel process sentinel
1484 This function associates @var{sentinel} with @var{process}. If
1485 @var{sentinel} is @code{nil}, then the process will have no sentinel.
1486 The default behavior when there is no sentinel is to insert a message in
1487 the process's buffer when the process status changes.
1489 Changes in process sentinel take effect immediately---if the sentinel
1490 is slated to be run but has not been called yet, and you specify a new
1491 sentinel, the eventual call to the sentinel will use the new one.
1495 (defun msg-me (process event)
1497 (format "Process: %s had the event `%s'" process event)))
1498 (set-process-sentinel (get-process "shell") 'msg-me)
1502 (kill-process (get-process "shell"))
1503 @print{} Process: #<process shell> had the event `killed'
1504 @result{} #<process shell>
1509 @defun process-sentinel process
1510 This function returns the sentinel of @var{process}, or @code{nil} if it
1514 @defun waiting-for-user-input-p
1515 While a sentinel or filter function is running, this function returns
1516 non-@code{nil} if Emacs was waiting for keyboard input from the user at
1517 the time the sentinel or filter function was called, @code{nil} if it
1521 @node Query Before Exit
1522 @section Querying Before Exit
1524 When Emacs exits, it terminates all its subprocesses by sending them
1525 the @code{SIGHUP} signal. Because subprocesses may be doing
1526 valuable work, Emacs normally asks the user to confirm that it is ok
1527 to terminate them. Each process has a query flag which, if
1528 non-@code{nil}, says that Emacs should ask for confirmation before
1529 exiting and thus killing that process. The default for the query flag
1530 is @code{t}, meaning @emph{do} query.
1532 @defun process-query-on-exit-flag process
1533 This returns the query flag of @var{process}.
1536 @defun set-process-query-on-exit-flag process flag
1537 This function sets the query flag of @var{process} to @var{flag}. It
1542 ;; @r{Don't query about the shell process}
1543 (set-process-query-on-exit-flag (get-process "shell") nil)
1549 @defun process-kill-without-query process &optional do-query
1550 This function clears the query flag of @var{process}, so that
1551 Emacs will not query the user on account of that process.
1553 Actually, the function does more than that: it returns the old value of
1554 the process's query flag, and sets the query flag to @var{do-query}.
1555 Please don't use this function to do those things any more---please
1556 use the newer, cleaner functions @code{process-query-on-exit-flag} and
1557 @code{set-process-query-on-exit-flag} in all but the simplest cases.
1558 The only way you should use @code{process-kill-without-query} nowadays
1563 ;; @r{Don't query about the shell process}
1564 (process-kill-without-query (get-process "shell"))
1569 @node Transaction Queues
1570 @section Transaction Queues
1571 @cindex transaction queue
1573 You can use a @dfn{transaction queue} to communicate with a subprocess
1574 using transactions. First use @code{tq-create} to create a transaction
1575 queue communicating with a specified process. Then you can call
1576 @code{tq-enqueue} to send a transaction.
1578 @defun tq-create process
1579 This function creates and returns a transaction queue communicating with
1580 @var{process}. The argument @var{process} should be a subprocess
1581 capable of sending and receiving streams of bytes. It may be a child
1582 process, or it may be a TCP connection to a server, possibly on another
1586 @defun tq-enqueue queue question regexp closure fn &optional delay-question
1587 This function sends a transaction to queue @var{queue}. Specifying the
1588 queue has the effect of specifying the subprocess to talk to.
1590 The argument @var{question} is the outgoing message that starts the
1591 transaction. The argument @var{fn} is the function to call when the
1592 corresponding answer comes back; it is called with two arguments:
1593 @var{closure}, and the answer received.
1595 The argument @var{regexp} is a regular expression that should match
1596 text at the end of the entire answer, but nothing before; that's how
1597 @code{tq-enqueue} determines where the answer ends.
1599 If the argument @var{delay-question} is non-nil, delay sending this
1600 question until the process has finished replying to any previous
1601 questions. This produces more reliable results with some processes.
1603 The return value of @code{tq-enqueue} itself is not meaningful.
1606 @defun tq-close queue
1607 Shut down transaction queue @var{queue}, waiting for all pending transactions
1608 to complete, and then terminate the connection or child process.
1611 Transaction queues are implemented by means of a filter function.
1612 @xref{Filter Functions}.
1615 @section Network Connections
1616 @cindex network connection
1620 Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
1621 connections to other processes on the same machine or other machines.
1622 A network connection is handled by Lisp much like a subprocess, and is
1623 represented by a process object. However, the process you are
1624 communicating with is not a child of the Emacs process, so it has no
1625 process @acronym{ID}, and you can't kill it or send it signals. All you
1626 can do is send and receive data. @code{delete-process} closes the
1627 connection, but does not kill the program at the other end; that
1628 program must decide what to do about closure of the connection.
1630 Lisp programs can listen for connections by creating network
1631 servers. A network server is also represented by a kind of process
1632 object, but unlike a network connection, the network server never
1633 transfers data itself. When it receives a connection request, it
1634 creates a new network connection to represent the connection just
1635 made. (The network connection inherits certain information, including
1636 the process plist, from the server.) The network server then goes
1637 back to listening for more connection requests.
1639 Network connections and servers are created by calling
1640 @code{make-network-process} with an argument list consisting of
1641 keyword/argument pairs, for example @code{:server t} to create a
1642 server process, or @code{:type 'datagram} to create a datagram
1643 connection. @xref{Low-Level Network}, for details. You can also use
1644 the @code{open-network-stream} function described below.
1646 To distinguish the different types of processes, the
1647 @code{process-type} function returns the symbol @code{network} for a
1648 network connection or server, @code{serial} for a serial port
1649 connection, or @code{real} for a real subprocess.
1651 The @code{process-status} function returns @code{open},
1652 @code{closed}, @code{connect}, and @code{failed} for network
1653 connections. For a network server, the status is always
1654 @code{listen}. None of those values is possible for a real
1655 subprocess. @xref{Process Information}.
1657 You can stop and resume operation of a network process by calling
1658 @code{stop-process} and @code{continue-process}. For a server
1659 process, being stopped means not accepting new connections. (Up to 5
1660 connection requests will be queued for when you resume the server; you
1661 can increase this limit, unless it is imposed by the operating
1662 system.) For a network stream connection, being stopped means not
1663 processing input (any arriving input waits until you resume the
1664 connection). For a datagram connection, some number of packets may be
1665 queued but input may be lost. You can use the function
1666 @code{process-command} to determine whether a network connection or
1667 server is stopped; a non-@code{nil} value means yes.
1669 @defun open-network-stream name buffer-or-name host service
1670 This function opens a TCP connection, and returns a process object
1671 that represents the connection.
1673 The @var{name} argument specifies the name for the process object. It
1674 is modified as necessary to make it unique.
1676 The @var{buffer-or-name} argument is the buffer to associate with the
1677 connection. Output from the connection is inserted in the buffer,
1678 unless you specify a filter function to handle the output. If
1679 @var{buffer-or-name} is @code{nil}, it means that the connection is not
1680 associated with any buffer.
1682 The arguments @var{host} and @var{service} specify where to connect to;
1683 @var{host} is the host name (a string), and @var{service} is the name of
1684 a defined network service (a string) or a port number (an integer).
1687 @node Network Servers
1688 @section Network Servers
1689 @cindex network servers
1691 You create a server by calling @code{make-network-process} with
1692 @code{:server t}. The server will listen for connection requests from
1693 clients. When it accepts a client connection request, that creates a
1694 new network connection, itself a process object, with the following
1699 The connection's process name is constructed by concatenating the
1700 server process' @var{name} with a client identification string. The
1701 client identification string for an IPv4 connection looks like
1702 @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a
1703 unique number in brackets, as in @samp{<@var{nnn}>}. The number
1704 is unique for each connection in the Emacs session.
1707 If the server's filter is non-@code{nil}, the connection process does
1708 not get a separate process buffer; otherwise, Emacs creates a new
1709 buffer for the purpose. The buffer name is the server's buffer name
1710 or process name, concatenated with the client identification string.
1712 The server's process buffer value is never used directly by Emacs, but
1713 it is passed to the log function, which can log connections by
1714 inserting text there.
1717 The communication type and the process filter and sentinel are
1718 inherited from those of the server. The server never directly
1719 uses its filter and sentinel; their sole purpose is to initialize
1720 connections made to the server.
1723 The connection's process contact info is set according to the client's
1724 addressing information (typically an IP address and a port number).
1725 This information is associated with the @code{process-contact}
1726 keywords @code{:host}, @code{:service}, @code{:remote}.
1729 The connection's local address is set up according to the port
1730 number used for the connection.
1733 The client process' plist is initialized from the server's plist.
1740 A datagram connection communicates with individual packets rather
1741 than streams of data. Each call to @code{process-send} sends one
1742 datagram packet (@pxref{Input to Processes}), and each datagram
1743 received results in one call to the filter function.
1745 The datagram connection doesn't have to talk with the same remote
1746 peer all the time. It has a @dfn{remote peer address} which specifies
1747 where to send datagrams to. Each time an incoming datagram is passed
1748 to the filter function, the peer address is set to the address that
1749 datagram came from; that way, if the filter function sends a datagram,
1750 it will go back to that place. You can specify the remote peer
1751 address when you create the datagram connection using the
1752 @code{:remote} keyword. You can change it later on by calling
1753 @code{set-process-datagram-address}.
1755 @defun process-datagram-address process
1756 If @var{process} is a datagram connection or server, this function
1757 returns its remote peer address.
1760 @defun set-process-datagram-address process address
1761 If @var{process} is a datagram connection or server, this function
1762 sets its remote peer address to @var{address}.
1765 @node Low-Level Network
1766 @section Low-Level Network Access
1768 You can also create network connections by operating at a lower
1769 level than that of @code{open-network-stream}, using
1770 @code{make-network-process}.
1773 * Proc: Network Processes. Using @code{make-network-process}.
1774 * Options: Network Options. Further control over network connections.
1775 * Features: Network Feature Testing.
1776 Determining which network features work on
1777 the machine you are using.
1780 @node Network Processes
1781 @subsection @code{make-network-process}
1783 The basic function for creating network connections and network
1784 servers is @code{make-network-process}. It can do either of those
1785 jobs, depending on the arguments you give it.
1787 @defun make-network-process &rest args
1788 This function creates a network connection or server and returns the
1789 process object that represents it. The arguments @var{args} are a
1790 list of keyword/argument pairs. Omitting a keyword is always
1791 equivalent to specifying it with value @code{nil}, except for
1792 @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here
1793 are the meaningful keywords:
1796 @item :name @var{name}
1797 Use the string @var{name} as the process name. It is modified if
1798 necessary to make it unique.
1800 @item :type @var{type}
1801 Specify the communication type. A value of @code{nil} specifies a
1802 stream connection (the default); @code{datagram} specifies a datagram
1803 connection. Both connections and servers can be of either type.
1805 @item :server @var{server-flag}
1806 If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
1807 create a connection. For a stream type server, @var{server-flag} may
1808 be an integer which then specifies the length of the queue of pending
1809 connections to the server. The default queue length is 5.
1811 @item :host @var{host}
1812 Specify the host to connect to. @var{host} should be a host name or
1813 Internet address, as a string, or the symbol @code{local} to specify
1814 the local host. If you specify @var{host} for a server, it must
1815 specify a valid address for the local host, and only clients
1816 connecting to that address will be accepted.
1818 @item :service @var{service}
1819 @var{service} specifies a port number to connect to, or, for a server,
1820 the port number to listen on. It should be a service name that
1821 translates to a port number, or an integer specifying the port number
1822 directly. For a server, it can also be @code{t}, which means to let
1823 the system select an unused port number.
1825 @item :family @var{family}
1826 @var{family} specifies the address (and protocol) family for
1827 communication. @code{nil} means determine the proper address family
1828 automatically for the given @var{host} and @var{service}.
1829 @code{local} specifies a Unix socket, in which case @var{host} is
1830 ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6
1833 @item :local @var{local-address}
1834 For a server process, @var{local-address} is the address to listen on.
1835 It overrides @var{family}, @var{host} and @var{service}, and you
1836 may as well not specify them.
1838 @item :remote @var{remote-address}
1839 For a connection, @var{remote-address} is the address to connect to.
1840 It overrides @var{family}, @var{host} and @var{service}, and you
1841 may as well not specify them.
1843 For a datagram server, @var{remote-address} specifies the initial
1844 setting of the remote datagram address.
1846 The format of @var{local-address} or @var{remote-address} depends on
1851 An IPv4 address is represented as a five-element vector of four 8-bit
1852 integers and one 16-bit integer
1853 @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to
1854 numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number
1858 An IPv6 address is represented as a nine-element vector of 16-bit
1859 integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f}
1860 @var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address
1861 @var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and
1862 port number @var{p}.
1865 A local address is represented as a string which specifies the address
1866 in the local address space.
1869 An ``unsupported family'' address is represented by a cons
1870 @code{(@var{f} . @var{av})}, where @var{f} is the family number and
1871 @var{av} is a vector specifying the socket address using one element
1872 per address data byte. Do not rely on this format in portable code,
1873 as it may depend on implementation defined constants, data sizes, and
1874 data structure alignment.
1877 @item :nowait @var{bool}
1878 If @var{bool} is non-@code{nil} for a stream connection, return
1879 without waiting for the connection to complete. When the connection
1880 succeeds or fails, Emacs will call the sentinel function, with a
1881 second argument matching @code{"open"} (if successful) or
1882 @code{"failed"}. The default is to block, so that
1883 @code{make-network-process} does not return until the connection
1884 has succeeded or failed.
1886 @item :stop @var{stopped}
1887 Start the network connection or server in the `stopped' state if
1888 @var{stopped} is non-@code{nil}.
1890 @item :buffer @var{buffer}
1891 Use @var{buffer} as the process buffer.
1893 @item :coding @var{coding}
1894 Use @var{coding} as the coding system for this process. To specify
1895 different coding systems for decoding data from the connection and for
1896 encoding data sent to it, specify @code{(@var{decoding} .
1897 @var{encoding})} for @var{coding}.
1899 If you don't specify this keyword at all, the default
1900 is to determine the coding systems from the data.
1902 @item :noquery @var{query-flag}
1903 Initialize the process query flag to @var{query-flag}.
1904 @xref{Query Before Exit}.
1906 @item :filter @var{filter}
1907 Initialize the process filter to @var{filter}.
1909 @item :filter-multibyte @var{bool}
1910 If @var{bool} is non-@code{nil}, strings given to the process filter
1911 are multibyte, otherwise they are unibyte. If you don't specify this
1912 keyword at all, the default is that the strings are multibyte if
1913 @code{default-enable-multibyte-characters} is non-@code{nil}.
1915 @item :sentinel @var{sentinel}
1916 Initialize the process sentinel to @var{sentinel}.
1918 @item :log @var{log}
1919 Initialize the log function of a server process to @var{log}. The log
1920 function is called each time the server accepts a network connection
1921 from a client. The arguments passed to the log function are
1922 @var{server}, @var{connection}, and @var{message}, where @var{server}
1923 is the server process, @var{connection} is the new process for the
1924 connection, and @var{message} is a string describing what has
1927 @item :plist @var{plist}
1928 Initialize the process plist to @var{plist}.
1931 The original argument list, modified with the actual connection
1932 information, is available via the @code{process-contact} function.
1935 @node Network Options
1936 @subsection Network Options
1938 The following network options can be specified when you create a
1939 network process. Except for @code{:reuseaddr}, you can also set or
1940 modify these options later, using @code{set-network-process-option}.
1942 For a server process, the options specified with
1943 @code{make-network-process} are not inherited by the client
1944 connections, so you will need to set the necessary options for each
1945 child connection as it is created.
1948 @item :bindtodevice @var{device-name}
1949 If @var{device-name} is a non-empty string identifying a network
1950 interface name (see @code{network-interface-list}), only handle
1951 packets received on that interface. If @var{device-name} is @code{nil}
1952 (the default), handle packets received on any interface.
1954 Using this option may require special privileges on some systems.
1956 @item :broadcast @var{broadcast-flag}
1957 If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
1958 process will receive datagram packet sent to a broadcast address, and
1959 be able to send packets to a broadcast address. Ignored for a stream
1962 @item :dontroute @var{dontroute-flag}
1963 If @var{dontroute-flag} is non-@code{nil}, the process can only send
1964 to hosts on the same network as the local host.
1966 @item :keepalive @var{keepalive-flag}
1967 If @var{keepalive-flag} is non-@code{nil} for a stream connection,
1968 enable exchange of low-level keep-alive messages.
1970 @item :linger @var{linger-arg}
1971 If @var{linger-arg} is non-@code{nil}, wait for successful
1972 transmission of all queued packets on the connection before it is
1973 deleted (see @code{delete-process}). If @var{linger-arg} is an
1974 integer, it specifies the maximum time in seconds to wait for queued
1975 packets to be sent before closing the connection. Default is
1976 @code{nil} which means to discard unsent queued packets when the
1979 @item :oobinline @var{oobinline-flag}
1980 If @var{oobinline-flag} is non-@code{nil} for a stream connection,
1981 receive out-of-band data in the normal data stream. Otherwise, ignore
1984 @item :priority @var{priority}
1985 Set the priority for packets sent on this connection to the integer
1986 @var{priority}. The interpretation of this number is protocol
1987 specific, such as setting the TOS (type of service) field on IP
1988 packets sent on this connection. It may also have system dependent
1989 effects, such as selecting a specific output queue on the network
1992 @item :reuseaddr @var{reuseaddr-flag}
1993 If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
1994 server process, allow this server to reuse a specific port number (see
1995 @code{:service}) unless another process on this host is already
1996 listening on that port. If @var{reuseaddr-flag} is @code{nil}, there
1997 may be a period of time after the last use of that port (by any
1998 process on the host), where it is not possible to make a new server on
2002 @defun set-network-process-option process option value
2003 This function sets or modifies a network option for network process
2004 @var{process}. See @code{make-network-process} for details of options
2005 @var{option} and their corresponding values @var{value}.
2007 The current setting of an option is available via the
2008 @code{process-contact} function.
2011 @node Network Feature Testing
2012 @subsection Testing Availability of Network Features
2014 To test for the availability of a given network feature, use
2015 @code{featurep} like this:
2018 (featurep 'make-network-process '(@var{keyword} @var{value}))
2022 The result of the first form is @code{t} if it works to specify
2023 @var{keyword} with value @var{value} in @code{make-network-process}.
2024 The result of the second form is @code{t} if @var{keyword} is
2025 supported by @code{make-network-process}. Here are some of the
2026 @var{keyword}---@var{value} pairs you can test in
2031 Non-@code{nil} if non-blocking connect is supported.
2032 @item (:type datagram)
2033 Non-@code{nil} if datagrams are supported.
2034 @item (:family local)
2035 Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported.
2036 @item (:family ipv6)
2037 Non-@code{nil} if IPv6 is supported.
2039 Non-@code{nil} if the system can select the port for a server.
2042 To test for the availability of a given network option, use
2043 @code{featurep} like this:
2046 (featurep 'make-network-process '@var{keyword})
2050 Here are some of the options you can test in this way.
2061 That particular network option is supported by
2062 @code{make-network-process} and @code{set-network-process-option}.
2066 @section Misc Network Facilities
2068 These additional functions are useful for creating and operating
2069 on network connections. Note that they are supported only on some
2072 @defun network-interface-list
2073 This function returns a list describing the network interfaces
2074 of the machine you are using. The value is an alist whose
2075 elements have the form @code{(@var{name} . @var{address})}.
2076 @var{address} has the same form as the @var{local-address}
2077 and @var{remote-address} arguments to @code{make-network-process}.
2080 @defun network-interface-info ifname
2081 This function returns information about the network interface named
2082 @var{ifname}. The value is a list of the form
2083 @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
2087 The Internet protocol address.
2089 The broadcast address.
2093 The layer 2 address (Ethernet MAC address, for instance).
2095 The current flags of the interface.
2099 @defun format-network-address address &optional omit-port
2100 This function converts the Lisp representation of a network address to
2103 A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]}
2104 represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port
2105 number @var{p}. @code{format-network-address} converts that to the
2106 string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
2108 A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e}
2109 @var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along
2110 with a port number. @code{format-network-address} converts that to
2112 @code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}.
2114 If the vector does not include the port number, @var{p}, or if
2115 @var{omit-port} is non-@code{nil}, the result does not include the
2116 @code{:@var{p}} suffix.
2120 @section Communicating with Serial Ports
2121 @cindex @file{/dev/tty}
2124 Emacs can communicate with serial ports. For interactive use,
2125 @kbd{M-x serial-term} opens a terminal window. In a Lisp program,
2126 @code{make-serial-process} creates a process object.
2128 The serial port can be configured at run-time, without having to
2129 close and re-open it. The function @code{serial-process-configure}
2130 lets you change the speed, bytesize, and other parameters. In a
2131 terminal window created by @code{serial-term}, you can click on the
2132 mode line for configuration.
2134 A serial connection is represented by a process object which can be
2135 used similar to a subprocess or network process. You can send and
2136 receive data and configure the serial port. A serial process object
2137 has no process ID, and you can't send signals to it.
2138 @code{delete-process} on the process object or @code{kill-buffer} on
2139 the process buffer close the connection, but this does not affect the
2140 device connected to the serial port.
2142 The function @code{process-type} returns the symbol @code{serial}
2143 for a process object representing a serial port.
2145 Serial ports are available on GNU/Linux, Unix, and Windows systems.
2147 @defun serial-term port speed
2148 Start a terminal-emulator for a serial port in a new buffer.
2149 @var{port} is the path or name of the serial port. For example, this
2150 could be @file{/dev/ttyS0} on Unix. On Windows, this could be
2151 @file{COM1}, or @file{\\.\COM10} (double the backslashes in strings).
2153 @var{speed} is the speed of the serial port in bits per second. 9600
2154 is a common value. The buffer is in Term mode; see @code{term-mode}
2155 for the commands to use in that buffer. You can change the speed and
2156 the configuration in the mode line menu. @end defun
2158 @defun make-serial-process &rest args
2159 @code{make-serial-process} creates a process and a buffer. Arguments
2160 are specified as keyword/argument pairs. The following arguments are
2165 @var{port} (mandatory) is the path or name of the serial port.
2166 For example, this could be @file{/dev/ttyS0} on Unix. On Windows,
2167 this could be @file{COM1}, or @file{\\.\COM10} for ports higher than
2168 @file{COM9} (double the backslashes in strings).
2171 @var{speed} (mandatory) is handled by @code{serial-process-configure},
2172 which is called by @code{make-serial-process}.
2175 @var{name} is the name of the process. If @var{name} is not given, the
2176 value of @var{port} is used.
2178 @item :buffer buffer
2179 @var{buffer} is the buffer (or buffer-name) to associate with the
2180 process. Process output goes at the end of that buffer, unless you
2181 specify an output stream or filter function to handle the output. If
2182 @var{buffer} is not given, the value of @var{name} is used.
2184 @item :coding coding
2185 If @var{coding} is a symbol, it specifies the coding system used for
2186 both reading and writing for this process. If @var{coding} is a cons
2187 @code{(decoding . encoding)}, @var{decoding} is used for reading, and
2188 @var{encoding} is used for writing.
2191 When exiting Emacs, query the user if @var{bool} is @code{nil} and the
2192 process is running. If @var{bool} is not given, query before exiting.
2195 Start process in the @code{stopped} state if @var{bool} is
2196 non-@code{nil}. In the stopped state, a serial process does not
2197 accept incoming data, but you can send outgoing data. The stopped
2198 state is cleared by @code{continue-process} and set by
2199 @code{stop-process}.
2201 @item :filter filter
2202 Install @var{filter} as the process filter.
2204 @item :sentinel sentinel
2205 Install @var{sentinel} as the process sentinel.
2208 Install @var{plist} as the initial plist of the process.
2215 These arguments are handled by @code{serial-process-configure}, which
2216 is called by @code{make-serial-process}.
2219 The original argument list, possibly modified by later configuration,
2220 is available via the function @code{process-contact}.
2225 (make-serial-process :port "/dev/ttyS0" :speed 9600)
2227 (make-serial-process :port "COM1" :speed 115200 :stopbits 2)
2229 (make-serial-process :port "\\\\.\\COM13" :speed 1200 :bytesize 7 :parity 'odd)
2231 (make-serial-process :port "/dev/tty.BlueConsole-SPP-1" :speed nil)
2235 @defun serial-process-configure &rest args
2242 Configure a serial port. Arguments are specified as keyword/argument
2243 pairs. Attributes that are not given are re-initialized from the
2244 process's current configuration (available via the function
2245 @code{process-contact}) or set to reasonable default values. The
2246 following arguments are defined:
2249 @item :process process
2251 @itemx :buffer buffer
2253 Any of these arguments can be given to identify the process that is to
2254 be configured. If none of these arguments is given, the current
2255 buffer's process is used.
2257 @item :speed @var{speed}
2258 @var{speed} is the speed of the serial port in bits per second, also
2259 called baud rate. Any value can be given for @var{speed}, but most
2260 serial ports work only at a few defined values between 1200 and
2261 115200, with 9600 being the most common value. If @var{speed} is
2262 @code{nil}, the serial port is not configured any further, i.e., all
2263 other arguments are ignored. This may be useful for special serial
2264 ports such as Bluetooth-to-serial converters which can only be
2265 configured through AT commands. A value of @code{nil} for @var{speed}
2266 can be used only when passed through @code{make-serial-process} or
2269 @item :bytesize @var{bytesize}
2270 @var{bytesize} is the number of bits per byte, which can be 7 or 8.
2271 If @var{bytesize} is not given or @code{nil}, a value of 8 is used.
2273 @item :parity @var{parity}
2274 @var{parity} can be @code{nil} (don't use parity), the symbol
2275 @code{odd} (use odd parity), or the symbol @code{even} (use even
2276 parity). If @var{parity} is not given, no parity is used.
2278 @item :stopbits @var{stopbits}
2279 @var{stopbits} is the number of stopbits used to terminate a byte
2280 transmission. @var{stopbits} can be 1 or 2. If @var{stopbits} is not
2281 given or @code{nil}, 1 stopbit is used.
2283 @item :flowcontrol @var{flowcontrol}
2284 @var{flowcontrol} determines the type of flowcontrol to be used, which
2285 is either @code{nil} (don't use flowcontrol), the symbol @code{hw}
2286 (use RTS/CTS hardware flowcontrol), or the symbol @code{sw} (use
2287 XON/XOFF software flowcontrol). If @var{flowcontrol} is not given, no
2288 flowcontrol is used.
2291 @code{serial-process-configure} is called by @code{make-serial-process} for the
2292 initial configuration of the serial port.
2297 (serial-process-configure :process "/dev/ttyS0" :speed 1200)
2299 (serial-process-configure :buffer "COM1" :stopbits 1 :parity 'odd :flowcontrol 'hw)
2301 (serial-process-configure :port "\\\\.\\COM13" :bytesize 7)
2306 @section Packing and Unpacking Byte Arrays
2307 @cindex byte packing and unpacking
2309 This section describes how to pack and unpack arrays of bytes,
2310 usually for binary network protocols. These functions convert byte arrays
2311 to alists, and vice versa. The byte array can be represented as a
2312 unibyte string or as a vector of integers, while the alist associates
2313 symbols either with fixed-size objects or with recursive sub-alists.
2316 @cindex deserializing
2319 Conversion from byte arrays to nested alists is also known as
2320 @dfn{deserializing} or @dfn{unpacking}, while going in the opposite
2321 direction is also known as @dfn{serializing} or @dfn{packing}.
2324 * Bindat Spec:: Describing data layout.
2325 * Bindat Functions:: Doing the unpacking and packing.
2326 * Bindat Examples:: Samples of what bindat.el can do for you!
2330 @subsection Describing Data Layout
2332 To control unpacking and packing, you write a @dfn{data layout
2333 specification}, a special nested list describing named and typed
2334 @dfn{fields}. This specification controls length of each field to be
2335 processed, and how to pack or unpack it. We normally keep bindat specs
2336 in variables whose names end in @samp{-bindat-spec}; that kind of name
2337 is automatically recognized as ``risky.''
2341 @cindex little endian
2342 @cindex network byte ordering
2343 A field's @dfn{type} describes the size (in bytes) of the object
2344 that the field represents and, in the case of multibyte fields, how
2345 the bytes are ordered within the field. The two possible orderings
2346 are ``big endian'' (also known as ``network byte ordering'') and
2347 ``little endian.'' For instance, the number @code{#x23cd} (decimal
2348 9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
2349 and in little endian, @code{#xcd} @code{#x23}. Here are the possible
2355 Unsigned byte, with length 1.
2360 Unsigned integer in network byte order, with length 2.
2363 Unsigned integer in network byte order, with length 3.
2368 Unsigned integer in network byte order, with length 4.
2369 Note: These values may be limited by Emacs' integer implementation limits.
2374 Unsigned integer in little endian order, with length 2, 3 and 4, respectively.
2377 String of length @var{len}.
2379 @item strz @var{len}
2380 Zero-terminated string, in a fixed-size field with length @var{len}.
2382 @item vec @var{len} [@var{type}]
2383 Vector of @var{len} elements of type @var{type}, or bytes if not
2384 @var{type} is specified.
2385 The @var{type} is any of the simple types above, or another vector
2386 specified as a list @code{(vec @var{len} [@var{type}])}.
2389 Four-byte vector representing an Internet address. For example:
2390 @code{[127 0 0 1]} for localhost.
2392 @item bits @var{len}
2393 List of set bits in @var{len} bytes. The bytes are taken in big
2394 endian order and the bits are numbered starting with @code{8 *
2395 @var{len} @minus{} 1} and ending with zero. For example: @code{bits
2396 2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and
2397 @code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}.
2399 @item (eval @var{form})
2400 @var{form} is a Lisp expression evaluated at the moment the field is
2401 unpacked or packed. The result of the evaluation should be one of the
2402 above-listed type specifications.
2405 For a fixed-size field, the length @var{len} is given as an integer
2406 specifying the number of bytes in the field.
2408 When the length of a field is not fixed, it typically depends on the
2409 value of a preceding field. In this case, the length @var{len} can be
2410 given either as a list @code{(@var{name} ...)} identifying a
2411 @dfn{field name} in the format specified for @code{bindat-get-field}
2412 below, or by an expression @code{(eval @var{form})} where @var{form}
2413 should evaluate to an integer, specifying the field length.
2415 A field specification generally has the form @code{([@var{name}]
2416 @var{handler})}. The square braces indicate that @var{name} is
2417 optional. (Don't use names that are symbols meaningful as type
2418 specifications (above) or handler specifications (below), since that
2419 would be ambiguous.) @var{name} can be a symbol or the expression
2420 @code{(eval @var{form})}, in which case @var{form} should evaluate to
2423 @var{handler} describes how to unpack or pack the field and can be one
2428 Unpack/pack this field according to the type specification @var{type}.
2430 @item eval @var{form}
2431 Evaluate @var{form}, a Lisp expression, for side-effect only. If the
2432 field name is specified, the value is bound to that field name.
2434 @item fill @var{len}
2435 Skip @var{len} bytes. In packing, this leaves them unchanged,
2436 which normally means they remain zero. In unpacking, this means
2439 @item align @var{len}
2440 Skip to the next multiple of @var{len} bytes.
2442 @item struct @var{spec-name}
2443 Process @var{spec-name} as a sub-specification. This describes a
2444 structure nested within another structure.
2446 @item union @var{form} (@var{tag} @var{spec})@dots{}
2447 @c ??? I don't see how one would actually use this.
2448 @c ??? what kind of expression would be useful for @var{form}?
2449 Evaluate @var{form}, a Lisp expression, find the first @var{tag}
2450 that matches it, and process its associated data layout specification
2451 @var{spec}. Matching can occur in one of three ways:
2455 If a @var{tag} has the form @code{(eval @var{expr})}, evaluate
2456 @var{expr} with the variable @code{tag} dynamically bound to the value
2457 of @var{form}. A non-@code{nil} result indicates a match.
2460 @var{tag} matches if it is @code{equal} to the value of @var{form}.
2463 @var{tag} matches unconditionally if it is @code{t}.
2466 @item repeat @var{count} @var{field-specs}@dots{}
2467 Process the @var{field-specs} recursively, in order, then repeat
2468 starting from the first one, processing all the specs @var{count}
2469 times overall. The @var{count} is given using the same formats as a
2470 field length---if an @code{eval} form is used, it is evaluated just once.
2471 For correct operation, each spec in @var{field-specs} must include a name.
2474 For the @code{(eval @var{form})} forms used in a bindat specification,
2475 the @var{form} can access and update these dynamically bound variables
2480 Value of the last field processed.
2483 The data as a byte array.
2486 Current index (within @code{bindat-raw}) for unpacking or packing.
2489 The alist containing the structured data that have been unpacked so
2490 far, or the entire structure being packed. You can use
2491 @code{bindat-get-field} to access specific fields of this structure.
2495 Inside a @code{repeat} block, these contain the maximum number of
2496 repetitions (as specified by the @var{count} parameter), and the
2497 current repetition number (counting from 0). Setting @code{count} to
2498 zero will terminate the inner-most repeat block after the current
2499 repetition has completed.
2502 @node Bindat Functions
2503 @subsection Functions to Unpack and Pack Bytes
2505 In the following documentation, @var{spec} refers to a data layout
2506 specification, @code{bindat-raw} to a byte array, and @var{struct} to an
2507 alist representing unpacked field data.
2509 @defun bindat-unpack spec bindat-raw &optional bindat-idx
2510 This function unpacks data from the unibyte string or byte
2511 array @code{bindat-raw}
2512 according to @var{spec}. Normally this starts unpacking at the
2513 beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it
2514 specifies a zero-based starting position to use instead.
2516 The value is an alist or nested alist in which each element describes
2520 @defun bindat-get-field struct &rest name
2521 This function selects a field's data from the nested alist
2522 @var{struct}. Usually @var{struct} was returned by
2523 @code{bindat-unpack}. If @var{name} corresponds to just one argument,
2524 that means to extract a top-level field value. Multiple @var{name}
2525 arguments specify repeated lookup of sub-structures. An integer name
2526 acts as an array index.
2528 For example, if @var{name} is @code{(a b 2 c)}, that means to find
2529 field @code{c} in the third element of subfield @code{b} of field
2530 @code{a}. (This corresponds to @code{struct.a.b[2].c} in C.)
2533 Although packing and unpacking operations change the organization of
2534 data (in memory), they preserve the data's @dfn{total length}, which is
2535 the sum of all the fields' lengths, in bytes. This value is not
2536 generally inherent in either the specification or alist alone; instead,
2537 both pieces of information contribute to its calculation. Likewise, the
2538 length of a string or array being unpacked may be longer than the data's
2539 total length as described by the specification.
2541 @defun bindat-length spec struct
2542 This function returns the total length of the data in @var{struct},
2543 according to @var{spec}.
2546 @defun bindat-pack spec struct &optional bindat-raw bindat-idx
2547 This function returns a byte array packed according to @var{spec} from
2548 the data in the alist @var{struct}. Normally it creates and fills a
2549 new byte array starting at the beginning. However, if @var{bindat-raw}
2550 is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to
2551 pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting
2552 offset for packing into @code{bindat-raw}.
2554 When pre-allocating, you should make sure @code{(length @var{bindat-raw})}
2555 meets or exceeds the total length to avoid an out-of-range error.
2558 @defun bindat-ip-to-string ip
2559 Convert the Internet address vector @var{ip} to a string in the usual
2563 (bindat-ip-to-string [127 0 0 1])
2564 @result{} "127.0.0.1"
2568 @node Bindat Examples
2569 @subsection Examples of Byte Unpacking and Packing
2571 Here is a complete example of byte unpacking and packing:
2574 (defvar fcookie-index-spec
2582 (:offset repeat (:count)
2584 "Description of a fortune cookie index file's contents.")
2586 (defun fcookie (cookies &optional index)
2587 "Display a random fortune cookie from file COOKIES.
2588 Optional second arg INDEX specifies the associated index
2589 filename, which is by default constructed by appending
2590 \".dat\" to COOKIES. Display cookie text in possibly
2591 new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
2592 is COOKIES without the directory part."
2593 (interactive "fCookies file: ")
2594 (let* ((info (with-temp-buffer
2595 (insert-file-contents-literally
2596 (or index (concat cookies ".dat")))
2597 (bindat-unpack fcookie-index-spec
2599 (sel (random (bindat-get-field info :count)))
2600 (beg (cdar (bindat-get-field info :offset sel)))
2601 (end (or (cdar (bindat-get-field info
2603 (nth 7 (file-attributes cookies)))))
2606 (format "*Fortune Cookie: %s*"
2607 (file-name-nondirectory cookies))))
2609 (insert-file-contents-literally
2610 cookies nil beg (- end 3))))
2612 (defun fcookie-create-index (cookies &optional index delim)
2613 "Scan file COOKIES, and write out its index file.
2614 Optional second arg INDEX specifies the index filename,
2615 which is by default constructed by appending \".dat\" to
2616 COOKIES. Optional third arg DELIM specifies the unibyte
2617 character which, when found on a line of its own in
2618 COOKIES, indicates the border between entries."
2619 (interactive "fCookies file: ")
2620 (setq delim (or delim ?%))
2621 (let ((delim-line (format "\n%c\n" delim))
2624 min p q len offsets)
2625 (unless (= 3 (string-bytes delim-line))
2626 (error "Delimiter cannot be represented in one byte"))
2628 (insert-file-contents-literally cookies)
2629 (while (and (setq p (point))
2630 (search-forward delim-line (point-max) t)
2631 (setq len (- (point) 3 p)))
2632 (setq count (1+ count)
2634 min (min (or min max) len)
2635 offsets (cons (1- p) offsets))))
2637 (set-buffer-multibyte nil)
2647 (:offset . ,(mapcar (lambda (o)
2648 (list (cons :foo o)))
2649 (nreverse offsets))))))
2650 (let ((coding-system-for-write 'raw-text-unix))
2651 (write-file (or index (concat cookies ".dat")))))))
2654 Following is an example of defining and unpacking a complex structure.
2655 Consider the following C structures:
2659 unsigned long dest_ip;
2660 unsigned long src_ip;
2661 unsigned short dest_port;
2662 unsigned short src_port;
2667 unsigned char opcode;
2668 unsigned short length; /* In network byte order */
2669 unsigned char id[8]; /* null-terminated string */
2670 unsigned char data[/* (length + 3) & ~3 */];
2674 struct header header;
2675 unsigned long counters[2]; /* In little endian order */
2676 unsigned char items;
2677 unsigned char filler[3];
2678 struct data item[/* items */];
2683 The corresponding data layout specification:
2695 (length u16) ;; network byte order
2701 '((header struct header-spec)
2702 (counters vec 2 u32r) ;; little endian order
2705 (item repeat (items)
2706 (struct data-spec))))
2709 A binary data representation:
2713 [ 192 168 1 100 192 168 1 101 01 28 21 32
2714 160 134 1 0 5 1 0 0 2 0 0 0
2715 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
2716 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
2719 The corresponding decoded structure:
2722 (setq decoded (bindat-unpack packet-spec binary-data))
2725 (dest-ip . [192 168 1 100])
2726 (src-ip . [192 168 1 101])
2729 (counters . [100000 261])
2731 (item ((data . [1 2 3 4 5])
2736 ((data . [6 7 8 9 10 11 12])
2743 Fetching data from this structure:
2746 (bindat-get-field decoded 'item 1 'id)
2751 arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a