annotate lispref/processes.texi @ 49129:6b546e74af50

sort-regexp-fields update
author Karl Berry <karl@gnu.org>
date Thu, 09 Jan 2003 23:29:54 +0000
parents dd413d2af8ad
children 23a1cea22d13
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.
27189
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
4 @c 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
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 called a ``process''. Lisp programs can use this object to communicate
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.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 @node Subprocess Creation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 @section Functions that Create Subprocesses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 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
57 a program. One of them, @code{start-process}, creates an asynchronous
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 process and returns a process object (@pxref{Asynchronous Processes}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 The other two, @code{call-process} and @code{call-process-region},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 create a synchronous process and do not return a process object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 (@pxref{Synchronous Processes}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
63 Synchronous and asynchronous processes are explained in the following
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 sections. Since the three functions are all called in a similar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 fashion, their common arguments are described here.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 @cindex execute program
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 @cindex @code{PATH} environment variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 @cindex @code{HOME} environment variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 In all cases, the function's @var{program} argument specifies the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 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
72 cannot be executed. If the file name is relative, the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 @code{exec-path} contains a list of directories to search. Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 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
75 the environment variable @code{PATH}. The standard file name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 in @code{exec-path}, but environment variable substitutions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 (@samp{$HOME}, etc.) are not recognized; use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 @code{substitute-in-file-name} to perform them (@pxref{File Name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 Expansion}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 Each of the subprocess-creating functions has a @var{buffer-or-name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 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
84 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
85 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
86 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
87 handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
88 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
89 same buffer because their output would be intermixed randomly.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @cindex program arguments
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 All three of the subprocess-creating functions have a @code{&rest}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 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
94 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
95 characters and other shell constructs have no special meanings in these
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
96 strings, since the whole strings are passed directly to the specified
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
97 program.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7411
diff changeset
99 @strong{Please note:} The argument @var{program} contains only the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 name of the program; it may not contain any command-line arguments. You
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 must use @var{args} to provide those.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 The subprocess gets its current directory from the value of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @code{default-directory} (@pxref{File Name Expansion}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 @cindex environment variables, subprocesses
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
107 The subprocess inherits its environment from Emacs, but you can
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 specify overrides for it with @code{process-environment}. @xref{System
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 Environment}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 @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
112 @pindex movemail
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
113 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
114 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
115 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
116 Rmail uses it to fetch new mail from an inbox.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 @end defvar
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 @defopt exec-path
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 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
121 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
122 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
123 directory (which is the value of @code{default-directory}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 @cindex program directories
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 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
127 @code{start-process} when the @var{program} argument is not an absolute
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 file name.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
131 @node Shell Arguments
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
132 @section Shell Arguments
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
133
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
134 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
135 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
136 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
137 gives special treatment to certain characters, and if these characters
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
138 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
139 characters, use the function @code{shell-quote-argument}:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
140
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
141 @defun shell-quote-argument argument
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
142 This function returns a string which represents, in shell syntax,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
143 an argument whose actual contents are @var{argument}. It should
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
144 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
145 and then pass it to a shell for execution.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
146
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
147 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
148 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
149 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
150 function.
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 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
153 ;; @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
154 (shell-quote-argument "foo > bar")
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
155 @result{} "foo\\ \\>\\ bar"
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
156
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
157 ;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
158 (shell-quote-argument "foo > bar")
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
159 @result{} "\"foo > bar\""
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
160 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
161
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
162 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
163 a shell command:
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 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
166 (concat "diff -c "
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
167 (shell-quote-argument oldfile)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
168 " "
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
169 (shell-quote-argument newfile))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
170 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
171 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
172
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @node Synchronous Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 @section Creating a Synchronous Process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @cindex synchronous subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 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
178 process to terminate before continuing. Starting Dired on GNU or
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
179 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
180 @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
181 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
182 slightly. Because the process is synchronous, the entire directory
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
183 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
184
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 While Emacs waits for the synchronous subprocess to terminate, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 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
187 the subprocess with a @code{SIGINT} signal; but it waits until the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 subprocess actually terminates before quitting. If during that time the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 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
190 @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
191 other processes doesn't work). @xref{Quitting}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
193 The synchronous subprocess functions return an indication of how the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
194 process terminated.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
195
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
196 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
197 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
198 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
199 system, much like text written into a file. @xref{Coding Systems}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
201 @defun call-process program &optional infile destination display &rest args
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 This function calls @var{program} in a separate process and waits for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 it to finish.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 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
206 @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
207 The argument @var{destination} says where to put the process output.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
208 Here are the possibilities:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
209
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
210 @table @asis
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
211 @item a buffer
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
212 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
213 standard output stream and the standard error stream of the process.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
214
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
215 @item a string
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
216 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
217
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
218 @item @code{t}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
219 Insert the output in the current buffer, before point.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
220
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
221 @item @code{nil}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
222 Discard the output.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
224 @item 0
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
225 Discard the output, and return @code{nil} immediately without waiting
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
226 for the subprocess to finish.
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 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
229 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
230 Emacs is essentially finished with the subprocess as soon as this
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
231 function returns.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
232
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
233 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
234 work there.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
235
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
236 @item @code{(@var{real-destination} @var{error-destination})}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
237 Keep the standard output stream separate from the standard error stream;
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
238 deal with the ordinary output as specified by @var{real-destination},
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
239 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
240 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
241 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
242 string specifies a file name to redirect error output into.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
243
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
244 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
245 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
246 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
247 buffer.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
248 @end table
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 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
251 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
252 for decoding output is @code{undecided}, meaning deduce the encoding
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
253 from the actual data, then redisplay sometimes cannot continue once
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
254 non-@sc{ascii} characters are encountered. There are fundamental
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
255 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
256
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
257 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
258 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
259 buffer in the normal course of events.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 The remaining arguments, @var{args}, are strings that specify command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 line arguments for the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 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
265 wait) indicates the reason for process termination. A number gives the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 exit status of the subprocess; 0 means success, and any other value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 means failure. If the process terminated with a signal,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 @code{call-process} returns a string describing the signal.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 In the examples below, the buffer @samp{foo} is current.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 (call-process "pwd" nil t)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
275 @result{} 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 /usr/user/lewis/manual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 @end group
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 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
284 @result{} 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 ---------- Buffer: bar ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 ---------- Buffer: bar ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
293 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
294 be found in the definition of @code{insert-directory}:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
298 (call-process insert-directory-program nil t nil @var{switches}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 (if full-directory-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 (concat (file-name-as-directory file) ".")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 file))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
306 @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
307 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
308 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
309 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
310 @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
311 buffer in place of the input.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
313 The arguments @var{destination} and @var{display} control what to do
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 with the output from the subprocess, and whether to update the display
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 as it comes in. For details, see the description of
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
316 @code{call-process}, above. If @var{destination} is the integer 0,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @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
318 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
319 works if asynchronous subprocesses are supported).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 The remaining arguments, @var{args}, are strings that specify command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 line arguments for the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 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
325 @code{call-process}: @code{nil} if you told it to return without
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 waiting; otherwise, a number or string which indicates how the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 subprocess terminated.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 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
330 @code{cat} utility, with standard input being the first five characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 standard input into its standard output. Since the argument
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
333 @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
334 buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 input@point{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 (call-process-region 1 6 "cat" nil t)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
345 @result{} 0
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 inputinput@point{}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 The @code{shell-command-on-region} command uses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @code{call-process-region} like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 (call-process-region
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 start end
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 shell-file-name ; @r{Name of program.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 nil ; @r{Do not delete region.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 buffer ; @r{Send output to @code{buffer}.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 nil ; @r{No redisplay during output.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 "-c" command) ; @r{Arguments for the shell.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
369 @defun shell-command-to-string command
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
370 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
371 then returns the command's output as a string.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
372 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
373
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 @node Asynchronous Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 @section Creating an Asynchronous Process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @cindex asynchronous subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
378 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
379 both continue running immediately. The process thereafter runs
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
380 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
381 using the functions described in the following sections. However,
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
382 communication is only partially asynchronous: Emacs sends data to the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
383 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
384 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
385 delay.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
386
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
387 Here we describe how to create an asynchronous process.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 @defun start-process name buffer-or-name program &rest args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 This function creates a new asynchronous subprocess and starts the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 program @var{program} running in it. It returns a process object that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 stands for the new subprocess in Lisp. The argument @var{name}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 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
394 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
395 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
396 associate with the process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 The remaining arguments, @var{args}, are strings that specify command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 line arguments for the program.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 In the example below, the first process is started and runs (rather,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 sleeps) for 100 seconds. Meanwhile, the second process is started, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 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
404 inserts the directory listing at the end of the buffer @samp{foo},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 before the first process finishes. Then it finishes, and a message to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 that effect is inserted in the buffer. Much later, the first process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 finishes, and another message is inserted in the buffer for it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 (start-process "my-process" "foo" "sleep" "100")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 @result{} #<process my-process>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 @end group
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 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 @result{} #<process my-process<1>>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 total 2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 Process my-process<1> finished
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 Process my-process finished
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 ---------- Buffer: foo ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 @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
433 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
434 to execute the specified command. The argument @var{command} is a shell
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 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
436 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
437 use.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
438
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
439 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
440 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
441 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
442 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
443 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
444 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
445 Arguments}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 @defvar process-connection-type
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @cindex pipes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @cindex @sc{pty}s
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 This variable controls the type of device used to communicate with
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
452 asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
453 used, when available. Otherwise, pipes are used.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @sc{pty}s are usually preferable for processes visible to the user, as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 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
457 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
458 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
459 often better to use a pipe, because they are more efficient. In
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
460 addition, the total number of @sc{pty}s is limited on many systems and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
461 it is good not to waste them.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
463 The value of @code{process-connection-type} takes effect when
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 @code{start-process} is called. So you can specify how to communicate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 with one subprocess by binding the variable around the call to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 @code{start-process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 (let ((process-connection-type nil)) ; @r{Use a pipe.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 (start-process @dots{}))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 @end smallexample
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
474
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
475 To determine whether a given subprocess actually got a pipe or a
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
476 @sc{pty}, use the function @code{process-tty-name} (@pxref{Process
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
477 Information}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 @node Deleting Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 @section Deleting Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 @cindex deleting processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 @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
485 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
486 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
487 at any time. If you delete a terminated process explicitly before it
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
488 is deleted automatically, no harm results. Deletion of a running
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
489 process sends a signal to terminate it (and its child processes if
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
490 any), and calls the process sentinel if it has one.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
492 @code{get-buffer-process} and @code{process-list} do not remember a
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
493 deleted process, but the process object itself continues to exist as
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
494 long as other Lisp objects point to it. All the Lisp primitives that
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
495 work on process objects accept deleted processes, but those that do
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
496 I/O or send signals will report an error. The process mark continues
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
497 to point to the same place as before, usually into a buffer where
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
498 output from the process was being inserted.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
500 @defopt delete-exited-processes
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 This variable controls automatic deletion of processes that have
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 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
503 @code{nil}, then they continue to exist until the user runs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 @code{list-processes}. Otherwise, they are deleted immediately after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505 they exit.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
506 @end defopt
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508 @defun delete-process name
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
509 This function deletes the process associated with @var{name}, killing
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
510 it with a @code{SIGKILL} signal. The argument @var{name} may be a
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
511 process, the name of a process, a buffer, or the name of a buffer.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
512 Calling @code{delete-process} on a running process terminates it,
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
513 updates the process status, and runs the sentinel (if any) immediately.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
514 If the process has already terminated, calling @code{delete-process}
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
515 has no effect on its status, or on the running of its sentinel (which
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
516 will happen sooner or later).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 (delete-process "*shell*")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 @node Process Information
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 @section Process Information
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 Several functions return information about processes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 @code{list-processes} is provided for interactive use.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 @deffn Command list-processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 This command displays a listing of all living processes. In addition,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 it finally deletes any process whose status was @samp{Exited} or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 @samp{Signaled}. It returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 @defun process-list
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 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
540
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 (process-list)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 @result{} (#<process display-time> #<process shell>)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 @defun get-process name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 This function returns the process named @var{name}, or @code{nil} if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 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
552
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 (get-process "shell")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 @result{} #<process shell>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 @defun process-command process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 This function returns the command that was executed to start
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 @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
564 program executed and the rest of the strings being the arguments that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 were given to the program.
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 (process-command (get-process "shell"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 @result{} ("/bin/csh" "-i")
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
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 @defun process-id process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 This function returns the @sc{pid} of @var{process}. This is an
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
577 integer that distinguishes the process @var{process} from all other
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 processes running on the same computer at the current time. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @sc{pid} of a process is chosen by the operating system kernel when the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 process is started and remains constant as long as the process exists.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @end defun
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 @defun process-name process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 This function returns the name of @var{process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
587 @defun process-contact process
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
588 This function returns @code{t} for an ordinary child process, and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
589 @code{(@var{hostname} @var{service})} for a net connection
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
590 (@pxref{Network}).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
591 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
592
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 @defun process-status process-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 This function returns the status of @var{process-name} as a symbol.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 The argument @var{process-name} must be a process, a buffer, a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 process name (string) or a buffer name (string).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
598 The possible values for an actual subprocess are:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 @item run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 for a process that is running.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 @item stop
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 for a process that is stopped but continuable.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 @item exit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 for a process that has exited.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607 @item signal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 for a process that has received a fatal signal.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 @item open
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 for a network connection that is open.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 @item closed
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 for a network connection that is closed. Once a connection
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 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
614 a new connection to the same place.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 @item nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 if @var{process-name} is not the name of an existing process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 (process-status "shell")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 @result{} run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 (process-status (get-buffer "*shell*"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 @result{} run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 x
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 @result{} #<process xx<1>>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 (process-status x)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 @result{} exit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 For a network connection, @code{process-status} returns one of the symbols
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @code{open} or @code{closed}. The latter means that the other side
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 closed the connection, or Emacs did @code{delete-process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 @defun process-exit-status process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642 This function returns the exit status of @var{process} or the signal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 number that killed it. (Use the result of @code{process-status} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 determine which of those it is.) If @var{process} has not yet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 terminated, the value is 0.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
648 @defun process-tty-name process
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
649 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
650 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
651 instead of a terminal (see @code{process-connection-type} in
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
652 @ref{Asynchronous Processes}).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
653 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
654
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
655 @defun process-coding-system process
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
656 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
657 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
658 @var{process} (@pxref{Coding Systems}). The value has this form:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
659
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
660 @example
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
661 (@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
662 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
663 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
664
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
665 @defun set-process-coding-system process decoding-system encoding-system
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
666 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
667 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
668 decode subprocess output, and @var{encoding-system} to encode subprocess
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
669 input.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
670 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
671
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 @node Input to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 @section Sending Input to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @cindex process input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 Asynchronous subprocesses receive input when it is sent to them by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 Emacs, which is done with the functions in this section. You must
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 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
679 data appears on the ``standard input'' of the subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 Some operating systems have limited space for buffered input in a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682 @sc{pty}. On these systems, Emacs sends an @sc{eof} periodically amidst
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 the other characters, to force them through. For most programs,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684 these @sc{eof}s do no harm.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
686 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
687 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
688 @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
689 (@pxref{Process Information}). Otherwise, the coding system comes from
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
690 @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
691 the defaulting mechanism (@pxref{Default Coding Systems}).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
692
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
693 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
694 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
695 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
696 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
697 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
698 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
699
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700 @defun process-send-string process-name string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 This function sends @var{process-name} the contents of @var{string} as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 standard input. The argument @var{process-name} must be a process or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703 the name of a process. If it is @code{nil}, the current buffer's
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 process is used.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 The function returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 (process-send-string "shell<1>" "ls\n")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 ---------- Buffer: *shell* ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 ...
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 introduction.texi syntax-tables.texi~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 introduction.texi~ text.texi
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 introduction.txt text.texi~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 ...
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 ---------- Buffer: *shell* ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
727 @defun process-send-region process-name start end
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 This function sends the text in the region defined by @var{start} and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 @var{end} as standard input to @var{process-name}, which is a process or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 a process name. (If it is @code{nil}, the current buffer's process is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 used.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 An error is signaled unless both @var{start} and @var{end} are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 integers or markers that indicate positions in the current buffer. (It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 is unimportant which number is larger.)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
736 @end defun
6558
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 @defun process-send-eof &optional process-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 This function makes @var{process-name} see an end-of-file in its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740 input. The @sc{eof} comes after any text already sent to it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 If @var{process-name} is not supplied, or if it is @code{nil}, then
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 this function sends the @sc{eof} to the current buffer's process. An
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 error is signaled if the current buffer has no process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 The function returns @var{process-name}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 (process-send-eof "shell")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 @result{} "shell"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
756 @defun process-running-child-p process
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
757 @tindex process-running-child-p process
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
758 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
759 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
760 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
761 that this is not so.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
762 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
763
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 @node Signals to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 @section Sending Signals to Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 @cindex process signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 @cindex sending signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768 @cindex signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 @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
771 activities. There are several different signals, each with its own
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772 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
773 system. For example, the signal @code{SIGINT} means that the user has
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774 typed @kbd{C-c}, or that some analogous thing has happened.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776 Each signal has a standard effect on the subprocess. Most signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 kill the subprocess, but some stop or resume execution instead. Most
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 signals can optionally be handled by programs; if the program handles
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779 the signal, then we can say nothing in general about its effects.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 You can send signals explicitly by calling the functions in this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782 section. Emacs also sends signals automatically at certain times:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783 killing a buffer sends a @code{SIGHUP} signal to all its associated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 processes; killing Emacs sends a @code{SIGHUP} signal to all remaining
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 processes. (@code{SIGHUP} is a signal that usually indicates that the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 user hung up the phone.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 Each of the signal-sending functions takes two optional arguments:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789 @var{process-name} and @var{current-group}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 The argument @var{process-name} must be either a process, the name of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 one, or @code{nil}. If it is @code{nil}, the process defaults to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 process associated with the current buffer. An error is signaled if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 @var{process-name} does not identify a process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 The argument @var{current-group} is a flag that makes a difference
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 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
798 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
799 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
800 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
801 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
802 the immediate subprocess of Emacs. If the subprocess is a job-control
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 shell, this is the shell itself.
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 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
806 communicate with the subprocess, because the operating system does not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807 support the distinction in the case of pipes. For the same reason,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 job-control shells won't work when a pipe is used. See
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 @code{process-connection-type} in @ref{Asynchronous Processes}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 @defun interrupt-process &optional process-name current-group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812 This function interrupts the process @var{process-name} by sending the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814 character'' (normally @kbd{C-c} on some systems, and @code{DEL} on
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 others) sends this signal. When the argument @var{current-group} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 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
817 on the terminal by which Emacs talks to the subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 @defun kill-process &optional process-name current-group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821 This function kills the process @var{process-name} by sending the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 signal @code{SIGKILL}. This signal kills the subprocess immediately,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823 and cannot be handled by the subprocess.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 @defun quit-process &optional process-name current-group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 This function sends the signal @code{SIGQUIT} to the process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 @var{process-name}. This signal is the one sent by the ``quit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 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
830 Emacs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 @end defun
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 @defun stop-process &optional process-name current-group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 This function stops the process @var{process-name} by sending the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 execution.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
838 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
839 (usually @kbd{C-z}) normally sends this signal. When
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
840 @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
841 ``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
842 subprocess.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 @end defun
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 @defun continue-process &optional process-name current-group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 This function resumes execution of the process @var{process} by sending
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 it the signal @code{SIGCONT}. This presumes that @var{process-name} was
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 stopped previously.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 @defun signal-process pid signal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 This function sends a signal to process @var{pid}, which need not be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 a child of Emacs. The argument @var{signal} specifies which signal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 to send; it should be an integer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 @end defun
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 @node Output from Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 @section Receiving Output from Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 @cindex process output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 @cindex output from processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 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
864 its standard output stream. The output can be inserted in a buffer,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865 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
866 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
867 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
868 discarded.
27259
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
869
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
870 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
871 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
872 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
873 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
874
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
875 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
876 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
877 (@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
878 Output}). This minimizes the problem of timing errors that usually
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
879 plague parallel programming. For example, you can safely create a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
880 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
881 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
882 primitive that waits.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
883
27259
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
884 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
885 streams of the subprocess, because Emacs normally spawns the subprocess
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
886 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
887 you want to keep the output to those streams separate, you should
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
888 redirect one of them to a file--for example, by using an appropriate
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
889 shell command.
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
890
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
891 Subprocess output is normally decoded using a coding system before the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
892 buffer or filter function receives it, much like text read from a file.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
893 You can use @code{set-process-coding-system} to specify which coding
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
894 system to use (@pxref{Process Information}). Otherwise, the coding
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
895 system comes from @code{coding-system-for-read}, if that is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
896 non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
897 Coding Systems}).
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
898
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
899 @strong{Warning:} Coding systems such as @code{undecided} which
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
900 determine the coding system from the data do not work entirely reliably
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
901 with asynchronous subprocess output. This is because Emacs has to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
902 process asynchronous subprocess output in batches, as it arrives. Emacs
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
903 must try to detect the proper coding system from one batch at a time,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
904 and this does not always work. Therefore, if at all possible, use a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
905 coding system which determines both the character code conversion and
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
906 the end of line conversion---that is, one like @code{latin-1-unix},
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
907 rather than @code{undecided} or @code{latin-1}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
908
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 * Process Buffers:: If no filter, output is put in a buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 * Filter Functions:: Filter functions accept output from the process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 * Accepting Output:: Explicitly permitting subprocess output.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 Waiting for subprocess output.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 @node Process Buffers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 @subsection Process Buffers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 A process can (and usually does) have an @dfn{associated buffer},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 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
921 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
922 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
923 normal practice only one process is associated with any given buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924 Many applications of processes also use the buffer for editing input to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 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
926
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 Unless the process has a filter function (@pxref{Filter Functions}),
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 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
929 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
930 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
931 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
932
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933 @defun process-buffer process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 This function returns the associated buffer of the process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 @var{process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 (process-buffer (get-process "shell"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 @result{} #<buffer *shell*>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 @defun process-mark process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 This function returns the process marker for @var{process}, which is the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 marker that says where to insert output from the process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
948
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949 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
950 marker that points nowhere.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 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
953 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
954 successive batches of output are inserted consecutively.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956 Filter functions normally should use this marker in the same fashion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957 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
958 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
959 the end of the following section.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
960
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 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
962 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
963 from previous output.
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
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966 @defun set-process-buffer process buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 This function sets the buffer associated with @var{process} to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 associated with no buffer.
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 @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
973 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
974 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
975 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
976 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
977 (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
978 return.
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
979
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
980 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
981 the same buffer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 (get-buffer-process "*shell*")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 @result{} #<process shell>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990 Killing the process's buffer deletes the process, which kills the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 @node Filter Functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995 @subsection Process Filter Functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996 @cindex filter function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 @cindex process filter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 A process @dfn{filter function} is a function that receives the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 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
1001 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
1002 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
1003 there is no filter.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1005 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
1006 something, because process output arrives only at such times. Emacs
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1007 waits when reading terminal input, in @code{sit-for} and
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1008 @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
1009 (@pxref{Accepting Output}).
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1010
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1011 A filter function must accept two arguments: the associated process
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1012 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
1013 then free to do whatever it chooses with the output.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 Quitting is normally inhibited within a filter function---otherwise,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016 the effect of typing @kbd{C-g} at command level or to quit a user
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 command would be unpredictable. If you want to permit quitting inside a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018 filter function, bind @code{inhibit-quit} to @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019 @xref{Quitting}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1021 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
1022 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
1023 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
1024 @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
1025 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
1026 filter function. @xref{Debugger}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1027
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 Many filter functions sometimes or always insert the text in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029 process's buffer, mimicking the actions of Emacs when there is no
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 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
1031 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
1032 semipermanently, these filter functions must save and restore the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1033 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
1034 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
1035
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038 (defun ordinary-insertion-filter (proc string)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1039 (with-current-buffer (process-buffer proc)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1040 (let ((moving (= (point) (process-mark proc))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1043 (save-excursion
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1044 ;; @r{Insert the text, advancing the process marker.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1045 (goto-char (process-mark proc))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1046 (insert string)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1047 (set-marker (process-mark proc) (point)))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1048 (if moving (goto-char (process-mark proc))))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052 @noindent
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1053 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
1054 @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
1055 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
1056 @code{goto-char}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 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
1059 text arrives, insert the following line just before the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1060 @code{with-current-buffer} construct:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 (display-buffer (process-buffer proc))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1066 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
1067 previously, eliminate the variable @code{moving} and call
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 @code{goto-char} unconditionally.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1070 In earlier Emacs versions, every filter function that did regular
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1071 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
1072 match data. Now Emacs does this automatically for filter functions;
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1073 they never need to do it explicitly. @xref{Match Data}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 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
1076 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
1077 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
1078 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1079 if the buffer is dead.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081 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
1082 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
1083 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
1084 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
1085 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
1086 or more batches of output.
6558
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 set-process-filter process filter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1089 This function gives @var{process} the filter function @var{filter}. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090 @var{filter} is @code{nil}, it gives the process no filter.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1092
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 @defun process-filter process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094 This function returns the filter function of @var{process}, or @code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095 if it has none.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1097
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1098 Here is an example of use of a filter function:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102 (defun keep-output (process output)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 (setq kept (cons output kept)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 @result{} keep-output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107 (setq kept nil)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1108 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111 (set-process-filter (get-process "shell") 'keep-output)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1112 @result{} keep-output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115 (process-send-string "shell" "ls ~/other\n")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117 kept
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1118 @result{} ("lewis@@slug[8] % "
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1121 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 address.txt backup.psf kolstad.psf
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 backup.bib~ david.mss resume-Dec-86.mss~
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124 backup.err david.psf resume-Dec.psf
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125 backup.mss dland syllabus.mss
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126 "
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127 "#backups.mss# backup.mss~ kolstad.mss
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 ")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 @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
1133 Here is another, more realistic example, which demonstrates how to use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 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
1135 there is no filter function:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 ;; @r{and make sure that buffer is shown in some window.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1141 (defun my-process-filter (proc str)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1142 (let ((cur (selected-window))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1143 (pop-up-windows t))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1144 (pop-to-buffer my-shell-buffer)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1147 (goto-char (point-max))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1148 (insert str)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1149 (set-marker (process-mark proc) (point-max))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1150 (select-window cur)))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153 @end ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 @node Accepting Output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156 @subsection Accepting Output from Processes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 Output from asynchronous subprocesses normally arrives only while
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 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
1160 or terminal input. Occasionally it is useful in a Lisp program to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161 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
1162 until output arrives from a process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 @defun accept-process-output &optional process seconds millisec
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165 This function allows Emacs to read pending output from processes. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166 output is inserted in the associated buffers or given to their filter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 functions. If @var{process} is non-@code{nil} then this function does
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168 not return until some output has been received from @var{process}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1169
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1170 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1171 The arguments @var{seconds} and @var{millisec} let you specify timeout
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1172 periods. The former specifies a period measured in seconds and the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 latter specifies one measured in milliseconds. The two time periods
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 thus specified are added together, and @code{accept-process-output}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 returns after that much time whether or not there has been any
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 subprocess output.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1178 The argument @var{seconds} need not be an integer. If it is a floating
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1179 point number, this function waits for a fractional number of seconds.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1180 Some systems support only a whole number of seconds; on these systems,
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1181 @var{seconds} is rounded down.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1182
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183 Not all operating systems support waiting periods other than multiples
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1184 of a second; on those that do not, you get an error if you specify
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185 nonzero @var{millisec}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1186
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187 The function @code{accept-process-output} returns non-@code{nil} if it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188 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
1189 arrived.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190 @end defun
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 @node Sentinels
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193 @section Sentinels: Detecting Process Status Changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194 @cindex process sentinel
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195 @cindex sentinel
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 A @dfn{process sentinel} is a function that is called whenever the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198 associated process changes status for any reason, including signals
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1199 (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
1200 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
1201 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
1202 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
1203 describing the type of event.
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 The string describing the event looks like one of the following:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1206
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207 @itemize @bullet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1208 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1209 @code{"finished\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212 @code{"exited abnormally with code @var{exitcode}\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1213
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215 @code{"@var{name-of-signal}\n"}.
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 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1218 @code{"@var{name-of-signal} (core dumped)\n"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1221 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
1222 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
1223 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
1224 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
1225 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
1226 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1227 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
1228 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
1229 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
1230
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1231 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
1232 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
1233 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
1234 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
1235 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
1236 because the process status can't change again after termination.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1237
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238 Quitting is normally inhibited within a sentinel---otherwise, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 effect of typing @kbd{C-g} at command level or to quit a user command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240 would be unpredictable. If you want to permit quitting inside a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241 sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 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
1244 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
1245 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
1246 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1248 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
1249 automatically, so that it doesn't stop the execution of whatever
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1250 programs was running when the sentinel was started. However, if
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1251 @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
1252 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
1253 sentinel. @xref{Debugger}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10039
diff changeset
1254
44428
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1255 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
1256 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
1257 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
1258 a new sentinel.
7e1a0877a121 Explain that sentinels cannot run recursively.
Richard M. Stallman <rms@gnu.org>
parents: 44345
diff changeset
1259
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1260 In earlier Emacs versions, every sentinel that did regular expression
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1261 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
1262 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
1263 it explicitly. @xref{Match Data}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1264
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 @defun set-process-sentinel process sentinel
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 This function associates @var{sentinel} with @var{process}. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267 @var{sentinel} is @code{nil}, then the process will have no sentinel.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268 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
1269 the process's buffer when the process status changes.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270
44345
d2f43521efb4 New node Query Before Exit broken out of Deleting Processes.
Richard M. Stallman <rms@gnu.org>
parents: 39426
diff changeset
1271 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
1272 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
1273 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
1274
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1275 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277 (defun msg-me (process event)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278 (princ
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1279 (format "Process: %s had the event `%s'" process event)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1280 (set-process-sentinel (get-process "shell") 'msg-me)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1281 @result{} msg-me
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1282 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1283 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1284 (kill-process (get-process "shell"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1285 @print{} Process: #<process shell> had the event `killed'
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1286 @result{} #<process shell>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1287 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1288 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1289 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1290
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1291 @defun process-sentinel process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1292 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
1293 has none.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1294 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1295
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1296 @defun waiting-for-user-input-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1297 While a sentinel or filter function is running, this function returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298 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
1299 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
1300 was not.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1301 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1302
46340
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1303 @node Query Before Exit
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1304 @section Querying Before Exit
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1305
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1306 When Emacs exits, it terminates all its subprocesses by sending them
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1307 the @code{SIGHUP} signal. Because some subprocesses are doing
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1308 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
1309 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
1310 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
1311 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
1312 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
1313
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1314 @tindex process-query-on-exit-flag
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1315 @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
1316 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
1317 @end defun
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1318
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1319 @tindex set-process-query-on-exit-flag
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1320 @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
1321 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
1322 returns @var{flag}.
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1323
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1324 @smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1325 @group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1326 ;; @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
1327 (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
1328 @result{} t
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1329 @end group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1330 @end smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1331 @end defun
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1332
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1333 @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
1334 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
1335 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
1336
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1337 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
1338 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
1339 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
1340 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
1341 @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
1342 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
1343 is like this:
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1344
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1345 @smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1346 @group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1347 ;; @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
1348 (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
1349 @end group
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1350 @end smallexample
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1351 @end defun
dd413d2af8ad Move the node Query Before Exit down.
Richard M. Stallman <rms@gnu.org>
parents: 44428
diff changeset
1352
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1353 @node Transaction Queues
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1354 @section Transaction Queues
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355 @cindex transaction queue
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1356
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1357 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
1358 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
1359 queue communicating with a specified process. Then you can call
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17611
diff changeset
1360 @code{tq-enqueue} to send a transaction.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1362 @defun tq-create process
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 This function creates and returns a transaction queue communicating with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364 @var{process}. The argument @var{process} should be a subprocess
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 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
1366 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
1367 machine.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368 @end defun
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 @defun tq-enqueue queue question regexp closure fn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371 This function sends a transaction to queue @var{queue}. Specifying the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372 queue has the effect of specifying the subprocess to talk to.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1374 The argument @var{question} is the outgoing message that starts the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1375 transaction. The argument @var{fn} is the function to call when the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1376 corresponding answer comes back; it is called with two arguments:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1377 @var{closure}, and the answer received.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1378
39426
4520697c8aa5 (tq-enqueue): Clarify meaning of REGEXP.
Richard M. Stallman <rms@gnu.org>
parents: 27370
diff changeset
1379 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
1380 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
1381 @code{tq-enqueue} determines where the answer ends.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1382
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1383 The return value of @code{tq-enqueue} itself is not meaningful.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1384 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1385
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1386 @defun tq-close queue
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1387 Shut down transaction queue @var{queue}, waiting for all pending transactions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1388 to complete, and then terminate the connection or child process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1389 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1390
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1391 Transaction queues are implemented by means of a filter function.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1392 @xref{Filter Functions}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1393
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1394 @node Network
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1395 @section Network Connections
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1396 @cindex network connection
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1397 @cindex TCP
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1398
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1399 Emacs Lisp programs can open TCP network connections to other processes on
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1400 the same machine or other machines. A network connection is handled by Lisp
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1401 much like a subprocess, and is represented by a process object.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1402 However, the process you are communicating with is not a child of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1403 Emacs process, so you can't kill it or send it signals. All you can do
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1404 is send and receive data. @code{delete-process} closes the connection,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405 but does not kill the process at the other end; that process must decide
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406 what to do about closure of the connection.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408 You can distinguish process objects representing network connections
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409 from those representing subprocesses with the @code{process-status}
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1410 function. It always returns either @code{open} or @code{closed} for a
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1411 network connection, and it never returns either of those values for a
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1412 real subprocess. @xref{Process Information}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1413
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1414 @defun open-network-stream name buffer-or-name host service
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1415 This function opens a TCP connection for a service to a host. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1416 returns a process object to represent the connection.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1417
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418 The @var{name} argument specifies the name for the process object. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419 is modified as necessary to make it unique.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421 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
1422 connection. Output from the connection is inserted in the buffer,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1423 unless you specify a filter function to handle the output. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 @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
1425 associated with any buffer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1426
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1427 The arguments @var{host} and @var{service} specify where to connect to;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1428 @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
1429 a defined network service (a string) or a port number (an integer).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1430 @end defun