annotate lispref/processes.texi @ 82370:53488343dec3

*** empty log message ***
author Jay Belanger <jay.p.belanger@gmail.com>
date Tue, 14 Aug 2007 05:34:10 +0000
parents 38bfa1de0aca
children f59dca8510d0 f55f9811f5d7
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
75250
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 75050
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 75050
diff changeset
4 @c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/processes
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
7 @node Processes, Display, Abbrevs, Top
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex child process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 @cindex parent process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 @cindex subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 @cindex process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 In the terminology of operating systems, a @dfn{process} is a space in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 which a program can execute. Emacs runs in a process. Emacs Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 programs can invoke other programs in processes of their own. These are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 called @dfn{subprocesses} or @dfn{child processes} of the Emacs process,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 which is their @dfn{parent process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 depending on how it is created. When you create a synchronous
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 subprocess, the Lisp program waits for the subprocess to terminate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 before continuing execution. When you create an asynchronous
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 subprocess, it can run in parallel with the Lisp program. This kind of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 subprocess is represented within Emacs by a Lisp object which is also
71957
61cb5aae3bc3 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71697
diff changeset
26 called a ``process.'' Lisp programs can use this object to communicate
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 with the subprocess or to control it. For example, you can send
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 signals, obtain status information, receive output from the process, or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 send input to it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 @defun processp object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 This function returns @code{t} if @var{object} is a process,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 @code{nil} otherwise.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 * Subprocess Creation:: Functions that start subprocesses.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
38 * Shell Arguments:: Quoting an argument to pass it to a shell.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 * Synchronous Processes:: Details of using synchronous subprocesses.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 * Asynchronous Processes:: Starting up an asynchronous subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 * Deleting Processes:: Eliminating an asynchronous subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 * Process Information:: Accessing run-status and other attributes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 * Input to Processes:: Sending input to an asynchronous subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 * Signals to Processes:: Stopping, continuing or interrupting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 an asynchronous subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 * Output from Processes:: Collecting output from an asynchronous subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 * Sentinels:: Sentinels run when process run-status changes.
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
48 * Query Before Exit:: Whether to query if exiting will kill a process.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 * Transaction Queues:: Transaction-based communication with subprocesses.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
50 * Network:: Opening network connections.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
51 * Network Servers:: Network servers let Emacs accept net connections.
62245
a9109def6d90 (Processes): Add menu description.
Lute Kamstra <lute@gnu.org>
parents: 62230
diff changeset
52 * Datagrams:: UDP network connections.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
53 * Low-Level Network:: Lower-level but more general function
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
54 to create connections and servers.
64913
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
55 * Misc Network:: Additional relevant functions for network connections.
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
56 * Byte Packing:: Using bindat to pack and unpack binary data.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 @node Subprocess Creation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 @section Functions that Create Subprocesses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 There are three functions that create a new subprocess in which to run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 a program. One of them, @code{start-process}, creates an asynchronous
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 process and returns a process object (@pxref{Asynchronous Processes}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 The other two, @code{call-process} and @code{call-process-region},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 create a synchronous process and do not return a process object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 (@pxref{Synchronous Processes}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
69 Synchronous and asynchronous processes are explained in the following
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 sections. Since the three functions are all called in a similar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 fashion, their common arguments are described here.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 @cindex execute program
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 @cindex @code{PATH} environment variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 @cindex @code{HOME} environment variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 In all cases, the function's @var{program} argument specifies the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 program to be run. An error is signaled if the file is not found or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 cannot be executed. If the file name is relative, the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 @code{exec-path} contains a list of directories to search. Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 initializes @code{exec-path} when it starts up, based on the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81 the environment variable @code{PATH}. The standard file name
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
82 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
83 usual in @code{exec-path}, but environment variable substitutions
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 (@samp{$HOME}, etc.) are not recognized; use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 @code{substitute-in-file-name} to perform them (@pxref{File Name
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
86 Expansion}). @code{nil} in this list refers to
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
87 @code{default-directory}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88
51922
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
89 Executing a program can also try adding suffixes to the specified
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
90 name:
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
91
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
92 @defvar exec-suffixes
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
93 This variable is a list of suffixes (strings) to try adding to the
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
94 specified program file name. The list should include @code{""} if you
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
95 want the name to be tried exactly as specified. The default value is
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
96 system-dependent.
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
97 @end defvar
97cfe6cd3e4f (Subprocess Creation): Add exec-suffixes.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
98
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
99 @strong{Please note:} The argument @var{program} contains only the
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
100 name of the program; it may not contain any command-line arguments. You
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
101 must use @var{args} to provide those.
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
102
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 Each of the subprocess-creating functions has a @var{buffer-or-name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 argument which specifies where the standard output from the program will
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
105 go. It should be a buffer or a buffer name; if it is a buffer name,
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
106 that will create the buffer if it does not already exist. It can also
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
107 be @code{nil}, which says to discard the output unless a filter function
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
108 handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
109 Normally, you should avoid having multiple processes send output to the
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
110 same buffer because their output would be intermixed randomly.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 @cindex program arguments
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 All three of the subprocess-creating functions have a @code{&rest}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 argument, @var{args}. The @var{args} must all be strings, and they are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 supplied to @var{program} as separate command line arguments. Wildcard
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
116 characters and other shell constructs have no special meanings in these
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
117 strings, since the strings are passed directly to the specified program.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 The subprocess gets its current directory from the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 @code{default-directory} (@pxref{File Name Expansion}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @cindex environment variables, subprocesses
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
123 The subprocess inherits its environment from Emacs, but you can
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 specify overrides for it with @code{process-environment}. @xref{System
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 Environment}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
127 @defvar exec-directory
17611
1b2afa6391ca (exec-directory): Wakeup no longer exists, so use movemail as example.
Richard M. Stallman <rms@gnu.org>
parents: 16664
diff changeset
128 @pindex movemail
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
129 The value of this variable is a string, the name of a directory that
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
130 contains programs that come with GNU Emacs, programs intended for Emacs
17611
1b2afa6391ca (exec-directory): Wakeup no longer exists, so use movemail as example.
Richard M. Stallman <rms@gnu.org>
parents: 16664
diff changeset
131 to invoke. The program @code{movemail} is an example of such a program;
1b2afa6391ca (exec-directory): Wakeup no longer exists, so use movemail as example.
Richard M. Stallman <rms@gnu.org>
parents: 16664
diff changeset
132 Rmail uses it to fetch new mail from an inbox.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 @defopt exec-path
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 The value of this variable is a list of directories to search for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 programs to run in subprocesses. Each element is either the name of a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 directory (i.e., a string), or @code{nil}, which stands for the default
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 directory (which is the value of @code{default-directory}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 @cindex program directories
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 The value of @code{exec-path} is used by @code{call-process} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 @code{start-process} when the @var{program} argument is not an absolute
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 file name.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
147 @node Shell Arguments
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
148 @section Shell Arguments
76993
55c9ef5f1559 Improve index entries.
Richard M. Stallman <rms@gnu.org>
parents: 76922
diff changeset
149 @cindex arguments for shell commands
55c9ef5f1559 Improve index entries.
Richard M. Stallman <rms@gnu.org>
parents: 76922
diff changeset
150 @cindex shell command arguments
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
151
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
152 Lisp programs sometimes need to run a shell and give it a command
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
153 that contains file names that were specified by the user. These
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
154 programs ought to be able to support any valid file name. But the shell
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
155 gives special treatment to certain characters, and if these characters
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
156 occur in the file name, they will confuse the shell. To handle these
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
157 characters, use the function @code{shell-quote-argument}:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
158
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
159 @defun shell-quote-argument argument
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
160 This function returns a string which represents, in shell syntax,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
161 an argument whose actual contents are @var{argument}. It should
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
162 work reliably to concatenate the return value into a shell command
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
163 and then pass it to a shell for execution.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
164
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
165 Precisely what this function does depends on your operating system. The
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
166 function is designed to work with the syntax of your system's standard
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
167 shell; if you use an unusual shell, you will need to redefine this
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
168 function.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
169
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
170 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
171 ;; @r{This example shows the behavior on GNU and Unix systems.}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
172 (shell-quote-argument "foo > bar")
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
173 @result{} "foo\\ \\>\\ bar"
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
174
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
175 ;; @r{This example shows the behavior on MS-DOS and MS-Windows.}
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
176 (shell-quote-argument "foo > bar")
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
177 @result{} "\"foo > bar\""
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
178 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
179
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
180 Here's an example of using @code{shell-quote-argument} to construct
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
181 a shell command:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
182
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
183 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
184 (concat "diff -c "
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
185 (shell-quote-argument oldfile)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
186 " "
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
187 (shell-quote-argument newfile))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
188 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
189 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
190
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 @node Synchronous Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 @section Creating a Synchronous Process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 @cindex synchronous subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 After a @dfn{synchronous process} is created, Emacs waits for the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
196 process to terminate before continuing. Starting Dired on GNU or
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
197 Unix@footnote{On other systems, Emacs uses a Lisp emulation of
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
198 @code{ls}; see @ref{Contents of Directories}.} is an example of this: it
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
199 runs @code{ls} in a synchronous process, then modifies the output
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
200 slightly. Because the process is synchronous, the entire directory
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
201 listing arrives in the buffer before Emacs tries to do anything with it.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 While Emacs waits for the synchronous subprocess to terminate, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 the subprocess with a @code{SIGINT} signal; but it waits until the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 subprocess actually terminates before quitting. If during that time the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 user types another @kbd{C-g}, that kills the subprocess instantly with
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
208 @code{SIGKILL} and quits immediately (except on MS-DOS, where killing
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
209 other processes doesn't work). @xref{Quitting}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
211 The synchronous subprocess functions return an indication of how the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
212 process terminated.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
213
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
214 The output from a synchronous subprocess is generally decoded using a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
215 coding system, much like text read from a file. The input sent to a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
216 subprocess by @code{call-process-region} is encoded using a coding
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
217 system, much like text written into a file. @xref{Coding Systems}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
219 @defun call-process program &optional infile destination display &rest args
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 This function calls @var{program} in a separate process and waits for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 it to finish.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 The standard input for the process comes from file @var{infile} if
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
224 @var{infile} is not @code{nil}, and from the null device otherwise.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
225 The argument @var{destination} says where to put the process output.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
226 Here are the possibilities:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
227
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
228 @table @asis
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
229 @item a buffer
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
230 Insert the output in that buffer, before point. This includes both the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
231 standard output stream and the standard error stream of the process.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
232
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
233 @item a string
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
234 Insert the output in a buffer with that name, before point.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
235
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
236 @item @code{t}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
237 Insert the output in the current buffer, before point.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
238
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
239 @item @code{nil}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
240 Discard the output.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
242 @item 0
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
243 Discard the output, and return @code{nil} immediately without waiting
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
244 for the subprocess to finish.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
245
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
246 In this case, the process is not truly synchronous, since it can run in
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
247 parallel with Emacs; but you can think of it as synchronous in that
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
248 Emacs is essentially finished with the subprocess as soon as this
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
249 function returns.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
250
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
251 MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
252 work there.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
253
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
254 @item @code{(@var{real-destination} @var{error-destination})}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
255 Keep the standard output stream separate from the standard error stream;
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
256 deal with the ordinary output as specified by @var{real-destination},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
257 and dispose of the error output according to @var{error-destination}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
258 If @var{error-destination} is @code{nil}, that means to discard the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
259 error output, @code{t} means mix it with the ordinary output, and a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
260 string specifies a file name to redirect error output into.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
261
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
262 You can't directly specify a buffer to put the error output in; that is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
263 too difficult to implement. But you can achieve this result by sending
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
264 the error output to a temporary file and then inserting the file into a
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
265 buffer.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
266 @end table
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
269 the buffer as output is inserted. (However, if the coding system chosen
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
270 for decoding output is @code{undecided}, meaning deduce the encoding
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
271 from the actual data, then redisplay sometimes cannot continue once
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
272 non-@acronym{ASCII} characters are encountered. There are fundamental
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
273 reasons why it is hard to fix this; see @ref{Output from Processes}.)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
274
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
275 Otherwise the function @code{call-process} does no redisplay, and the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
276 results become visible on the screen only when Emacs redisplays that
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
277 buffer in the normal course of events.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 The remaining arguments, @var{args}, are strings that specify command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 line arguments for the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 The value returned by @code{call-process} (unless you told it not to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 wait) indicates the reason for process termination. A number gives the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 exit status of the subprocess; 0 means success, and any other value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 means failure. If the process terminated with a signal,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 @code{call-process} returns a string describing the signal.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 In the examples below, the buffer @samp{foo} is current.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 (call-process "pwd" nil t)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
293 @result{} 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 /usr/user/lewis/manual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
302 @result{} 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 ---------- Buffer: bar ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 ---------- Buffer: bar ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
311 Here is a good example of the use of @code{call-process}, which used to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
312 be found in the definition of @code{insert-directory}:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
316 (call-process insert-directory-program nil t nil @var{switches}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 (if full-directory-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 (concat (file-name-as-directory file) ".")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 file))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323
57670
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
324 @defun process-file program &optional infile buffer display &rest args
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
325 This function processes files synchronously in a separate process. It
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
326 is similar to @code{call-process} but may invoke a file handler based
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
327 on the value of the variable @code{default-directory}. The current
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
328 working directory of the subprocess is @code{default-directory}.
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
329
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
330 The arguments are handled in almost the same way as for
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
331 @code{call-process}, with the following differences:
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
332
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
333 Some file handlers may not support all combinations and forms of the
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
334 arguments @var{infile}, @var{buffer}, and @var{display}. For example,
58500
6f8c0631e5aa (Synchronous Processes): Grammar fix.
Richard M. Stallman <rms@gnu.org>
parents: 58405
diff changeset
335 some file handlers might behave as if @var{display} were @code{nil},
57670
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
336 regardless of the value actually passed. As another example, some
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
337 file handlers might not support separating standard output and error
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
338 output by way of the @var{buffer} argument.
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
339
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
340 If a file handler is invoked, it determines the program to run based
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
341 on the first argument @var{program}. For instance, consider that a
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
342 handler for remote files is invoked. Then the path that is used for
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
343 searching the program might be different than @code{exec-path}.
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
344
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
345 The second argument @var{infile} may invoke a file handler. The file
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
346 handler could be different from the handler chosen for the
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
347 @code{process-file} function itself. (For example,
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
348 @code{default-directory} could be on a remote host, whereas
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
349 @var{infile} is on another remote host. Or @code{default-directory}
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
350 could be non-special, whereas @var{infile} is on a remote host.)
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
351
77123
4d7a5d9bbe76 improve breaks in 8.5x11
Karl Berry <karl@gnu.org>
parents: 76993
diff changeset
352 If @var{buffer} is a list of the form @code{(@var{real-destination}
57670
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
353 @var{error-destination})}, and @var{error-destination} names a file,
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
354 then the same remarks as for @var{infile} apply.
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
355
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
356 The remaining arguments (@var{args}) will be passed to the process
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
357 verbatim. Emacs is not involved in processing file names that are
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
358 present in @var{args}. To avoid confusion, it may be best to avoid
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
359 absolute file names in @var{args}, but rather to specify all file
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
360 names as relative to @code{default-directory}. The function
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
361 @code{file-relative-name} is useful for constructing such relative
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
362 file names.
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
363 @end defun
dd36fc88814a (Synchronous Processes): Document process-file.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56704
diff changeset
364
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
365 @defun call-process-region start end program &optional delete destination display &rest args
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
366 This function sends the text from @var{start} to @var{end} as
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 standard input to a process running @var{program}. It deletes the text
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
368 sent if @var{delete} is non-@code{nil}; this is useful when
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
369 @var{destination} is @code{t}, to insert the output in the current
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
370 buffer in place of the input.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
372 The arguments @var{destination} and @var{display} control what to do
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 with the output from the subprocess, and whether to update the display
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 as it comes in. For details, see the description of
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
375 @code{call-process}, above. If @var{destination} is the integer 0,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @code{call-process-region} discards the output and returns @code{nil}
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
377 immediately, without waiting for the subprocess to finish (this only
27370
70846ee19545 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
378 works if asynchronous subprocesses are supported).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 The remaining arguments, @var{args}, are strings that specify command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 line arguments for the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 The return value of @code{call-process-region} is just like that of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 @code{call-process}: @code{nil} if you told it to return without
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 waiting; otherwise, a number or string which indicates how the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 subprocess terminated.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 In the following example, we use @code{call-process-region} to run the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 @code{cat} utility, with standard input being the first five characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 standard input into its standard output. Since the argument
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
392 @var{destination} is @code{t}, this output is inserted in the current
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 input@point{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 (call-process-region 1 6 "cat" nil t)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
404 @result{} 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 inputinput@point{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 The @code{shell-command-on-region} command uses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 @code{call-process-region} like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
417 (call-process-region
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
418 start end
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 shell-file-name ; @r{Name of program.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 nil ; @r{Do not delete region.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 buffer ; @r{Send output to @code{buffer}.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 nil ; @r{No redisplay during output.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 "-c" command) ; @r{Arguments for the shell.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
428 @defun call-process-shell-command command &optional infile destination display &rest args
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
429 This function executes the shell command @var{command} synchronously
54265
1f7cd275e61f Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 54004
diff changeset
430 in a separate process. The final arguments @var{args} are additional
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
431 arguments to add at the end of @var{command}. The other arguments
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
432 are handled as in @code{call-process}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
433 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
434
82092
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
435 @defun process-file-shell-command command &optional infile destination display &rest args
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
436 This function is like @code{call-process-shell-command}, but uses
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
437 @code{process-file} internally. Depending on @code{default-directory},
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
438 @var{command} can be executed also on remote hosts.
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
439 @end defun
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
440
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
441 @defun shell-command-to-string command
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
442 This function executes @var{command} (a string) as a shell command,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
443 then returns the command's output as a string.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
444 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
445
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @node Asynchronous Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @section Creating an Asynchronous Process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 @cindex asynchronous subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
450 After an @dfn{asynchronous process} is created, Emacs and the subprocess
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
451 both continue running immediately. The process thereafter runs
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
452 in parallel with Emacs, and the two can communicate with each other
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
453 using the functions described in the following sections. However,
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
454 communication is only partially asynchronous: Emacs sends data to the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
455 process only when certain functions are called, and Emacs accepts data
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
456 from the process only when Emacs is waiting for input or for a time
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
457 delay.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
458
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
459 Here we describe how to create an asynchronous process.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @defun start-process name buffer-or-name program &rest args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 This function creates a new asynchronous subprocess and starts the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 program @var{program} running in it. It returns a process object that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 stands for the new subprocess in Lisp. The argument @var{name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 specifies the name for the process object; if a process with this name
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
466 already exists, then @var{name} is modified (by appending @samp{<1>},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
467 etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 associate with the process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 The remaining arguments, @var{args}, are strings that specify command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 line arguments for the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 In the example below, the first process is started and runs (rather,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 sleeps) for 100 seconds. Meanwhile, the second process is started, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 given the name @samp{my-process<1>} for the sake of uniqueness. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 inserts the directory listing at the end of the buffer @samp{foo},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 before the first process finishes. Then it finishes, and a message to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 that effect is inserted in the buffer. Much later, the first process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 finishes, and another message is inserted in the buffer for it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 (start-process "my-process" "foo" "sleep" "100")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 @result{} #<process my-process>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 @result{} #<process my-process<1>>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 total 2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 Process my-process<1> finished
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498 Process my-process finished
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503
81737
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
504 @defun start-file-process name buffer-or-name program &rest args
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
505 Like @code{start-process}, this function starts a new asynchronous
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
506 subprocess running @var{program} in it. The corresponding process
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
507 object is returned.
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
508
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
509 If @code{default-directory} corresponds to a file handler, that
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
510 handler is invoked. @var{program} runs then on a remote host which is
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
511 identified by @code{default-directory}. The local part of
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
512 @code{default-directory} is the working directory of the subprocess.
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
513
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
514 @var{program} and @var{program-args} might be file names. They are not
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
515 objects of file handler invocation.
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
516
82092
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
517 Depending on the implementation of the file handler, it might not be
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
518 possible to apply @code{process-filter} or @code{process-sentinel} to
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
519 the resulting process object (@pxref{Filter Functions}, @pxref{Sentinels}).
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
520
81737
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
521 Some file handlers may not support @code{start-file-process} (for
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
522 example @code{ange-ftp-hook-function}). It returns then @code{nil}.
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
523 @end defun
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
524
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 @defun start-process-shell-command name buffer-or-name command &rest command-args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 This function is like @code{start-process} except that it uses a shell
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 to execute the specified command. The argument @var{command} is a shell
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 command name, and @var{command-args} are the arguments for the shell
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
529 command. The variable @code{shell-file-name} specifies which shell to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
530 use.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
531
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
532 The point of running a program through the shell, rather than directly
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
533 with @code{start-process}, is so that you can employ shell features such
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
534 as wildcards in the arguments. It follows that if you include an
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
535 arbitrary user-specified arguments in the command, you should quote it
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
536 with @code{shell-quote-argument} first, so that any special shell
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
537 characters do @emph{not} have their special shell meanings. @xref{Shell
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
538 Arguments}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540
82092
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
541 @defun start-file-process-shell-command name buffer-or-name command &rest command-args
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
542 This function is like @code{start-process-shell-command}, but uses
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
543 @code{start-file-process} internally. By this, @var{command} can be
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
544 executed also on remote hosts, depending on @code{default-directory}.
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
545 @end defun
38bfa1de0aca * processes.texi (Synchronous Processes): Add
Michael Albinus <michael.albinus@gmx.de>
parents: 81737
diff changeset
546
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @defvar process-connection-type
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 @cindex pipes
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
549 @cindex @acronym{PTY}s
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 This variable controls the type of device used to communicate with
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
551 asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
552 used, when available. Otherwise, pipes are used.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
554 @acronym{PTY}s are usually preferable for processes visible to the user, as
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
556 etc.) to work between the process and its children, whereas pipes do
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
557 not. For subprocesses used for internal purposes by programs, it is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
558 often better to use a pipe, because they are more efficient. In
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
559 addition, the total number of @acronym{PTY}s is limited on many systems and
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
560 it is good not to waste them.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
562 The value of @code{process-connection-type} takes effect when
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 @code{start-process} is called. So you can specify how to communicate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 with one subprocess by binding the variable around the call to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 @code{start-process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 (let ((process-connection-type nil)) ; @r{Use a pipe.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 (start-process @dots{}))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @end smallexample
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
573
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
574 To determine whether a given subprocess actually got a pipe or a
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
575 @acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
576 Information}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @node Deleting Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 @section Deleting Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @cindex deleting processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 @dfn{Deleting a process} disconnects Emacs immediately from the
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
584 subprocess. Processes are deleted automatically after they terminate,
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
585 but not necessarily right away. You can delete a process explicitly
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
586 at any time. If you delete a terminated process explicitly before it
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
587 is deleted automatically, no harm results. Deleting a running
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
588 process sends a signal to terminate it (and its child processes if
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
589 any), and calls the process sentinel if it has one. @xref{Sentinels}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
591 When a process is deleted, the process object itself continues to
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
592 exist as long as other Lisp objects point to it. All the Lisp
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
593 primitives that work on process objects accept deleted processes, but
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
594 those that do I/O or send signals will report an error. The process
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
595 mark continues to point to the same place as before, usually into a
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
596 buffer where output from the process was being inserted.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
598 @defopt delete-exited-processes
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599 This variable controls automatic deletion of processes that have
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 terminated (due to calling @code{exit} or to a signal). If it is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 @code{nil}, then they continue to exist until the user runs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 @code{list-processes}. Otherwise, they are deleted immediately after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 they exit.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
604 @end defopt
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
606 @defun delete-process process
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
607 This function deletes a process, killing it with a @code{SIGKILL}
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
608 signal. The argument may be a process, the name of a process, a
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
609 buffer, or the name of a buffer. (A buffer or buffer-name stands for
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
610 the process that @code{get-buffer-process} returns.) Calling
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
611 @code{delete-process} on a running process terminates it, updates the
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
612 process status, and runs the sentinel (if any) immediately. If the
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
613 process has already terminated, calling @code{delete-process} has no
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
614 effect on its status, or on the running of its sentinel (which will
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
615 happen sooner or later).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 (delete-process "*shell*")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 @node Process Information
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 @section Process Information
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 Several functions return information about processes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 @code{list-processes} is provided for interactive use.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
631 @deffn Command list-processes &optional query-only
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 This command displays a listing of all living processes. In addition,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 it finally deletes any process whose status was @samp{Exited} or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @samp{Signaled}. It returns @code{nil}.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
635
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
636 If @var{query-only} is non-@code{nil} then it lists only processes
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
637 whose query flag is non-@code{nil}. @xref{Query Before Exit}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 @defun process-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 This function returns a list of all processes that have not been deleted.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 (process-list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 @result{} (#<process display-time> #<process shell>)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 @defun get-process name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652 This function returns the process named @var{name}, or @code{nil} if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 there is none. An error is signaled if @var{name} is not a string.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 (get-process "shell")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 @result{} #<process shell>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663 @defun process-command process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664 This function returns the command that was executed to start
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 @var{process}. This is a list of strings, the first string being the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 program executed and the rest of the strings being the arguments that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 were given to the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 (process-command (get-process "shell"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 @result{} ("/bin/csh" "-i")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 @defun process-id process
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
678 This function returns the @acronym{PID} of @var{process}. This is an
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
679 integer that distinguishes the process @var{process} from all other
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 processes running on the same computer at the current time. The
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
681 @acronym{PID} of a process is chosen by the operating system kernel when the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682 process is started and remains constant as long as the process exists.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 @defun process-name process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 This function returns the name of @var{process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 @defun process-status process-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 This function returns the status of @var{process-name} as a symbol.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691 The argument @var{process-name} must be a process, a buffer, a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 process name (string) or a buffer name (string).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 The possible values for an actual subprocess are:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697 @item run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 for a process that is running.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 @item stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700 for a process that is stopped but continuable.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 @item exit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 for a process that has exited.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703 @item signal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 for a process that has received a fatal signal.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 @item open
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 for a network connection that is open.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 @item closed
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 for a network connection that is closed. Once a connection
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 is closed, you cannot reopen it, though you might be able to open
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 a new connection to the same place.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
711 @item connect
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
712 for a non-blocking connection that is waiting to complete.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
713 @item failed
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
714 for a non-blocking connection that has failed to complete.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
715 @item listen
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
716 for a network server that is listening.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 @item nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 if @var{process-name} is not the name of an existing process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 (process-status "shell")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 @result{} run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 (process-status (get-buffer "*shell*"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 @result{} run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @result{} #<process xx<1>>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 (process-status x)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 @result{} exit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 For a network connection, @code{process-status} returns one of the symbols
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 @code{open} or @code{closed}. The latter means that the other side
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740 closed the connection, or Emacs did @code{delete-process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 @defun process-exit-status process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 This function returns the exit status of @var{process} or the signal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 number that killed it. (Use the result of @code{process-status} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 determine which of those it is.) If @var{process} has not yet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 terminated, the value is 0.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
750 @defun process-tty-name process
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
751 This function returns the terminal name that @var{process} is using for
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
752 its communication with Emacs---or @code{nil} if it is using pipes
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
753 instead of a terminal (see @code{process-connection-type} in
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
754 @ref{Asynchronous Processes}).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
755 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
756
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 54916
diff changeset
757 @defun process-coding-system process
53292
5408fe43d709 (Process Information): Add anchor.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
758 @anchor{Coding systems for a subprocess}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
759 This function returns a cons cell describing the coding systems in use
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
760 for decoding output from @var{process} and for encoding input to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
761 @var{process} (@pxref{Coding Systems}). The value has this form:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
762
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
763 @example
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
764 (@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
765 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
766 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
767
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
768 @defun set-process-coding-system process &optional decoding-system encoding-system
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
769 This function specifies the coding systems to use for subsequent output
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
770 from and input to @var{process}. It will use @var{decoding-system} to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
771 decode subprocess output, and @var{encoding-system} to encode subprocess
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
772 input.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
773 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
774
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
775 Every process also has a property list that you can use to store
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
776 miscellaneous values associated with the process.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
777
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
778 @defun process-get process propname
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
779 This function returns the value of the @var{propname} property
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
780 of @var{process}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
781 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
782
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
783 @defun process-put process propname value
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
784 This function sets the value of the @var{propname} property
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
785 of @var{process} to @var{value}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
786 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
787
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
788 @defun process-plist process
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
789 This function returns the process plist of @var{process}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
790 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
791
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
792 @defun set-process-plist process plist
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
793 This function sets the process plist of @var{process} to @var{plist}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
794 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
795
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 @node Input to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 @section Sending Input to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 @cindex process input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 Asynchronous subprocesses receive input when it is sent to them by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 Emacs, which is done with the functions in this section. You must
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 specify the process to send input to, and the input data to send. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 data appears on the ``standard input'' of the subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 Some operating systems have limited space for buffered input in a
63560
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
806 @acronym{PTY}. On these systems, Emacs sends an @acronym{EOF}
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
807 periodically amidst the other characters, to force them through. For
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
808 most programs, these @acronym{EOF}s do no harm.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
810 Subprocess input is normally encoded using a coding system before the
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
811 subprocess receives it, much like text written into a file. You can use
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
812 @code{set-process-coding-system} to specify which coding system to use
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
813 (@pxref{Process Information}). Otherwise, the coding system comes from
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
814 @code{coding-system-for-write}, if that is non-@code{nil}; or else from
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
815 the defaulting mechanism (@pxref{Default Coding Systems}).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
816
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
817 Sometimes the system is unable to accept input for that process,
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
818 because the input buffer is full. When this happens, the send functions
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
819 wait a short while, accepting output from subprocesses, and then try
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
820 again. This gives the subprocess a chance to read more of its pending
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
821 input and make space in the buffer. It also allows filters, sentinels
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
822 and timers to run---so take account of that in writing your code.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
823
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
824 In these functions, the @var{process} argument can be a process or
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
825 the name of a process, or a buffer or buffer name (which stands
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
826 for a process via @code{get-buffer-process}). @code{nil} means
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
827 the current buffer's process.
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
828
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
829 @defun process-send-string process string
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
830 This function sends @var{process} the contents of @var{string} as
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
831 standard input. If it is @code{nil}, the current buffer's process is used.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 The function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 (process-send-string "shell<1>" "ls\n")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 ---------- Buffer: *shell* ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844 ...
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 introduction.texi syntax-tables.texi~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 introduction.texi~ text.texi
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 introduction.txt text.texi~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 ...
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 ---------- Buffer: *shell* ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
854 @defun process-send-region process start end
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 This function sends the text in the region defined by @var{start} and
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
856 @var{end} as standard input to @var{process}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858 An error is signaled unless both @var{start} and @var{end} are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 integers or markers that indicate positions in the current buffer. (It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 is unimportant which number is larger.)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
861 @end defun
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
863 @defun process-send-eof &optional process
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
864 This function makes @var{process} see an end-of-file in its
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
865 input. The @acronym{EOF} comes after any text already sent to it.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
867 The function returns @var{process}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871 (process-send-eof "shell")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872 @result{} "shell"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
877 @defun process-running-child-p process
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
878 This function will tell you whether a subprocess has given control of
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
879 its terminal to its own child process. The value is @code{t} if this is
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
880 true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
881 that this is not so.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
882 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
883
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 @node Signals to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 @section Sending Signals to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886 @cindex process signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 @cindex sending signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888 @cindex signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890 @dfn{Sending a signal} to a subprocess is a way of interrupting its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 activities. There are several different signals, each with its own
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 meaning. The set of signals and their names is defined by the operating
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893 system. For example, the signal @code{SIGINT} means that the user has
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894 typed @kbd{C-c}, or that some analogous thing has happened.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896 Each signal has a standard effect on the subprocess. Most signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 kill the subprocess, but some stop or resume execution instead. Most
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 signals can optionally be handled by programs; if the program handles
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899 the signal, then we can say nothing in general about its effects.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 You can send signals explicitly by calling the functions in this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902 section. Emacs also sends signals automatically at certain times:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 killing a buffer sends a @code{SIGHUP} signal to all its associated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 processes. (@code{SIGHUP} is a signal that usually indicates that the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 user hung up the phone.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 Each of the signal-sending functions takes two optional arguments:
62229
789b9a24928a (Signals to Processes): Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 60270
diff changeset
909 @var{process} and @var{current-group}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
911 The argument @var{process} must be either a process, a process
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
912 name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
913 stands for a process through @code{get-buffer-process}. @code{nil}
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
914 stands for the process associated with the current buffer. An error
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
915 is signaled if @var{process} does not identify a process.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 The argument @var{current-group} is a flag that makes a difference
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918 when you are running a job-control shell as an Emacs subprocess. If it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 is non-@code{nil}, then the signal is sent to the current process-group
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
920 of the terminal that Emacs uses to communicate with the subprocess. If
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
921 the process is a job-control shell, this means the shell's current
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
922 subjob. If it is @code{nil}, the signal is sent to the process group of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 the immediate subprocess of Emacs. If the subprocess is a job-control
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924 shell, this is the shell itself.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926 The flag @var{current-group} has no effect when a pipe is used to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 communicate with the subprocess, because the operating system does not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 support the distinction in the case of pipes. For the same reason,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929 job-control shells won't work when a pipe is used. See
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
930 @code{process-connection-type} in @ref{Asynchronous Processes}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
931
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
932 @defun interrupt-process &optional process current-group
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
933 This function interrupts the process @var{process} by sending the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936 others) sends this signal. When the argument @var{current-group} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 non-@code{nil}, you can think of this function as ``typing @kbd{C-c}''
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 on the terminal by which Emacs talks to the subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
941 @defun kill-process &optional process current-group
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
942 This function kills the process @var{process} by sending the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 signal @code{SIGKILL}. This signal kills the subprocess immediately,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 and cannot be handled by the subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
947 @defun quit-process &optional process current-group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
948 This function sends the signal @code{SIGQUIT} to the process
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
949 @var{process}. This signal is the one sent by the ``quit
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951 Emacs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
954 @defun stop-process &optional process current-group
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
955 This function stops the process @var{process} by sending the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957 execution.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
958
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
959 Outside of Emacs, on systems with job control, the ``stop character''
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
960 (usually @kbd{C-z}) normally sends this signal. When
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
961 @var{current-group} is non-@code{nil}, you can think of this function as
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
962 ``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
963 subprocess.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
966 @defun continue-process &optional process current-group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 This function resumes execution of the process @var{process} by sending
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
968 it the signal @code{SIGCONT}. This presumes that @var{process} was
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 stopped previously.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 @c Emacs 19 feature
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
973 @defun signal-process process signal
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
974 This function sends a signal to process @var{process}. The argument
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
975 @var{signal} specifies which signal to send; it should be an integer.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
976
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
977 The @var{process} argument can be a system process @acronym{ID}; that
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
978 allows you to send signals to processes that are not children of
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
979 Emacs.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 @node Output from Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 @section Receiving Output from Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 @cindex process output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 @cindex output from processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 There are two ways to receive the output that a subprocess writes to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 its standard output stream. The output can be inserted in a buffer,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989 which is called the associated buffer of the process, or a function
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
990 called the @dfn{filter function} can be called to act on the output. If
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
991 the process has no buffer and no filter function, its output is
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
992 discarded.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
993
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
994 When a subprocess terminates, Emacs reads any pending output,
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
995 then stops reading output from that subprocess. Therefore, if the
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
996 subprocess has children that are still live and still producing
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
997 output, Emacs won't receive that output.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
998
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
999 Output from a subprocess can arrive only while Emacs is waiting: when
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1000 reading terminal input, in @code{sit-for} and @code{sleep-for}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1001 (@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1002 Output}). This minimizes the problem of timing errors that usually
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1003 plague parallel programming. For example, you can safely create a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1004 process and only then specify its buffer or filter function; no output
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1005 can arrive before you finish, if the code in between does not call any
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1006 primitive that waits.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1007
56704
900340a218c9 (Output from Processes): New var `process-adaptive-read-buffering'.
Kim F. Storm <storm@cua.dk>
parents: 56703
diff changeset
1008 @defvar process-adaptive-read-buffering
900340a218c9 (Output from Processes): New var `process-adaptive-read-buffering'.
Kim F. Storm <storm@cua.dk>
parents: 56703
diff changeset
1009 On some systems, when Emacs reads the output from a subprocess, the
900340a218c9 (Output from Processes): New var `process-adaptive-read-buffering'.
Kim F. Storm <storm@cua.dk>
parents: 56703
diff changeset
1010 output data is read in very small blocks, potentially resulting in
63560
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
1011 very poor performance. This behavior can be remedied to some extent
56704
900340a218c9 (Output from Processes): New var `process-adaptive-read-buffering'.
Kim F. Storm <storm@cua.dk>
parents: 56703
diff changeset
1012 by setting the variable @var{process-adaptive-read-buffering} to a
58405
4fe765649696 (Synchronous Processes, Output from Processes):
Jesper Harder <harder@ifa.au.dk>
parents: 57670
diff changeset
1013 non-@code{nil} value (the default), as it will automatically delay reading
56704
900340a218c9 (Output from Processes): New var `process-adaptive-read-buffering'.
Kim F. Storm <storm@cua.dk>
parents: 56703
diff changeset
1014 from such processes, thus allowing them to produce more output before
900340a218c9 (Output from Processes): New var `process-adaptive-read-buffering'.
Kim F. Storm <storm@cua.dk>
parents: 56703
diff changeset
1015 Emacs tries to read it.
900340a218c9 (Output from Processes): New var `process-adaptive-read-buffering'.
Kim F. Storm <storm@cua.dk>
parents: 56703
diff changeset
1016 @end defvar
900340a218c9 (Output from Processes): New var `process-adaptive-read-buffering'.
Kim F. Storm <storm@cua.dk>
parents: 56703
diff changeset
1017
27259
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1018 It is impossible to separate the standard output and standard error
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1019 streams of the subprocess, because Emacs normally spawns the subprocess
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1020 inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1021 you want to keep the output to those streams separate, you should
54916
07f4773453a0 Markup fixes.
Jesper Harder <harder@ifa.au.dk>
parents: 54864
diff changeset
1022 redirect one of them to a file---for example, by using an appropriate
27259
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1023 shell command.
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1024
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 @menu
51993
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1026 * Process Buffers:: If no filter, output is put in a buffer.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1027 * Filter Functions:: Filter functions accept output from the process.
51994
eb38ba134224 Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 51993
diff changeset
1028 * Decoding Output:: Filters can get unibyte or multibyte strings.
51993
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1029 * Accepting Output:: How to wait until process output arrives.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 @node Process Buffers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 @subsection Process Buffers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1035 A process can (and usually does) have an @dfn{associated buffer},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036 which is an ordinary Emacs buffer that is used for two purposes: storing
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 the output from the process, and deciding when to kill the process. You
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038 can also use the buffer to identify a process to operate on, since in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039 normal practice only one process is associated with any given buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040 Many applications of processes also use the buffer for editing input to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 be sent to the process, but this is not built into Emacs Lisp.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043 Unless the process has a filter function (@pxref{Filter Functions}),
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044 its output is inserted in the associated buffer. The position to insert
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1045 the output is determined by the @code{process-mark}, which is then
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1046 updated to point to the end of the text just inserted. Usually, but not
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1047 always, the @code{process-mark} is at the end of the buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 @defun process-buffer process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050 This function returns the associated buffer of the process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051 @var{process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055 (process-buffer (get-process "shell"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 @result{} #<buffer *shell*>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 @defun process-mark process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 This function returns the process marker for @var{process}, which is the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 marker that says where to insert output from the process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 If @var{process} does not have a buffer, @code{process-mark} returns a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 marker that points nowhere.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 Insertion of process output in a buffer uses this marker to decide where
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 to insert, and updates it to point after the inserted text. That is why
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070 successive batches of output are inserted consecutively.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1072 Filter functions normally should use this marker in the same fashion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1073 as is done by direct insertion of output in the buffer. A good
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 example of a filter function that uses @code{process-mark} is found at
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 the end of the following section.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077 When the user is expected to enter input in the process buffer for
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1078 transmission to the process, the process marker separates the new input
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1079 from previous output.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 @defun set-process-buffer process buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083 This function sets the buffer associated with @var{process} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 associated with no buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 @defun get-buffer-process buffer-or-name
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1089 This function returns a nondeleted process associated with the buffer
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1090 specified by @var{buffer-or-name}. If there are several processes
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1091 associated with it, this function chooses one (currently, the one most
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1092 recently created, but don't count on that). Deletion of a process
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1093 (see @code{delete-process}) makes it ineligible for this function to
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1094 return.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1095
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1096 It is usually a bad idea to have more than one process associated with
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1097 the same buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1098
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 (get-buffer-process "*shell*")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102 @result{} #<process shell>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106 Killing the process's buffer deletes the process, which kills the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1108 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110 @node Filter Functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111 @subsection Process Filter Functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1112 @cindex filter function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 @cindex process filter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115 A process @dfn{filter function} is a function that receives the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116 standard output from the associated process. If a process has a filter,
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1117 then @emph{all} output from that process is passed to the filter. The
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1118 process buffer is used directly for output from the process only when
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1119 there is no filter.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1121 The filter function can only be called when Emacs is waiting for
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1122 something, because process output arrives only at such times. Emacs
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1123 waits when reading terminal input, in @code{sit-for} and
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1124 @code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1125 (@pxref{Accepting Output}).
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1126
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1127 A filter function must accept two arguments: the associated process
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1128 and a string, which is output just received from it. The function is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1129 then free to do whatever it chooses with the output.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 Quitting is normally inhibited within a filter function---otherwise,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 the effect of typing @kbd{C-g} at command level or to quit a user
66152
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1133 command would be unpredictable. If you want to permit quitting inside
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1134 a filter function, bind @code{inhibit-quit} to @code{nil}. In most
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1135 cases, the right way to do this is with the macro
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1136 @code{with-local-quit}. @xref{Quitting}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1138 If an error happens during execution of a filter function, it is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1139 caught automatically, so that it doesn't stop the execution of whatever
12125
995be67f3fd1 updates for version 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
1140 program was running when the filter function was started. However, if
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1141 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1142 off. This makes it possible to use the Lisp debugger to debug the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1143 filter function. @xref{Debugger}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1144
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 Many filter functions sometimes or always insert the text in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 process's buffer, mimicking the actions of Emacs when there is no
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147 filter. Such filter functions need to use @code{set-buffer} in order to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148 be sure to insert in that buffer. To avoid setting the current buffer
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1149 semipermanently, these filter functions must save and restore the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1150 current buffer. They should also update the process marker, and in some
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1151 cases update the value of point. Here is how to do these things:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 (defun ordinary-insertion-filter (proc string)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1156 (with-current-buffer (process-buffer proc)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1157 (let ((moving (= (point) (process-mark proc))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1160 (save-excursion
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1161 ;; @r{Insert the text, advancing the process marker.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1162 (goto-char (process-mark proc))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1163 (insert string)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1164 (set-marker (process-mark proc) (point)))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1165 (if moving (goto-char (process-mark proc))))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1169 @noindent
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1170 The reason to use @code{with-current-buffer}, rather than using
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1171 @code{save-excursion} to save and restore the current buffer, is so as
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1172 to preserve the change in point made by the second call to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1173 @code{goto-char}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 To make the filter force the process buffer to be visible whenever new
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 text arrives, insert the following line just before the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1177 @code{with-current-buffer} construct:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1180 (display-buffer (process-buffer proc))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1183 To force point to the end of the new output, no matter where it was
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1184 previously, eliminate the variable @code{moving} and call
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185 @code{goto-char} unconditionally.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1186
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1187 In earlier Emacs versions, every filter function that did regular
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1188 expression searching or matching had to explicitly save and restore the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1189 match data. Now Emacs does this automatically for filter functions;
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1190 they never need to do it explicitly. @xref{Match Data}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192 A filter function that writes the output into the buffer of the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1193 process should check whether the buffer is still alive. If it tries to
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1194 insert into a dead buffer, it will get an error. The expression
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1195 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1196 if the buffer is dead.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198 The output to the function may come in chunks of any size. A program
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1199 that produces the same output twice in a row may send it as one batch of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1200 200 characters one time, and five batches of 40 characters the next. If
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1201 the filter looks for certain text strings in the subprocess output, make
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1202 sure to handle the case where one of these strings is split across two
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1203 or more batches of output.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 @defun set-process-filter process filter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1206 This function gives @var{process} the filter function @var{filter}. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207 @var{filter} is @code{nil}, it gives the process no filter.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1208 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1209
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 @defun process-filter process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211 This function returns the filter function of @var{process}, or @code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212 if it has none.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1213 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215 Here is an example of use of a filter function:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1216
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1218 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219 (defun keep-output (process output)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220 (setq kept (cons output kept)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221 @result{} keep-output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1222 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1224 (setq kept nil)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1227 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1228 (set-process-filter (get-process "shell") 'keep-output)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229 @result{} keep-output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232 (process-send-string "shell" "ls ~/other\n")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234 kept
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235 @result{} ("lewis@@slug[8] % "
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1237 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 address.txt backup.psf kolstad.psf
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240 backup.bib~ david.mss resume-Dec-86.mss~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241 backup.err david.psf resume-Dec.psf
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242 backup.mss dland syllabus.mss
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 "
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 "#backups.mss# backup.mss~ kolstad.mss
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245 ")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249 @ignore @c The code in this example doesn't show the right way to do things.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 Here is another, more realistic example, which demonstrates how to use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251 the process mark to do insertion in the same fashion as is done when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 there is no filter function:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257 ;; @r{and make sure that buffer is shown in some window.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1258 (defun my-process-filter (proc str)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1259 (let ((cur (selected-window))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1260 (pop-up-windows t))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1261 (pop-to-buffer my-shell-buffer)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1264 (goto-char (point-max))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1265 (insert str)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1266 (set-marker (process-mark proc) (point-max))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1267 (select-window cur)))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270 @end ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271
51993
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1272 @node Decoding Output
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1273 @subsection Decoding Process Output
76835
e5b96737f906 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 76833
diff changeset
1274 @cindex decode process output
51993
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1275
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1276 When Emacs writes process output directly into a multibyte buffer,
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1277 it decodes the output according to the process output coding system.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1278 If the coding system is @code{raw-text} or @code{no-conversion}, Emacs
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1279 converts the unibyte output to multibyte using
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
1280 @code{string-to-multibyte}, and inserts the resulting multibyte text.
51993
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1281
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1282 You can use @code{set-process-coding-system} to specify which coding
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1283 system to use (@pxref{Process Information}). Otherwise, the coding
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1284 system comes from @code{coding-system-for-read}, if that is
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1285 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1286 Coding Systems}).
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1287
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1288 @strong{Warning:} Coding systems such as @code{undecided} which
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1289 determine the coding system from the data do not work entirely
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1290 reliably with asynchronous subprocess output. This is because Emacs
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1291 has to process asynchronous subprocess output in batches, as it
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1292 arrives. Emacs must try to detect the proper coding system from one
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1293 batch at a time, and this does not always work. Therefore, if at all
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1294 possible, specify a coding system that determines both the character
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1295 code conversion and the end of line conversion---that is, one like
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1296 @code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1297
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1298 @cindex filter multibyte flag, of process
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1299 @cindex process filter multibyte flag
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1300 When Emacs calls a process filter function, it provides the process
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1301 output as a multibyte string or as a unibyte string according to the
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1302 process's filter multibyte flag. If the flag is non-@code{nil}, Emacs
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1303 decodes the output according to the process output coding system to
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1304 produce a multibyte string, and passes that to the process. If the
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1305 flag is @code{nil}, Emacs puts the output into a unibyte string, with
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1306 no decoding, and passes that.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1307
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1308 When you create a process, the filter multibyte flag takes its
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1309 initial value from @code{default-enable-multibyte-characters}. If you
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1310 want to change the flag later on, use
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1311 @code{set-process-filter-multibyte}.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1312
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1313 @defun set-process-filter-multibyte process multibyte
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1314 This function sets the filter multibyte flag of @var{process}
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1315 to @var{multibyte}.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1316 @end defun
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1317
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1318 @defun process-filter-multibyte-p process
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1319 This function returns the filter multibyte flag of @var{process}.
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1320 @end defun
d99e407c0a21 (Decoding Output): New node.
Richard M. Stallman <rms@gnu.org>
parents: 51922
diff changeset
1321
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 @node Accepting Output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323 @subsection Accepting Output from Processes
76835
e5b96737f906 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 76833
diff changeset
1324 @cindex accept input from processes
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 Output from asynchronous subprocesses normally arrives only while
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1327 Emacs is waiting for some sort of external event, such as elapsed time
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1328 or terminal input. Occasionally it is useful in a Lisp program to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1329 explicitly permit output to arrive at a specific point, or even to wait
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330 until output arrives from a process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331
77655
61d6d08c1ecf (Accepting Output): Revert most of previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77648
diff changeset
1332 @defun accept-process-output &optional process seconds millisec just-this-one
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1333 This function allows Emacs to read pending output from processes. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334 output is inserted in the associated buffers or given to their filter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335 functions. If @var{process} is non-@code{nil} then this function does
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1336 not return until some output has been received from @var{process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1337
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1338 @c Emacs 19 feature
77655
61d6d08c1ecf (Accepting Output): Revert most of previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77648
diff changeset
1339 The arguments @var{seconds} and @var{millisec} let you specify timeout
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340 periods. The former specifies a period measured in seconds and the
77655
61d6d08c1ecf (Accepting Output): Revert most of previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77648
diff changeset
1341 latter specifies one measured in milliseconds. The two time periods
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 thus specified are added together, and @code{accept-process-output}
77648
5fac150d631b (Accepting Output): accept-process-output
Richard M. Stallman <rms@gnu.org>
parents: 77123
diff changeset
1343 returns after that much time, whether or not there has been any
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1344 subprocess output.
81737
326bae23bda1 * process.texi (Asynchronous Processes):
Michael Albinus <michael.albinus@gmx.de>
parents: 77655
diff changeset
1345
77655
61d6d08c1ecf (Accepting Output): Revert most of previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77648
diff changeset
1346 The argument @var{millisec} is semi-obsolete nowadays because
77648
5fac150d631b (Accepting Output): accept-process-output
Richard M. Stallman <rms@gnu.org>
parents: 77123
diff changeset
1347 @var{seconds} can be a floating point number to specify waiting a
5fac150d631b (Accepting Output): accept-process-output
Richard M. Stallman <rms@gnu.org>
parents: 77123
diff changeset
1348 fractional number of seconds. If @var{seconds} is 0, the function
5fac150d631b (Accepting Output): accept-process-output
Richard M. Stallman <rms@gnu.org>
parents: 77123
diff changeset
1349 accepts whatever output is pending but does not wait.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1350
59996
aac0a33f5772 Change release version from 21.4 to 22.1 throughout.
Kim F. Storm <storm@cua.dk>
parents: 58500
diff changeset
1351 @c Emacs 22.1 feature
56703
fdf8546f215b (Accepting Output): Add `just-this-one' arg to `accept-process-output'.
Kim F. Storm <storm@cua.dk>
parents: 56215
diff changeset
1352 If @var{process} is a process, and the argument @var{just-this-one} is
58405
4fe765649696 (Synchronous Processes, Output from Processes):
Jesper Harder <harder@ifa.au.dk>
parents: 57670
diff changeset
1353 non-@code{nil}, only output from that process is handled, suspending output
56703
fdf8546f215b (Accepting Output): Add `just-this-one' arg to `accept-process-output'.
Kim F. Storm <storm@cua.dk>
parents: 56215
diff changeset
1354 from other processes until some output has been received from that
fdf8546f215b (Accepting Output): Add `just-this-one' arg to `accept-process-output'.
Kim F. Storm <storm@cua.dk>
parents: 56215
diff changeset
1355 process or the timeout expires. If @var{just-this-one} is an integer,
fdf8546f215b (Accepting Output): Add `just-this-one' arg to `accept-process-output'.
Kim F. Storm <storm@cua.dk>
parents: 56215
diff changeset
1356 also inhibit running timers. This feature is generally not
fdf8546f215b (Accepting Output): Add `just-this-one' arg to `accept-process-output'.
Kim F. Storm <storm@cua.dk>
parents: 56215
diff changeset
1357 recommended, but may be necessary for specific applications, such as
fdf8546f215b (Accepting Output): Add `just-this-one' arg to `accept-process-output'.
Kim F. Storm <storm@cua.dk>
parents: 56215
diff changeset
1358 speech synthesis.
fdf8546f215b (Accepting Output): Add `just-this-one' arg to `accept-process-output'.
Kim F. Storm <storm@cua.dk>
parents: 56215
diff changeset
1359
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1360 The function @code{accept-process-output} returns non-@code{nil} if it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361 did get some output, or @code{nil} if the timeout expired before output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1362 arrived.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 @node Sentinels
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1366 @section Sentinels: Detecting Process Status Changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 @cindex process sentinel
76993
55c9ef5f1559 Improve index entries.
Richard M. Stallman <rms@gnu.org>
parents: 76922
diff changeset
1368 @cindex sentinel (of process)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370 A @dfn{process sentinel} is a function that is called whenever the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371 associated process changes status for any reason, including signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372 (whether sent by Emacs or caused by the process's own actions) that
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1373 terminate, stop, or continue the process. The process sentinel is
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1374 also called if the process exits. The sentinel receives two
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1375 arguments: the process for which the event occurred, and a string
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1376 describing the type of event.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1377
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1378 The string describing the event looks like one of the following:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1379
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1380 @itemize @bullet
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
1381 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1382 @code{"finished\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1383
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1384 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1385 @code{"exited abnormally with code @var{exitcode}\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1386
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1387 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1388 @code{"@var{name-of-signal}\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1389
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1390 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1391 @code{"@var{name-of-signal} (core dumped)\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1392 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1393
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1394 A sentinel runs only while Emacs is waiting (e.g., for terminal
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1395 input, or for time to elapse, or for process output). This avoids the
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1396 timing errors that could result from running them at random places in
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1397 the middle of other Lisp programs. A program can wait, so that
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1398 sentinels will run, by calling @code{sit-for} or @code{sleep-for}
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1399 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1400 Output}). Emacs also allows sentinels to run when the command loop is
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1401 reading input. @code{delete-process} calls the sentinel when it
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1402 terminates a running process.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1403
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1404 Emacs does not keep a queue of multiple reasons to call the sentinel
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1405 of one process; it records just the current status and the fact that
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1406 there has been a change. Therefore two changes in status, coming in
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1407 quick succession, can call the sentinel just once. However, process
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1408 termination will always run the sentinel exactly once. This is
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1409 because the process status can't change again after termination.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410
66152
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1411 Emacs explicitly checks for output from the process before running
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1412 the process sentinel. Once the sentinel runs due to process
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1413 termination, no further output can arrive from the process.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1414
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1415 A sentinel that writes the output into the buffer of the process
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1416 should check whether the buffer is still alive. If it tries to insert
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1417 into a dead buffer, it will get an error. If the buffer is dead,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419
66152
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1420 Quitting is normally inhibited within a sentinel---otherwise, the
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1421 effect of typing @kbd{C-g} at command level or to quit a user command
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1422 would be unpredictable. If you want to permit quitting inside a
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1423 sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1424 right way to do this is with the macro @code{with-local-quit}.
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1425 @xref{Quitting}.
6677034b52bb (Sentinels): Clarify about output and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 64913
diff changeset
1426
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1427 If an error happens during execution of a sentinel, it is caught
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1428 automatically, so that it doesn't stop the execution of whatever
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1429 programs was running when the sentinel was started. However, if
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1430 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1431 off. This makes it possible to use the Lisp debugger to debug the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1432 sentinel. @xref{Debugger}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1433
44428
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1434 While a sentinel is running, the process sentinel is temporarily
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1435 set to @code{nil} so that the sentinel won't run recursively.
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1436 For this reason it is not possible for a sentinel to specify
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1437 a new sentinel.
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1438
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1439 In earlier Emacs versions, every sentinel that did regular expression
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1440 searching or matching had to explicitly save and restore the match data.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1441 Now Emacs does this automatically for sentinels; they never need to do
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1442 it explicitly. @xref{Match Data}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1443
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444 @defun set-process-sentinel process sentinel
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445 This function associates @var{sentinel} with @var{process}. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446 @var{sentinel} is @code{nil}, then the process will have no sentinel.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1447 The default behavior when there is no sentinel is to insert a message in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1448 the process's buffer when the process status changes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1449
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1450 Changes in process sentinel take effect immediately---if the sentinel
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1451 is slated to be run but has not been called yet, and you specify a new
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1452 sentinel, the eventual call to the sentinel will use the new one.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1453
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456 (defun msg-me (process event)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 (princ
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458 (format "Process: %s had the event `%s'" process event)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 (set-process-sentinel (get-process "shell") 'msg-me)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460 @result{} msg-me
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1461 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 (kill-process (get-process "shell"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464 @print{} Process: #<process shell> had the event `killed'
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 @result{} #<process shell>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1470 @defun process-sentinel process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471 This function returns the sentinel of @var{process}, or @code{nil} if it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472 has none.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 @defun waiting-for-user-input-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476 While a sentinel or filter function is running, this function returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1477 non-@code{nil} if Emacs was waiting for keyboard input from the user at
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478 the time the sentinel or filter function was called, @code{nil} if it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1479 was not.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1480 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1482 @node Query Before Exit
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 46340
diff changeset
1483 @section Querying Before Exit
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1484
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1485 When Emacs exits, it terminates all its subprocesses by sending them
60270
b87ad571b7a8 (Subprocess Creation): Explain nil in exec-path. Cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 59996
diff changeset
1486 the @code{SIGHUP} signal. Because subprocesses may be doing
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1487 valuable work, Emacs normally asks the user to confirm that it is ok
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1488 to terminate them. Each process has a query flag which, if
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1489 non-@code{nil}, says that Emacs should ask for confirmation before
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1490 exiting and thus killing that process. The default for the query flag
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1491 is @code{t}, meaning @emph{do} query.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1492
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1493 @defun process-query-on-exit-flag process
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1494 This returns the query flag of @var{process}.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1495 @end defun
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1496
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1497 @defun set-process-query-on-exit-flag process flag
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1498 This function sets the query flag of @var{process} to @var{flag}. It
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1499 returns @var{flag}.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1500
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1501 @smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1502 @group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1503 ;; @r{Don't query about the shell process}
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1504 (set-process-query-on-exit-flag (get-process "shell") nil)
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1505 @result{} t
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1506 @end group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1507 @end smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1508 @end defun
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1509
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1510 @defun process-kill-without-query process &optional do-query
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1511 This function clears the query flag of @var{process}, so that
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1512 Emacs will not query the user on account of that process.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1513
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1514 Actually, the function does more than that: it returns the old value of
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1515 the process's query flag, and sets the query flag to @var{do-query}.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1516 Please don't use this function to do those things any more---please
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1517 use the newer, cleaner functions @code{process-query-on-exit-flag} and
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1518 @code{set-process-query-on-exit-flag} in all but the simplest cases.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1519 The only way you should use @code{process-kill-without-query} nowadays
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1520 is like this:
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1521
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1522 @smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1523 @group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1524 ;; @r{Don't query about the shell process}
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1525 (process-kill-without-query (get-process "shell"))
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1526 @end group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1527 @end smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1528 @end defun
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1529
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1530 @node Transaction Queues
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531 @section Transaction Queues
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1532 @cindex transaction queue
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1534 You can use a @dfn{transaction queue} to communicate with a subprocess
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1535 using transactions. First use @code{tq-create} to create a transaction
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1536 queue communicating with a specified process. Then you can call
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1537 @code{tq-enqueue} to send a transaction.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539 @defun tq-create process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540 This function creates and returns a transaction queue communicating with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1541 @var{process}. The argument @var{process} should be a subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542 capable of sending and receiving streams of bytes. It may be a child
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1543 process, or it may be a TCP connection to a server, possibly on another
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1544 machine.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1545 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1546
70034
db4c2d467e9a Revision: emacs@sv.gnu.org/emacs--devo--0--patch-220
Miles Bader <miles@gnu.org>
parents: 69708
diff changeset
1547 @defun tq-enqueue queue question regexp closure fn &optional delay-question
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1548 This function sends a transaction to queue @var{queue}. Specifying the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1549 queue has the effect of specifying the subprocess to talk to.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1550
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1551 The argument @var{question} is the outgoing message that starts the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1552 transaction. The argument @var{fn} is the function to call when the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1553 corresponding answer comes back; it is called with two arguments:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1554 @var{closure}, and the answer received.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1555
39426
4520697c8aa5 (tq-enqueue): Clarify meaning of REGEXP.
Richard M. Stallman <rms@gnu.org>
parents: 27370
diff changeset
1556 The argument @var{regexp} is a regular expression that should match
4520697c8aa5 (tq-enqueue): Clarify meaning of REGEXP.
Richard M. Stallman <rms@gnu.org>
parents: 27370
diff changeset
1557 text at the end of the entire answer, but nothing before; that's how
4520697c8aa5 (tq-enqueue): Clarify meaning of REGEXP.
Richard M. Stallman <rms@gnu.org>
parents: 27370
diff changeset
1558 @code{tq-enqueue} determines where the answer ends.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1559
70034
db4c2d467e9a Revision: emacs@sv.gnu.org/emacs--devo--0--patch-220
Miles Bader <miles@gnu.org>
parents: 69708
diff changeset
1560 If the argument @var{delay-question} is non-nil, delay sending this
db4c2d467e9a Revision: emacs@sv.gnu.org/emacs--devo--0--patch-220
Miles Bader <miles@gnu.org>
parents: 69708
diff changeset
1561 question until the process has finished replying to any previous
72548
e5542d6aad7f Miscellaneous tq-related fixes.
Miles Bader <miles@gnu.org>
parents: 72010
diff changeset
1562 questions. This produces more reliable results with some processes.
70034
db4c2d467e9a Revision: emacs@sv.gnu.org/emacs--devo--0--patch-220
Miles Bader <miles@gnu.org>
parents: 69708
diff changeset
1563
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564 The return value of @code{tq-enqueue} itself is not meaningful.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1565 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1566
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1567 @defun tq-close queue
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1568 Shut down transaction queue @var{queue}, waiting for all pending transactions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1569 to complete, and then terminate the connection or child process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1570 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1571
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1572 Transaction queues are implemented by means of a filter function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1573 @xref{Filter Functions}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1575 @node Network
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1576 @section Network Connections
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1577 @cindex network connection
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1578 @cindex TCP
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1579 @cindex UDP
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1580
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1581 Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1582 connections to other processes on the same machine or other machines.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1583 A network connection is handled by Lisp much like a subprocess, and is
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1584 represented by a process object. However, the process you are
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1585 communicating with is not a child of the Emacs process, so it has no
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52830
diff changeset
1586 process @acronym{ID}, and you can't kill it or send it signals. All you
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1587 can do is send and receive data. @code{delete-process} closes the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1588 connection, but does not kill the program at the other end; that
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1589 program must decide what to do about closure of the connection.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1590
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1591 Lisp programs can listen for connections by creating network
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1592 servers. A network server is also represented by a kind of process
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1593 object, but unlike a network connection, the network server never
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1594 transfers data itself. When it receives a connection request, it
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1595 creates a new network connection to represent the connection just
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1596 made. (The network connection inherits certain information, including
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1597 the process plist, from the server.) The network server then goes
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1598 back to listening for more connection requests.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1599
52818
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1600 Network connections and servers are created by calling
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1601 @code{make-network-process} with an argument list consisting of
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1602 keyword/argument pairs, for example @code{:server t} to create a
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1603 server process, or @code{:type 'datagram} to create a datagram
52830
b4281fb5cff8 (Network): Fix typo in xref (from Robert J. Chassell).
Kim F. Storm <storm@cua.dk>
parents: 52818
diff changeset
1604 connection. @xref{Low-Level Network}, for details. You can also use
63560
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
1605 the @code{open-network-stream} function described below.
52818
39239421c7e3 (Network): Introduce make-network-process.
Kim F. Storm <storm@cua.dk>
parents: 52759
diff changeset
1606
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1607 You can distinguish process objects representing network connections
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1608 and servers from those representing subprocesses with the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1609 @code{process-status} function. The possible status values for
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1610 network connections are @code{open}, @code{closed}, @code{connect},
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1611 and @code{failed}. For a network server, the status is always
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1612 @code{listen}. None of those values is possible for a real
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1613 subprocess. @xref{Process Information}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1614
54265
1f7cd275e61f Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 54004
diff changeset
1615 You can stop and resume operation of a network process by calling
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1616 @code{stop-process} and @code{continue-process}. For a server
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1617 process, being stopped means not accepting new connections. (Up to 5
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1618 connection requests will be queued for when you resume the server; you
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1619 can increase this limit, unless it is imposed by the operating
64720
3d8efebded47 Fix typo.
Juanma Barranquero <lekktu@gmail.com>
parents: 63583
diff changeset
1620 system.) For a network stream connection, being stopped means not
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1621 processing input (any arriving input waits until you resume the
52695
e5c94aabfe90 (Network): Say what stopped datagram connections do.
Richard M. Stallman <rms@gnu.org>
parents: 52598
diff changeset
1622 connection). For a datagram connection, some number of packets may be
e5c94aabfe90 (Network): Say what stopped datagram connections do.
Richard M. Stallman <rms@gnu.org>
parents: 52598
diff changeset
1623 queued but input may be lost. You can use the function
e5c94aabfe90 (Network): Say what stopped datagram connections do.
Richard M. Stallman <rms@gnu.org>
parents: 52598
diff changeset
1624 @code{process-command} to determine whether a network connection or
e5c94aabfe90 (Network): Say what stopped datagram connections do.
Richard M. Stallman <rms@gnu.org>
parents: 52598
diff changeset
1625 server is stopped; a non-@code{nil} value means yes.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1626
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1627 @defun open-network-stream name buffer-or-name host service
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1628 This function opens a TCP connection, and returns a process object
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1629 that represents the connection.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1631 The @var{name} argument specifies the name for the process object. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1632 is modified as necessary to make it unique.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1633
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1634 The @var{buffer-or-name} argument is the buffer to associate with the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1635 connection. Output from the connection is inserted in the buffer,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1636 unless you specify a filter function to handle the output. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1637 @var{buffer-or-name} is @code{nil}, it means that the connection is not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1638 associated with any buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1639
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1640 The arguments @var{host} and @var{service} specify where to connect to;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1641 @var{host} is the host name (a string), and @var{service} is the name of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1642 a defined network service (a string) or a port number (an integer).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1643 @end defun
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51994
diff changeset
1644
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1645 @defun process-contact process &optional key
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1646 This function returns information about how a network process was set
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1647 up. For a connection, when @var{key} is @code{nil}, it returns
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1648 @code{(@var{hostname} @var{service})} which specifies what you
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1649 connected to.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1650
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1651 If @var{key} is @code{t}, the value is the complete status information
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1652 for the connection or server; that is, the list of keywords and values
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1653 specified in @code{make-network-process}, except that some of the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1654 values represent the current status instead of what you specified:
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1655
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1656 @table @code
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1657 @item :buffer
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1658 The associated value is the process buffer.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1659 @item :filter
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1660 The associated value is the process filter function.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1661 @item :sentinel
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1662 The associated value is the process sentinel function.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1663 @item :remote
76922
e1bce097669d wording
Karl Berry <karl@gnu.org>
parents: 76878
diff changeset
1664 In a connection, the address in internal format of the remote peer.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1665 @item :local
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1666 The local address, in internal format.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1667 @item :service
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1668 In a server, if you specified @code{t} for @var{service},
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1669 this value is the actual port number.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1670 @end table
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1671
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1672 @code{:local} and @code{:remote} are included even if they were not
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1673 specified explicitly in @code{make-network-process}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1674
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1675 If @var{key} is a keyword, the function returns the value corresponding
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1676 to that keyword.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1677
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1678 For an ordinary child process, this function always returns @code{t}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1679 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1680
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1681 @node Network Servers
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1682 @section Network Servers
76835
e5b96737f906 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 76833
diff changeset
1683 @cindex network servers
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1684
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1685 You create a server by calling @code{make-network-process} with
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1686 @code{:server t}. The server will listen for connection requests from
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1687 clients. When it accepts a client connection request, that creates a
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1688 new network connection, itself a process object, with the following
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1689 parameters:
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1690
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1691 @itemize @bullet
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1692 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1693 The connection's process name is constructed by concatenating the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1694 server process' @var{name} with a client identification string. The
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1695 client identification string for an IPv4 connection looks like
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1696 @samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1697 unique number in brackets, as in @samp{<@var{nnn}>}. The number
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1698 is unique for each connection in the Emacs session.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1699
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1700 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1701 If the server's filter is non-@code{nil}, the connection process does
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1702 not get a separate process buffer; otherwise, Emacs creates a new
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1703 buffer for the purpose. The buffer name is the server's buffer name
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1704 or process name, concatenated with the client identification string.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1705
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1706 The server's process buffer value is never used directly by Emacs, but
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1707 it is passed to the log function, which can log connections by
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1708 inserting text there.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1709
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1710 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1711 The communication type and the process filter and sentinel are
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1712 inherited from those of the server. The server never directly
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1713 uses its filter and sentinel; their sole purpose is to initialize
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1714 connections made to the server.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1715
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1716 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1717 The connection's process contact info is set according to the client's
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1718 addressing information (typically an IP address and a port number).
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1719 This information is associated with the @code{process-contact}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1720 keywords @code{:host}, @code{:service}, @code{:remote}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1721
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1722 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1723 The connection's local address is set up according to the port
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1724 number used for the connection.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1725
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1726 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1727 The client process' plist is initialized from the server's plist.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1728 @end itemize
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1729
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1730 @node Datagrams
56703
fdf8546f215b (Accepting Output): Add `just-this-one' arg to `accept-process-output'.
Kim F. Storm <storm@cua.dk>
parents: 56215
diff changeset
1731 @section Datagrams
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1732 @cindex datagrams
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1733
54265
1f7cd275e61f Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 54004
diff changeset
1734 A datagram connection communicates with individual packets rather
1f7cd275e61f Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 54004
diff changeset
1735 than streams of data. Each call to @code{process-send} sends one
1f7cd275e61f Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 54004
diff changeset
1736 datagram packet (@pxref{Input to Processes}), and each datagram
1f7cd275e61f Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 54004
diff changeset
1737 received results in one call to the filter function.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1738
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1739 The datagram connection doesn't have to talk with the same remote
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1740 peer all the time. It has a @dfn{remote peer address} which specifies
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1741 where to send datagrams to. Each time an incoming datagram is passed
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1742 to the filter function, the peer address is set to the address that
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1743 datagram came from; that way, if the filter function sends a datagram,
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1744 it will go back to that place. You can specify the remote peer
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1745 address when you create the datagram connection using the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1746 @code{:remote} keyword. You can change it later on by calling
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1747 @code{set-process-datagram-address}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1748
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1749 @defun process-datagram-address process
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1750 If @var{process} is a datagram connection or server, this function
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1751 returns its remote peer address.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1752 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1753
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1754 @defun set-process-datagram-address process address
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1755 If @var{process} is a datagram connection or server, this function
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1756 sets its remote peer address to @var{address}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1757 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1758
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1759 @node Low-Level Network
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1760 @section Low-Level Network Access
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1761
64913
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1762 You can also create network connections by operating at a lower
76878
e4d2810db0e9 wording matters
Karl Berry <karl@gnu.org>
parents: 76837
diff changeset
1763 level than that of @code{open-network-stream}, using
64913
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1764 @code{make-network-process}.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1765
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1766 @menu
72010
248521aae95b (Low-Level Network): Make menu more convenient.
Richard M. Stallman <rms@gnu.org>
parents: 71999
diff changeset
1767 * Proc: Network Processes. Using @code{make-network-process}.
248521aae95b (Low-Level Network): Make menu more convenient.
Richard M. Stallman <rms@gnu.org>
parents: 71999
diff changeset
1768 * Options: Network Options. Further control over network connections.
248521aae95b (Low-Level Network): Make menu more convenient.
Richard M. Stallman <rms@gnu.org>
parents: 71999
diff changeset
1769 * Features: Network Feature Testing.
248521aae95b (Low-Level Network): Make menu more convenient.
Richard M. Stallman <rms@gnu.org>
parents: 71999
diff changeset
1770 Determining which network features work on
64913
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1771 the machine you are using.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1772 @end menu
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1773
71999
77f1713977dd (Low-Level Network): Rename node "Make Network"
Kim F. Storm <storm@cua.dk>
parents: 71957
diff changeset
1774 @node Network Processes
64913
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1775 @subsection @code{make-network-process}
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1776
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1777 The basic function for creating network connections and network
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1778 servers is @code{make-network-process}. It can do either of those
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1779 jobs, depending on the arguments you give it.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1780
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1781 @defun make-network-process &rest args
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1782 This function creates a network connection or server and returns the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1783 process object that represents it. The arguments @var{args} are a
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1784 list of keyword/argument pairs. Omitting a keyword is always
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1785 equivalent to specifying it with value @code{nil}, except for
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1786 @code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1787 are the meaningful keywords:
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1788
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1789 @table @asis
62230
98c45ed7ca3f (Low-Level Network): Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 62229
diff changeset
1790 @item :name @var{name}
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1791 Use the string @var{name} as the process name. It is modified if
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1792 necessary to make it unique.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1793
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1794 @item :type @var{type}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1795 Specify the communication type. A value of @code{nil} specifies a
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1796 stream connection (the default); @code{datagram} specifies a datagram
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1797 connection. Both connections and servers can be of either type.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1798
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1799 @item :server @var{server-flag}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1800 If @var{server-flag} is non-@code{nil}, create a server. Otherwise,
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1801 create a connection. For a stream type server, @var{server-flag} may
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1802 be an integer which then specifies the length of the queue of pending
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1803 connections to the server. The default queue length is 5.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1804
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1805 @item :host @var{host}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1806 Specify the host to connect to. @var{host} should be a host name or
70603
0d799d14ece7 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 70034
diff changeset
1807 Internet address, as a string, or the symbol @code{local} to specify
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1808 the local host. If you specify @var{host} for a server, it must
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1809 specify a valid address for the local host, and only clients
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1810 connecting to that address will be accepted.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1811
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1812 @item :service @var{service}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1813 @var{service} specifies a port number to connect to, or, for a server,
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1814 the port number to listen on. It should be a service name that
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1815 translates to a port number, or an integer specifying the port number
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1816 directly. For a server, it can also be @code{t}, which means to let
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1817 the system select an unused port number.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1818
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1819 @item :family @var{family}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1820 @var{family} specifies the address (and protocol) family for
68029
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
1821 communication. @code{nil} means determine the proper address family
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
1822 automatically for the given @var{host} and @var{service}.
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
1823 @code{local} specifies a Unix socket, in which case @var{host} is
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
1824 ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
1825 respectively.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1826
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1827 @item :local @var{local-address}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1828 For a server process, @var{local-address} is the address to listen on.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1829 It overrides @var{family}, @var{host} and @var{service}, and you
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1830 may as well not specify them.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1831
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1832 @item :remote @var{remote-address}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1833 For a connection, @var{remote-address} is the address to connect to.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1834 It overrides @var{family}, @var{host} and @var{service}, and you
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1835 may as well not specify them.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1836
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1837 For a datagram server, @var{remote-address} specifies the initial
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1838 setting of the remote datagram address.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1839
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1840 The format of @var{local-address} or @var{remote-address} depends on
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1841 the address family:
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1842
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1843 @itemize -
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1844 @item
68009
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1845 An IPv4 address is represented as a five-element vector of four 8-bit
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1846 integers and one 16-bit integer
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1847 @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1848 numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1849 @var{p}.
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1850
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1851 @item
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1852 An IPv6 address is represented as a nine-element vector of 16-bit
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1853 integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f}
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1854 @var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1855 @var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
1856 port number @var{p}.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1857
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1858 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1859 A local address is represented as a string which specifies the address
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1860 in the local address space.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1861
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1862 @item
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1863 An ``unsupported family'' address is represented by a cons
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1864 @code{(@var{f} . @var{av})}, where @var{f} is the family number and
54265
1f7cd275e61f Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 54004
diff changeset
1865 @var{av} is a vector specifying the socket address using one element
1f7cd275e61f Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 54004
diff changeset
1866 per address data byte. Do not rely on this format in portable code,
1f7cd275e61f Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 54004
diff changeset
1867 as it may depend on implementation defined constants, data sizes, and
1f7cd275e61f Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 54004
diff changeset
1868 data structure alignment.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1869 @end itemize
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1870
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1871 @item :nowait @var{bool}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1872 If @var{bool} is non-@code{nil} for a stream connection, return
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1873 without waiting for the connection to complete. When the connection
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1874 succeeds or fails, Emacs will call the sentinel function, with a
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1875 second argument matching @code{"open"} (if successful) or
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1876 @code{"failed"}. The default is to block, so that
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1877 @code{make-network-process} does not return until the connection
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1878 has succeeded or failed.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1879
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1880 @item :stop @var{stopped}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1881 Start the network connection or server in the `stopped' state if
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1882 @var{stopped} is non-@code{nil}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1883
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1884 @item :buffer @var{buffer}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1885 Use @var{buffer} as the process buffer.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1886
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1887 @item :coding @var{coding}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1888 Use @var{coding} as the coding system for this process. To specify
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1889 different coding systems for decoding data from the connection and for
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1890 encoding data sent to it, specify @code{(@var{decoding} .
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1891 @var{encoding})} for @var{coding}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1892
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1893 If you don't specify this keyword at all, the default
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1894 is to determine the coding systems from the data.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1895
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1896 @item :noquery @var{query-flag}
63560
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
1897 Initialize the process query flag to @var{query-flag}.
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
1898 @xref{Query Before Exit}.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1899
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1900 @item :filter @var{filter}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1901 Initialize the process filter to @var{filter}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1902
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1903 @item :filter-multibyte @var{bool}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1904 If @var{bool} is non-@code{nil}, strings given to the process filter
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1905 are multibyte, otherwise they are unibyte. If you don't specify this
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1906 keyword at all, the default is that the strings are multibyte if
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1907 @code{default-enable-multibyte-characters} is non-@code{nil}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1908
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1909 @item :sentinel @var{sentinel}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1910 Initialize the process sentinel to @var{sentinel}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1911
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1912 @item :log @var{log}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1913 Initialize the log function of a server process to @var{log}. The log
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1914 function is called each time the server accepts a network connection
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1915 from a client. The arguments passed to the log function are
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1916 @var{server}, @var{connection}, and @var{message}, where @var{server}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1917 is the server process, @var{connection} is the new process for the
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1918 connection, and @var{message} is a string describing what has
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1919 happened.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1920
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1921 @item :plist @var{plist}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1922 Initialize the process plist to @var{plist}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1923 @end table
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
1924
64913
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1925 The original argument list, modified with the actual connection
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1926 information, is available via the @code{process-contact} function.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1927 @end defun
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1928
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1929 @node Network Options
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1930 @subsection Network Options
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1931
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1932 The following network options can be specified when you create a
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1933 network process. Except for @code{:reuseaddr}, you can also set or
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1934 modify these options later, using @code{set-network-process-option}.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1935
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1936 For a server process, the options specified with
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1937 @code{make-network-process} are not inherited by the client
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1938 connections, so you will need to set the necessary options for each
64913
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1939 child connection as it is created.
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1940
52598
a0ba017ef9ef (Low-Level Network): Fix typo.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52596
diff changeset
1941 @table @asis
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1942 @item :bindtodevice @var{device-name}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1943 If @var{device-name} is a non-empty string identifying a network
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1944 interface name (see @code{network-interface-list}), only handle
54777
5745bf089073 Markup fixes.
Jesper Harder <harder@ifa.au.dk>
parents: 54265
diff changeset
1945 packets received on that interface. If @var{device-name} is @code{nil}
5745bf089073 Markup fixes.
Jesper Harder <harder@ifa.au.dk>
parents: 54265
diff changeset
1946 (the default), handle packets received on any interface.
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1947
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1948 Using this option may require special privileges on some systems.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1949
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1950 @item :broadcast @var{broadcast-flag}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1951 If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1952 process will receive datagram packet sent to a broadcast address, and
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1953 be able to send packets to a broadcast address. Ignored for a stream
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1954 connection.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1955
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1956 @item :dontroute @var{dontroute-flag}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1957 If @var{dontroute-flag} is non-@code{nil}, the process can only send
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1958 to hosts on the same network as the local host.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1959
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1960 @item :keepalive @var{keepalive-flag}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1961 If @var{keepalive-flag} is non-@code{nil} for a stream connection,
54004
8cc16a7bf4ce (Low-Level Network): Fix a typo.
Eli Zaretskii <eliz@is.elta.co.il>
parents: 53292
diff changeset
1962 enable exchange of low-level keep-alive messages.
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1963
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1964 @item :linger @var{linger-arg}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1965 If @var{linger-arg} is non-@code{nil}, wait for successful
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1966 transmission of all queued packets on the connection before it is
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1967 deleted (see @code{delete-process}). If @var{linger-arg} is an
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1968 integer, it specifies the maximum time in seconds to wait for queued
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1969 packets to be sent before closing the connection. Default is
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1970 @code{nil} which means to discard unsent queued packets when the
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1971 process is deleted.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1972
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1973 @item :oobinline @var{oobinline-flag}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1974 If @var{oobinline-flag} is non-@code{nil} for a stream connection,
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1975 receive out-of-band data in the normal data stream. Otherwise, ignore
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1976 out-of-band data.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1977
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1978 @item :priority @var{priority}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1979 Set the priority for packets sent on this connection to the integer
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1980 @var{priority}. The interpretation of this number is protocol
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1981 specific, such as setting the TOS (type of service) field on IP
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1982 packets sent on this connection. It may also have system dependent
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1983 effects, such as selecting a specific output queue on the network
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1984 interface.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1985
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1986 @item :reuseaddr @var{reuseaddr-flag}
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1987 If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1988 server process, allow this server to reuse a specific port number (see
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1989 @code{:service}) unless another process on this host is already
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1990 listening on that port. If @var{reuseaddr-flag} is @code{nil}, there
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1991 may be a period of time after the last use of that port (by any
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1992 process on the host), where it is not possible to make a new server on
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1993 that port.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1994 @end table
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1995
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1996 @defun set-network-process-option process option value
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1997 This function sets or modifies a network option for network process
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1998 @var{process}. See @code{make-network-process} for details of options
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
1999 @var{option} and their corresponding values @var{value}.
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
2000
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
2001 The current setting of an option is available via the
54864
ca548870d87a Markup fixes.
Jesper Harder <harder@ifa.au.dk>
parents: 54777
diff changeset
2002 @code{process-contact} function.
52596
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
2003 @end defun
f277840b17b2 (Network, Network Servers): Fix typos.
Kim F. Storm <storm@cua.dk>
parents: 52542
diff changeset
2004
64913
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2005 @node Network Feature Testing
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2006 @subsection Testing Availability of Network Features
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2007
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2008 To test for the availability of a given network feature, use
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2009 @code{featurep} like this:
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2010
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2011 @example
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2012 (featurep 'make-network-process '(@var{keyword} @var{value}))
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2013 @end example
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2014
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2015 @noindent
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2016 The result of the first form is @code{t} if it works to specify
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2017 @var{keyword} with value @var{value} in @code{make-network-process}.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2018 The result of the second form is @code{t} if @var{keyword} is
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2019 supported by @code{make-network-process}. Here are some of the
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2020 @var{keyword}---@var{value} pairs you can test in
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2021 this way.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2022
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2023 @table @code
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2024 @item (:nowait t)
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2025 Non-@code{nil} if non-blocking connect is supported.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2026 @item (:type datagram)
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2027 Non-@code{nil} if datagrams are supported.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2028 @item (:family local)
70603
0d799d14ece7 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 70034
diff changeset
2029 Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported.
68009
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
2030 @item (:family ipv6)
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
2031 Non-@code{nil} if IPv6 is supported.
64913
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2032 @item (:service t)
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2033 Non-@code{nil} if the system can select the port for a server.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2034 @end table
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2035
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2036 To test for the availability of a given network option, use
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2037 @code{featurep} like this:
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2038
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2039 @example
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2040 (featurep 'make-network-process '@var{keyword})
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2041 @end example
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2042
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2043 @noindent
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2044 Here are some of the options you can test in this way.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2045
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2046 @table @code
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2047 @item :bindtodevice
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2048 @itemx :broadcast
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2049 @itemx :dontroute
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2050 @itemx :keepalive
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2051 @itemx :linger
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2052 @itemx :oobinline
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2053 @itemx :priority
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2054 @itemx :reuseaddr
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2055 That particular network option is supported by
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2056 @code{make-network-process} and @code{set-network-process-option}.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2057 @end table
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2058
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2059 @node Misc Network
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2060 @section Misc Network Facilities
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2061
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2062 These additional functions are useful for creating and operating
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2063 on network connections.
989a5fc8da03 (Misc Network, Network Feature Testing)
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
2064
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2065 @defun network-interface-list
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2066 This function returns a list describing the network interfaces
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2067 of the machine you are using. The value is an alist whose
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2068 elements have the form @code{(@var{name} . @var{address})}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2069 @var{address} has the same form as the @var{local-address}
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2070 and @var{remote-address} arguments to @code{make-network-process}.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2071 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2072
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2073 @defun network-interface-info ifname
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2074 This function returns information about the network interface named
63560
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
2075 @var{ifname}. The value is a list of the form
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
2076 @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2077
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2078 @table @var
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2079 @item addr
70603
0d799d14ece7 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 70034
diff changeset
2080 The Internet protocol address.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2081 @item bcast
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2082 The broadcast address.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2083 @item netmask
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2084 The network mask.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2085 @item hwaddr
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2086 The layer 2 address (Ethernet MAC address, for instance).
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2087 @item flags
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2088 The current flags of the interface.
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2089 @end table
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2090 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2091
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2092 @defun format-network-address address &optional omit-port
52759
b85ed952e000 Fix typo.
Richard M. Stallman <rms@gnu.org>
parents: 52695
diff changeset
2093 This function converts the Lisp representation of a network address to
68009
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
2094 a string.
68029
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
2095
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
2096 A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]}
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
2097 represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
2098 number @var{p}. @code{format-network-address} converts that to the
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
2099 string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
2100
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
2101 A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e}
77123
4d7a5d9bbe76 improve breaks in 8.5x11
Karl Berry <karl@gnu.org>
parents: 76993
diff changeset
2102 @var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along
4d7a5d9bbe76 improve breaks in 8.5x11
Karl Berry <karl@gnu.org>
parents: 76993
diff changeset
2103 with a port number. @code{format-network-address} converts that to
4d7a5d9bbe76 improve breaks in 8.5x11
Karl Berry <karl@gnu.org>
parents: 76993
diff changeset
2104 the string
68009
dd865bff7357 (Make Network): Add IPv6 addresses and handling.
Kim F. Storm <storm@cua.dk>
parents: 67044
diff changeset
2105 @code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2106
68029
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
2107 If the vector does not include the port number, @var{p}, or if
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
2108 @var{omit-port} is non-@code{nil}, the result does not include the
61a03413f18b (Misc Network, Make Network): Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 68010
diff changeset
2109 @code{:@var{p}} suffix.
52542
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2110 @end defun
0df4c5163e4e (Process Information): Add list-processes arg QUERY-ONLY.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2111
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2112 @node Byte Packing
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2113 @section Packing and Unpacking Byte Arrays
76833
8c3661f15764 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75992
diff changeset
2114 @cindex byte packing and unpacking
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2115
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2116 This section describes how to pack and unpack arrays of bytes,
63563
c78918330811 (Byte Packing): Fix ungrammatical sentence.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63562
diff changeset
2117 usually for binary network protocols. These functions convert byte arrays
c78918330811 (Byte Packing): Fix ungrammatical sentence.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63562
diff changeset
2118 to alists, and vice versa. The byte array can be represented as a
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2119 unibyte string or as a vector of integers, while the alist associates
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2120 symbols either with fixed-size objects or with recursive sub-alists.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2121
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2122 @cindex serializing
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2123 @cindex deserializing
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2124 @cindex packing
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2125 @cindex unpacking
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2126 Conversion from byte arrays to nested alists is also known as
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2127 @dfn{deserializing} or @dfn{unpacking}, while going in the opposite
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2128 direction is also known as @dfn{serializing} or @dfn{packing}.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2129
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2130 @menu
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2131 * Bindat Spec:: Describing data layout.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2132 * Bindat Functions:: Doing the unpacking and packing.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2133 * Bindat Examples:: Samples of what bindat.el can do for you!
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2134 @end menu
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2135
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2136 @node Bindat Spec
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2137 @subsection Describing Data Layout
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2138
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2139 To control unpacking and packing, you write a @dfn{data layout
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2140 specification}, a special nested list describing named and typed
63568
3586a05f26ff Fix typo.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63563
diff changeset
2141 @dfn{fields}. This specification controls length of each field to be
72723
e32b692e4da5 (Bindat Spec): Suggest names ending in -bindat-spec.
Richard M. Stallman <rms@gnu.org>
parents: 72640
diff changeset
2142 processed, and how to pack or unpack it. We normally keep bindat specs
e32b692e4da5 (Bindat Spec): Suggest names ending in -bindat-spec.
Richard M. Stallman <rms@gnu.org>
parents: 72640
diff changeset
2143 in variables whose names end in @samp{-bindat-spec}; that kind of name
e32b692e4da5 (Bindat Spec): Suggest names ending in -bindat-spec.
Richard M. Stallman <rms@gnu.org>
parents: 72640
diff changeset
2144 is automatically recognized as ``risky.''
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2145
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2146 @cindex endianness
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2147 @cindex big endian
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2148 @cindex little endian
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2149 @cindex network byte ordering
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2150 A field's @dfn{type} describes the size (in bytes) of the object
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2151 that the field represents and, in the case of multibyte fields, how
63560
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
2152 the bytes are ordered within the field. The two possible orderings
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2153 are ``big endian'' (also known as ``network byte ordering'') and
71957
61cb5aae3bc3 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71697
diff changeset
2154 ``little endian.'' For instance, the number @code{#x23cd} (decimal
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2155 9165) in big endian would be the two bytes @code{#x23} @code{#xcd};
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2156 and in little endian, @code{#xcd} @code{#x23}. Here are the possible
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2157 type values:
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2158
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2159 @table @code
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2160 @item u8
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2161 @itemx byte
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2162 Unsigned byte, with length 1.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2163
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2164 @item u16
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2165 @itemx word
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2166 @itemx short
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2167 Unsigned integer in network byte order, with length 2.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2168
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2169 @item u24
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2170 Unsigned integer in network byte order, with length 3.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2171
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2172 @item u32
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2173 @itemx dword
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2174 @itemx long
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2175 Unsigned integer in network byte order, with length 4.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2176 Note: These values may be limited by Emacs' integer implementation limits.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2177
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2178 @item u16r
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2179 @itemx u24r
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2180 @itemx u32r
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2181 Unsigned integer in little endian order, with length 2, 3 and 4, respectively.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2182
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2183 @item str @var{len}
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2184 String of length @var{len}.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2185
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2186 @item strz @var{len}
74952
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2187 Zero-terminated string, in a fixed-size field with length @var{len}.
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2188
75987
9012e6e12d0e (Bindat Spec): Vector types can have optional element type.
Kim F. Storm <storm@cua.dk>
parents: 75250
diff changeset
2189 @item vec @var{len} [@var{type}]
9012e6e12d0e (Bindat Spec): Vector types can have optional element type.
Kim F. Storm <storm@cua.dk>
parents: 75250
diff changeset
2190 Vector of @var{len} elements of type @var{type}, or bytes if not
9012e6e12d0e (Bindat Spec): Vector types can have optional element type.
Kim F. Storm <storm@cua.dk>
parents: 75250
diff changeset
2191 @var{type} is specified.
9012e6e12d0e (Bindat Spec): Vector types can have optional element type.
Kim F. Storm <storm@cua.dk>
parents: 75250
diff changeset
2192 The @var{type} is any of the simple types above, or another vector
9012e6e12d0e (Bindat Spec): Vector types can have optional element type.
Kim F. Storm <storm@cua.dk>
parents: 75250
diff changeset
2193 specified as a list @code{(vec @var{len} [@var{type}])}.
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2194
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2195 @item ip
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2196 Four-byte vector representing an Internet address. For example:
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2197 @code{[127 0 0 1]} for localhost.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2198
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2199 @item bits @var{len}
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2200 List of set bits in @var{len} bytes. The bytes are taken in big
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2201 endian order and the bits are numbered starting with @code{8 *
63560
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
2202 @var{len} @minus{} 1} and ending with zero. For example: @code{bits
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2203 2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2204 @code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2205
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2206 @item (eval @var{form})
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2207 @var{form} is a Lisp expression evaluated at the moment the field is
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2208 unpacked or packed. The result of the evaluation should be one of the
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2209 above-listed type specifications.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2210 @end table
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2211
74970
d278931df0dd (Bindat Spec): Clarify using field names in
Kim F. Storm <storm@cua.dk>
parents: 74952
diff changeset
2212 For a fixed-size field, the length @var{len} is given as an integer
d278931df0dd (Bindat Spec): Clarify using field names in
Kim F. Storm <storm@cua.dk>
parents: 74952
diff changeset
2213 specifying the number of bytes in the field.
d278931df0dd (Bindat Spec): Clarify using field names in
Kim F. Storm <storm@cua.dk>
parents: 74952
diff changeset
2214
d278931df0dd (Bindat Spec): Clarify using field names in
Kim F. Storm <storm@cua.dk>
parents: 74952
diff changeset
2215 When the length of a field is not fixed, it typically depends on the
d278931df0dd (Bindat Spec): Clarify using field names in
Kim F. Storm <storm@cua.dk>
parents: 74952
diff changeset
2216 value of a preceding field. In this case, the length @var{len} can be
d278931df0dd (Bindat Spec): Clarify using field names in
Kim F. Storm <storm@cua.dk>
parents: 74952
diff changeset
2217 given either as a list @code{(@var{name} ...)} identifying a
d278931df0dd (Bindat Spec): Clarify using field names in
Kim F. Storm <storm@cua.dk>
parents: 74952
diff changeset
2218 @dfn{field name} in the format specified for @code{bindat-get-field}
d278931df0dd (Bindat Spec): Clarify using field names in
Kim F. Storm <storm@cua.dk>
parents: 74952
diff changeset
2219 below, or by an expression @code{(eval @var{form})} where @var{form}
d278931df0dd (Bindat Spec): Clarify using field names in
Kim F. Storm <storm@cua.dk>
parents: 74952
diff changeset
2220 should evaluate to an integer, specifying the field length.
74952
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2221
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2222 A field specification generally has the form @code{([@var{name}]
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2223 @var{handler})}. The square braces indicate that @var{name} is
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2224 optional. (Don't use names that are symbols meaningful as type
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2225 specifications (above) or handler specifications (below), since that
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2226 would be ambiguous.) @var{name} can be a symbol or the expression
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2227 @code{(eval @var{form})}, in which case @var{form} should evaluate to
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2228 a symbol.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2229
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2230 @var{handler} describes how to unpack or pack the field and can be one
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2231 of the following:
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2232
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2233 @table @code
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2234 @item @var{type}
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2235 Unpack/pack this field according to the type specification @var{type}.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2236
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2237 @item eval @var{form}
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2238 Evaluate @var{form}, a Lisp expression, for side-effect only. If the
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2239 field name is specified, the value is bound to that field name.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2240
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2241 @item fill @var{len}
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2242 Skip @var{len} bytes. In packing, this leaves them unchanged,
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2243 which normally means they remain zero. In unpacking, this means
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2244 they are ignored.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2245
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2246 @item align @var{len}
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2247 Skip to the next multiple of @var{len} bytes.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2248
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2249 @item struct @var{spec-name}
63560
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
2250 Process @var{spec-name} as a sub-specification. This describes a
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2251 structure nested within another structure.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2252
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2253 @item union @var{form} (@var{tag} @var{spec})@dots{}
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2254 @c ??? I don't see how one would actually use this.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2255 @c ??? what kind of expression would be useful for @var{form}?
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2256 Evaluate @var{form}, a Lisp expression, find the first @var{tag}
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2257 that matches it, and process its associated data layout specification
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2258 @var{spec}. Matching can occur in one of three ways:
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2259
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2260 @itemize
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2261 @item
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2262 If a @var{tag} has the form @code{(eval @var{expr})}, evaluate
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2263 @var{expr} with the variable @code{tag} dynamically bound to the value
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2264 of @var{form}. A non-@code{nil} result indicates a match.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2265
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2266 @item
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2267 @var{tag} matches if it is @code{equal} to the value of @var{form}.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2268
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2269 @item
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2270 @var{tag} matches unconditionally if it is @code{t}.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2271 @end itemize
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2272
71394
4b4feab31516 (Bindat Spec): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 71035
diff changeset
2273 @item repeat @var{count} @var{field-specs}@dots{}
4b4feab31516 (Bindat Spec): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 71035
diff changeset
2274 Process the @var{field-specs} recursively, in order, then repeat
4b4feab31516 (Bindat Spec): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 71035
diff changeset
2275 starting from the first one, processing all the specs @var{count}
74952
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2276 times overall. The @var{count} is given using the same formats as a
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2277 field length---if an @code{eval} form is used, it is evaluated just once.
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2278 For correct operation, each spec in @var{field-specs} must include a name.
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2279 @end table
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2280
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2281 For the @code{(eval @var{form})} forms used in a bindat specification,
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2282 the @var{form} can access and update these dynamically bound variables
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2283 during evaluation:
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2284
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2285 @table @code
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2286 @item last
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2287 Value of the last field processed.
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2288
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2289 @item bindat-raw
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2290 The data as a byte array.
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2291
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2292 @item bindat-idx
75050
27f521750ce8 (Bindat Spec): Fix Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 74970
diff changeset
2293 Current index (within @code{bindat-raw}) for unpacking or packing.
74952
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2294
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2295 @item struct
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2296 The alist containing the structured data that have been unpacked so
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2297 far, or the entire structure being packed. You can use
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2298 @code{bindat-get-field} to access specific fields of this structure.
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2299
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2300 @item count
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2301 @itemx index
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2302 Inside a @code{repeat} block, these contain the maximum number of
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2303 repetitions (as specified by the @var{count} parameter), and the
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2304 current repetition number (counting from 0). Setting @code{count} to
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2305 zero will terminate the inner-most repeat block after the current
0e7b380a6c47 (Bindat Spec): Explain eval forms and lengths better.
Kim F. Storm <storm@cua.dk>
parents: 72723
diff changeset
2306 repetition has completed.
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2307 @end table
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2308
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2309 @node Bindat Functions
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2310 @subsection Functions to Unpack and Pack Bytes
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2311
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2312 In the following documentation, @var{spec} refers to a data layout
71035
3574bac9e172 (Bindat Functions): Rename `pos' and `raw-data' to
Kim F. Storm <storm@cua.dk>
parents: 71013
diff changeset
2313 specification, @code{bindat-raw} to a byte array, and @var{struct} to an
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2314 alist representing unpacked field data.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2315
71035
3574bac9e172 (Bindat Functions): Rename `pos' and `raw-data' to
Kim F. Storm <storm@cua.dk>
parents: 71013
diff changeset
2316 @defun bindat-unpack spec bindat-raw &optional bindat-idx
70907
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2317 This function unpacks data from the unibyte string or byte
71035
3574bac9e172 (Bindat Functions): Rename `pos' and `raw-data' to
Kim F. Storm <storm@cua.dk>
parents: 71013
diff changeset
2318 array @code{bindat-raw}
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2319 according to @var{spec}. Normally this starts unpacking at the
71035
3574bac9e172 (Bindat Functions): Rename `pos' and `raw-data' to
Kim F. Storm <storm@cua.dk>
parents: 71013
diff changeset
2320 beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2321 specifies a zero-based starting position to use instead.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2322
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2323 The value is an alist or nested alist in which each element describes
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2324 one unpacked field.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2325 @end defun
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2326
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2327 @defun bindat-get-field struct &rest name
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2328 This function selects a field's data from the nested alist
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2329 @var{struct}. Usually @var{struct} was returned by
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2330 @code{bindat-unpack}. If @var{name} corresponds to just one argument,
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2331 that means to extract a top-level field value. Multiple @var{name}
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2332 arguments specify repeated lookup of sub-structures. An integer name
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2333 acts as an array index.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2334
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2335 For example, if @var{name} is @code{(a b 2 c)}, that means to find
67044
a40ac89f9800 (Bindat Functions): Say "third" to refer to zero-based index "2".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 66152
diff changeset
2336 field @code{c} in the third element of subfield @code{b} of field
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2337 @code{a}. (This corresponds to @code{struct.a.b[2].c} in C.)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2338 @end defun
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2339
70985
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2340 Although packing and unpacking operations change the organization of
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2341 data (in memory), they preserve the data's @dfn{total length}, which is
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2342 the sum of all the fields' lengths, in bytes. This value is not
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2343 generally inherent in either the specification or alist alone; instead,
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2344 both pieces of information contribute to its calculation. Likewise, the
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2345 length of a string or array being unpacked may be longer than the data's
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2346 total length as described by the specification.
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2347
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2348 @defun bindat-length spec struct
70985
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2349 This function returns the total length of the data in @var{struct},
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2350 according to @var{spec}.
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2351 @end defun
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2352
71035
3574bac9e172 (Bindat Functions): Rename `pos' and `raw-data' to
Kim F. Storm <storm@cua.dk>
parents: 71013
diff changeset
2353 @defun bindat-pack spec struct &optional bindat-raw bindat-idx
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2354 This function returns a byte array packed according to @var{spec} from
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2355 the data in the alist @var{struct}. Normally it creates and fills a
71035
3574bac9e172 (Bindat Functions): Rename `pos' and `raw-data' to
Kim F. Storm <storm@cua.dk>
parents: 71013
diff changeset
2356 new byte array starting at the beginning. However, if @var{bindat-raw}
70907
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2357 is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to
71035
3574bac9e172 (Bindat Functions): Rename `pos' and `raw-data' to
Kim F. Storm <storm@cua.dk>
parents: 71013
diff changeset
2358 pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting
3574bac9e172 (Bindat Functions): Rename `pos' and `raw-data' to
Kim F. Storm <storm@cua.dk>
parents: 71013
diff changeset
2359 offset for packing into @code{bindat-raw}.
3574bac9e172 (Bindat Functions): Rename `pos' and `raw-data' to
Kim F. Storm <storm@cua.dk>
parents: 71013
diff changeset
2360
3574bac9e172 (Bindat Functions): Rename `pos' and `raw-data' to
Kim F. Storm <storm@cua.dk>
parents: 71013
diff changeset
2361 When pre-allocating, you should make sure @code{(length @var{bindat-raw})}
70985
183e16c7e0b2 (Bindat Functions): Explain term "total length".
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70907
diff changeset
2362 meets or exceeds the total length to avoid an out-of-range error.
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2363 @end defun
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2364
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2365 @defun bindat-ip-to-string ip
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2366 Convert the Internet address vector @var{ip} to a string in the usual
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2367 dotted notation.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2368
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2369 @example
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2370 (bindat-ip-to-string [127 0 0 1])
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2371 @result{} "127.0.0.1"
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2372 @end example
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2373 @end defun
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2374
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2375 @node Bindat Examples
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2376 @subsection Examples of Byte Unpacking and Packing
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2377
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2378 Here is a complete example of byte unpacking and packing:
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2379
63569
bd65461db3b8 (Bindat Examples): Move @lisp to beginning of line. (Whitespace change.)
Luc Teirlinck <teirllm@auburn.edu>
parents: 63568
diff changeset
2380 @lisp
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2381 (defvar fcookie-index-spec
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2382 '((:version u32)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2383 (:count u32)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2384 (:longest u32)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2385 (:shortest u32)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2386 (:flags u32)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2387 (:delim u8)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2388 (:ignored fill 3)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2389 (:offset repeat (:count)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2390 (:foo u32)))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2391 "Description of a fortune cookie index file's contents.")
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2392
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2393 (defun fcookie (cookies &optional index)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2394 "Display a random fortune cookie from file COOKIES.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2395 Optional second arg INDEX specifies the associated index
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2396 filename, which is by default constructed by appending
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2397 \".dat\" to COOKIES. Display cookie text in possibly
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2398 new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2399 is COOKIES without the directory part."
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2400 (interactive "fCookies file: ")
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2401 (let* ((info (with-temp-buffer
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2402 (insert-file-contents-literally
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2403 (or index (concat cookies ".dat")))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2404 (bindat-unpack fcookie-index-spec
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2405 (buffer-string))))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2406 (sel (random (bindat-get-field info :count)))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2407 (beg (cdar (bindat-get-field info :offset sel)))
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2408 (end (or (cdar (bindat-get-field info
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2409 :offset (1+ sel)))
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2410 (nth 7 (file-attributes cookies)))))
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2411 (switch-to-buffer
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2412 (get-buffer-create
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2413 (format "*Fortune Cookie: %s*"
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2414 (file-name-nondirectory cookies))))
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2415 (erase-buffer)
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2416 (insert-file-contents-literally
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2417 cookies nil beg (- end 3))))
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2418
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2419 (defun fcookie-create-index (cookies &optional index delim)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2420 "Scan file COOKIES, and write out its index file.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2421 Optional second arg INDEX specifies the index filename,
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2422 which is by default constructed by appending \".dat\" to
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2423 COOKIES. Optional third arg DELIM specifies the unibyte
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2424 character which, when found on a line of its own in
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2425 COOKIES, indicates the border between entries."
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2426 (interactive "fCookies file: ")
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2427 (setq delim (or delim ?%))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2428 (let ((delim-line (format "\n%c\n" delim))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2429 (count 0)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2430 (max 0)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2431 min p q len offsets)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2432 (unless (= 3 (string-bytes delim-line))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2433 (error "Delimiter cannot be represented in one byte"))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2434 (with-temp-buffer
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2435 (insert-file-contents-literally cookies)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2436 (while (and (setq p (point))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2437 (search-forward delim-line (point-max) t)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2438 (setq len (- (point) 3 p)))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2439 (setq count (1+ count)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2440 max (max max len)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2441 min (min (or min max) len)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2442 offsets (cons (1- p) offsets))))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2443 (with-temp-buffer
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2444 (set-buffer-multibyte nil)
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2445 (insert
70907
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2446 (bindat-pack
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2447 fcookie-index-spec
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2448 `((:version . 2)
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2449 (:count . ,count)
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2450 (:longest . ,max)
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2451 (:shortest . ,min)
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2452 (:flags . 0)
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2453 (:delim . ,delim)
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2454 (:offset . ,(mapcar (lambda (o)
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2455 (list (cons :foo o)))
4f3bfa0df084 (Bindat Functions): Say "unibyte string"
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70603
diff changeset
2456 (nreverse offsets))))))
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2457 (let ((coding-system-for-write 'raw-text-unix))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2458 (write-file (or index (concat cookies ".dat")))))))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2459 @end lisp
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2460
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2461 Following is an example of defining and unpacking a complex structure.
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2462 Consider the following C structures:
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2463
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2464 @example
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2465 struct header @{
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2466 unsigned long dest_ip;
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2467 unsigned long src_ip;
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2468 unsigned short dest_port;
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2469 unsigned short src_port;
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2470 @};
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2471
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2472 struct data @{
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2473 unsigned char type;
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2474 unsigned char opcode;
75992
035ff8761729 More fixes to bindat example.
Kim F. Storm <storm@cua.dk>
parents: 75987
diff changeset
2475 unsigned short length; /* In network byte order */
63560
35d12dd91d05 Fix typos.
Luc Teirlinck <teirllm@auburn.edu>
parents: 63542
diff changeset
2476 unsigned char id[8]; /* null-terminated string */
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2477 unsigned char data[/* (length + 3) & ~3 */];
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2478 @};
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2479
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2480 struct packet @{
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2481 struct header header;
75992
035ff8761729 More fixes to bindat example.
Kim F. Storm <storm@cua.dk>
parents: 75987
diff changeset
2482 unsigned long counters[2]; /* In little endian order */
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2483 unsigned char items;
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2484 unsigned char filler[3];
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2485 struct data item[/* items */];
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2486
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2487 @};
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2488 @end example
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2489
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2490 The corresponding data layout specification:
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2491
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2492 @lisp
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2493 (setq header-spec
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2494 '((dest-ip ip)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2495 (src-ip ip)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2496 (dest-port u16)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2497 (src-port u16)))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2498
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2499 (setq data-spec
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2500 '((type u8)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2501 (opcode u8)
75992
035ff8761729 More fixes to bindat example.
Kim F. Storm <storm@cua.dk>
parents: 75987
diff changeset
2502 (length u16) ;; network byte order
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2503 (id strz 8)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2504 (data vec (length))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2505 (align 4)))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2506
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2507 (setq packet-spec
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2508 '((header struct header-spec)
75992
035ff8761729 More fixes to bindat example.
Kim F. Storm <storm@cua.dk>
parents: 75987
diff changeset
2509 (counters vec 2 u32r) ;; little endian order
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2510 (items u8)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2511 (fill 3)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2512 (item repeat (items)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2513 (struct data-spec))))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2514 @end lisp
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2515
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2516 A binary data representation:
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2517
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2518 @lisp
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2519 (setq binary-data
75992
035ff8761729 More fixes to bindat example.
Kim F. Storm <storm@cua.dk>
parents: 75987
diff changeset
2520 [ 192 168 1 100 192 168 1 101 01 28 21 32
035ff8761729 More fixes to bindat example.
Kim F. Storm <storm@cua.dk>
parents: 75987
diff changeset
2521 160 134 1 0 5 1 0 0 2 0 0 0
035ff8761729 More fixes to bindat example.
Kim F. Storm <storm@cua.dk>
parents: 75987
diff changeset
2522 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
035ff8761729 More fixes to bindat example.
Kim F. Storm <storm@cua.dk>
parents: 75987
diff changeset
2523 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2524 @end lisp
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2525
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2526 The corresponding decoded structure:
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2527
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2528 @lisp
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2529 (setq decoded (bindat-unpack packet-spec binary-data))
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2530 @result{}
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2531 ((header
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2532 (dest-ip . [192 168 1 100])
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2533 (src-ip . [192 168 1 101])
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2534 (dest-port . 284)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2535 (src-port . 5408))
75992
035ff8761729 More fixes to bindat example.
Kim F. Storm <storm@cua.dk>
parents: 75987
diff changeset
2536 (counters . [100000 261])
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2537 (items . 2)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2538 (item ((data . [1 2 3 4 5])
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2539 (id . "ABCDEF")
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2540 (length . 5)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2541 (opcode . 3)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2542 (type . 2))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2543 ((data . [6 7 8 9 10 11 12])
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2544 (id . "BCDEFG")
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2545 (length . 7)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2546 (opcode . 4)
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2547 (type . 1))))
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2548 @end lisp
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2549
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2550 Fetching data from this structure:
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2551
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2552 @lisp
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63569
diff changeset
2553 (bindat-get-field decoded 'item 1 'id)
63542
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2554 @result{} "BCDEFG"
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2555 @end lisp
e8205c5fb59b (Byte Packing): New node.
Richard M. Stallman <rms@gnu.org>
parents: 62370
diff changeset
2556
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51994
diff changeset
2557 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51994
diff changeset
2558 arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51994
diff changeset
2559 @end ignore