0
+ − 1 @c -*-texinfo-*-
+ − 2 @c This is part of the XEmacs Lisp Reference Manual.
442
+ − 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
0
+ − 4 @c See the file lispref.texi for copying conditions.
+ − 5 @setfilename ../../info/processes.info
+ − 6 @node Processes, System Interface, Databases, Top
+ − 7 @chapter Processes
+ − 8 @cindex child process
+ − 9 @cindex parent process
+ − 10 @cindex subprocess
+ − 11 @cindex process
+ − 12
+ − 13 In the terminology of operating systems, a @dfn{process} is a space in
+ − 14 which a program can execute. XEmacs runs in a process. XEmacs Lisp
+ − 15 programs can invoke other programs in processes of their own. These are
+ − 16 called @dfn{subprocesses} or @dfn{child processes} of the XEmacs process,
+ − 17 which is their @dfn{parent process}.
+ − 18
+ − 19 A subprocess of XEmacs may be @dfn{synchronous} or @dfn{asynchronous},
+ − 20 depending on how it is created. When you create a synchronous
+ − 21 subprocess, the Lisp program waits for the subprocess to terminate
+ − 22 before continuing execution. When you create an asynchronous
+ − 23 subprocess, it can run in parallel with the Lisp program. This kind of
+ − 24 subprocess is represented within XEmacs by a Lisp object which is also
+ − 25 called a ``process''. Lisp programs can use this object to communicate
+ − 26 with the subprocess or to control it. For example, you can send
+ − 27 signals, obtain status information, receive output from the process, or
+ − 28 send input to it.
+ − 29
+ − 30 @defun processp object
+ − 31 This function returns @code{t} if @var{object} is a process,
+ − 32 @code{nil} otherwise.
+ − 33 @end defun
+ − 34
+ − 35 @menu
+ − 36 * Subprocess Creation:: Functions that start subprocesses.
+ − 37 * Synchronous Processes:: Details of using synchronous subprocesses.
+ − 38 * MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
+ − 39 for data sent to and from a subprocess.
+ − 40 * Asynchronous Processes:: Starting up an asynchronous subprocess.
+ − 41 * Deleting Processes:: Eliminating an asynchronous subprocess.
+ − 42 * Process Information:: Accessing run-status and other attributes.
+ − 43 * Input to Processes:: Sending input to an asynchronous subprocess.
+ − 44 * Signals to Processes:: Stopping, continuing or interrupting
+ − 45 an asynchronous subprocess.
+ − 46 * Output from Processes:: Collecting output from an asynchronous subprocess.
+ − 47 * Sentinels:: Sentinels run when process run-status changes.
+ − 48 * Process Window Size:: Changing the logical window size of a process.
+ − 49 * Transaction Queues:: Transaction-based communication with subprocesses.
+ − 50 * Network:: Opening network connections.
+ − 51 @end menu
+ − 52
+ − 53 @node Subprocess Creation
+ − 54 @section Functions that Create Subprocesses
+ − 55
+ − 56 There are three functions that create a new subprocess in which to run
+ − 57 a program. One of them, @code{start-process}, creates an asynchronous
+ − 58 process and returns a process object (@pxref{Asynchronous Processes}).
+ − 59 The other two, @code{call-process} and @code{call-process-region},
+ − 60 create a synchronous process and do not return a process object
+ − 61 (@pxref{Synchronous Processes}).
+ − 62
444
+ − 63 Synchronous and asynchronous processes are explained in the following
0
+ − 64 sections. Since the three functions are all called in a similar
+ − 65 fashion, their common arguments are described here.
+ − 66
+ − 67 @cindex execute program
+ − 68 @cindex @code{PATH} environment variable
+ − 69 @cindex @code{HOME} environment variable
+ − 70 In all cases, the function's @var{program} argument specifies the
+ − 71 program to be run. An error is signaled if the file is not found or
+ − 72 cannot be executed. If the file name is relative, the variable
+ − 73 @code{exec-path} contains a list of directories to search. Emacs
+ − 74 initializes @code{exec-path} when it starts up, based on the value of
+ − 75 the environment variable @code{PATH}. The standard file name
+ − 76 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usual
+ − 77 in @code{exec-path}, but environment variable substitutions
+ − 78 (@samp{$HOME}, etc.) are not recognized; use
+ − 79 @code{substitute-in-file-name} to perform them (@pxref{File Name
+ − 80 Expansion}).
+ − 81
+ − 82 Each of the subprocess-creating functions has a @var{buffer-or-name}
+ − 83 argument which specifies where the standard output from the program will
+ − 84 go. If @var{buffer-or-name} is @code{nil}, that says to discard the
+ − 85 output unless a filter function handles it. (@xref{Filter Functions},
+ − 86 and @ref{Read and Print}.) Normally, you should avoid having multiple
+ − 87 processes send output to the same buffer because their output would be
+ − 88 intermixed randomly.
+ − 89
+ − 90 @cindex program arguments
+ − 91 All three of the subprocess-creating functions have a @code{&rest}
+ − 92 argument, @var{args}. The @var{args} must all be strings, and they are
+ − 93 supplied to @var{program} as separate command line arguments. Wildcard
+ − 94 characters and other shell constructs are not allowed in these strings,
442
+ − 95 since they are passed directly to the specified program.
0
+ − 96
+ − 97 @strong{Please note:} The argument @var{program} contains only the
+ − 98 name of the program; it may not contain any command-line arguments. You
+ − 99 must use @var{args} to provide those.
+ − 100
444
+ − 101 If you want to use features of the shell, then invoke the shell directly
+ − 102 using, for example, @var{program} of @code{"sh"}, and @var{args} of
+ − 103 @code{"-c"} and @var{"command line..."}.
+ − 104
0
+ − 105 The subprocess gets its current directory from the value of
+ − 106 @code{default-directory} (@pxref{File Name Expansion}).
+ − 107
+ − 108 @cindex environment variables, subprocesses
+ − 109 The subprocess inherits its environment from XEmacs; but you can
+ − 110 specify overrides for it with @code{process-environment}. @xref{System
+ − 111 Environment}.
+ − 112
442
+ − 113 @defvar exec-directory
0
+ − 114 @pindex wakeup
+ − 115 The value of this variable is the name of a directory (a string) that
+ − 116 contains programs that come with XEmacs, that are intended for XEmacs
+ − 117 to invoke. The program @code{wakeup} is an example of such a program;
+ − 118 the @code{display-time} command uses it to get a reminder once per
+ − 119 minute.
+ − 120 @end defvar
+ − 121
+ − 122 @defopt exec-path
+ − 123 The value of this variable is a list of directories to search for
+ − 124 programs to run in subprocesses. Each element is either the name of a
+ − 125 directory (i.e., a string), or @code{nil}, which stands for the default
+ − 126 directory (which is the value of @code{default-directory}).
+ − 127 @cindex program directories
+ − 128
+ − 129 The value of @code{exec-path} is used by @code{call-process} and
+ − 130 @code{start-process} when the @var{program} argument is not an absolute
+ − 131 file name.
+ − 132 @end defopt
+ − 133
+ − 134 @node Synchronous Processes
+ − 135 @section Creating a Synchronous Process
+ − 136 @cindex synchronous subprocess
+ − 137
+ − 138 After a @dfn{synchronous process} is created, XEmacs waits for the
+ − 139 process to terminate before continuing. Starting Dired is an example of
+ − 140 this: it runs @code{ls} in a synchronous process, then modifies the
+ − 141 output slightly. Because the process is synchronous, the entire
+ − 142 directory listing arrives in the buffer before XEmacs tries to do
+ − 143 anything with it.
+ − 144
+ − 145 While Emacs waits for the synchronous subprocess to terminate, the
+ − 146 user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
+ − 147 the subprocess with a @code{SIGINT} signal; but it waits until the
+ − 148 subprocess actually terminates before quitting. If during that time the
+ − 149 user types another @kbd{C-g}, that kills the subprocess instantly with
+ − 150 @code{SIGKILL} and quits immediately. @xref{Quitting}.
+ − 151
+ − 152 The synchronous subprocess functions returned @code{nil} in version
+ − 153 18. In version 19, they return an indication of how the process
+ − 154 terminated.
+ − 155
+ − 156 @defun call-process program &optional infile destination display &rest args
+ − 157 This function calls @var{program} in a separate process and waits for
+ − 158 it to finish.
+ − 159
+ − 160 The standard input for the process comes from file @var{infile} if
+ − 161 @var{infile} is not @code{nil} and from @file{/dev/null} otherwise.
+ − 162 The argument @var{destination} says where to put the process output.
+ − 163 Here are the possibilities:
+ − 164
+ − 165 @table @asis
+ − 166 @item a buffer
+ − 167 Insert the output in that buffer, before point. This includes both the
+ − 168 standard output stream and the standard error stream of the process.
+ − 169
+ − 170 @item a string
+ − 171 Find or create a buffer with that name, then insert
+ − 172 the output in that buffer, before point.
+ − 173
+ − 174 @item @code{t}
+ − 175 Insert the output in the current buffer, before point.
+ − 176
+ − 177 @item @code{nil}
+ − 178 Discard the output.
+ − 179
+ − 180 @item 0
+ − 181 Discard the output, and return immediately without waiting
+ − 182 for the subprocess to finish.
+ − 183
+ − 184 In this case, the process is not truly synchronous, since it can run in
+ − 185 parallel with Emacs; but you can think of it as synchronous in that
+ − 186 Emacs is essentially finished with the subprocess as soon as this
+ − 187 function returns.
+ − 188
+ − 189 @item (@var{real-destination} @var{error-destination})
+ − 190 Keep the standard output stream separate from the standard error stream;
+ − 191 deal with the ordinary output as specified by @var{real-destination},
+ − 192 and dispose of the error output according to @var{error-destination}.
+ − 193 The value @code{nil} means discard it, @code{t} means mix it with the
+ − 194 ordinary output, and a string specifies a file name to redirect error
+ − 195 output into.
+ − 196
+ − 197 You can't directly specify a buffer to put the error output in; that is
+ − 198 too difficult to implement. But you can achieve this result by sending
+ − 199 the error output to a temporary file and then inserting the file into a
+ − 200 buffer.
+ − 201 @end table
+ − 202
+ − 203 If @var{display} is non-@code{nil}, then @code{call-process} redisplays
+ − 204 the buffer as output is inserted. Otherwise the function does no
+ − 205 redisplay, and the results become visible on the screen only when XEmacs
+ − 206 redisplays that buffer in the normal course of events.
+ − 207
+ − 208 The remaining arguments, @var{args}, are strings that specify command
+ − 209 line arguments for the program.
+ − 210
+ − 211 The value returned by @code{call-process} (unless you told it not to
+ − 212 wait) indicates the reason for process termination. A number gives the
+ − 213 exit status of the subprocess; 0 means success, and any other value
+ − 214 means failure. If the process terminated with a signal,
+ − 215 @code{call-process} returns a string describing the signal.
+ − 216
+ − 217 In the examples below, the buffer @samp{foo} is current.
+ − 218
+ − 219 @smallexample
+ − 220 @group
+ − 221 (call-process "pwd" nil t)
+ − 222 @result{} nil
+ − 223
+ − 224 ---------- Buffer: foo ----------
+ − 225 /usr/user/lewis/manual
+ − 226 ---------- Buffer: foo ----------
+ − 227 @end group
+ − 228
+ − 229 @group
+ − 230 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
+ − 231 @result{} nil
+ − 232
+ − 233 ---------- Buffer: bar ----------
+ − 234 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
+ − 235
+ − 236 ---------- Buffer: bar ----------
+ − 237 @end group
+ − 238 @end smallexample
+ − 239
+ − 240 The @code{insert-directory} function contains a good example of the use
+ − 241 of @code{call-process}:
+ − 242
+ − 243 @smallexample
+ − 244 @group
+ − 245 (call-process insert-directory-program nil t nil switches
+ − 246 (if full-directory-p
+ − 247 (concat (file-name-as-directory file) ".")
+ − 248 file))
+ − 249 @end group
+ − 250 @end smallexample
+ − 251 @end defun
+ − 252
444
+ − 253 @defun call-process-region start end program &optional deletep destination displayp &rest args
0
+ − 254 This function sends the text between @var{start} to @var{end} as
+ − 255 standard input to a process running @var{program}. It deletes the text
444
+ − 256 sent if @var{deletep} is non-@code{nil}; this is useful when @var{buffer}
0
+ − 257 is @code{t}, to insert the output in the current buffer.
+ − 258
444
+ − 259 The arguments @var{destination} and @var{displayp} control what to do
0
+ − 260 with the output from the subprocess, and whether to update the display
+ − 261 as it comes in. For details, see the description of
+ − 262 @code{call-process}, above. If @var{destination} is the integer 0,
+ − 263 @code{call-process-region} discards the output and returns @code{nil}
+ − 264 immediately, without waiting for the subprocess to finish.
+ − 265
+ − 266 The remaining arguments, @var{args}, are strings that specify command
+ − 267 line arguments for the program.
+ − 268
+ − 269 The return value of @code{call-process-region} is just like that of
+ − 270 @code{call-process}: @code{nil} if you told it to return without
+ − 271 waiting; otherwise, a number or string which indicates how the
+ − 272 subprocess terminated.
+ − 273
+ − 274 In the following example, we use @code{call-process-region} to run the
+ − 275 @code{cat} utility, with standard input being the first five characters
+ − 276 in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
+ − 277 standard input into its standard output. Since the argument
+ − 278 @var{destination} is @code{t}, this output is inserted in the current
+ − 279 buffer.
+ − 280
+ − 281 @smallexample
+ − 282 @group
+ − 283 ---------- Buffer: foo ----------
+ − 284 input@point{}
+ − 285 ---------- Buffer: foo ----------
+ − 286 @end group
+ − 287
+ − 288 @group
+ − 289 (call-process-region 1 6 "cat" nil t)
+ − 290 @result{} nil
+ − 291
+ − 292 ---------- Buffer: foo ----------
+ − 293 inputinput@point{}
+ − 294 ---------- Buffer: foo ----------
+ − 295 @end group
+ − 296 @end smallexample
+ − 297
+ − 298 The @code{shell-command-on-region} command uses
+ − 299 @code{call-process-region} like this:
+ − 300
+ − 301 @smallexample
+ − 302 @group
442
+ − 303 (call-process-region
+ − 304 start end
0
+ − 305 shell-file-name ; @r{Name of program.}
+ − 306 nil ; @r{Do not delete region.}
+ − 307 buffer ; @r{Send output to @code{buffer}.}
+ − 308 nil ; @r{No redisplay during output.}
+ − 309 "-c" command) ; @r{Arguments for the shell.}
+ − 310 @end group
+ − 311 @end smallexample
+ − 312 @end defun
+ − 313
+ − 314 @node MS-DOS Subprocesses
+ − 315 @section MS-DOS Subprocesses
+ − 316
+ − 317 On MS-DOS, you must indicate whether the data going to and from
+ − 318 a synchronous subprocess are text or binary. Text data requires
+ − 319 translation between the end-of-line convention used within Emacs
+ − 320 (a single newline character) and the convention used outside Emacs
+ − 321 (the two-character sequence, @sc{crlf}).
+ − 322
+ − 323 The variable @code{binary-process-input} applies to input sent to the
+ − 324 subprocess, and @code{binary-process-output} applies to output received
+ − 325 from it. A non-@code{nil} value means the data is non-text; @code{nil}
+ − 326 means the data is text, and calls for conversion.
+ − 327
+ − 328 @defvar binary-process-input
+ − 329 If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
+ − 330 the input to a synchronous subprocess.
+ − 331 @end defvar
+ − 332
+ − 333 @defvar binary-process-output
+ − 334 If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
+ − 335 the output from a synchronous subprocess.
+ − 336 @end defvar
+ − 337
+ − 338 @xref{Files and MS-DOS}, for related information.
+ − 339
+ − 340 @node Asynchronous Processes
+ − 341 @section Creating an Asynchronous Process
+ − 342 @cindex asynchronous subprocess
+ − 343
+ − 344 After an @dfn{asynchronous process} is created, Emacs and the Lisp
+ − 345 program both continue running immediately. The process may thereafter
+ − 346 run in parallel with Emacs, and the two may communicate with each other
+ − 347 using the functions described in following sections. Here we describe
+ − 348 how to create an asynchronous process with @code{start-process}.
+ − 349
+ − 350 @defun start-process name buffer-or-name program &rest args
+ − 351 This function creates a new asynchronous subprocess and starts the
+ − 352 program @var{program} running in it. It returns a process object that
+ − 353 stands for the new subprocess in Lisp. The argument @var{name}
+ − 354 specifies the name for the process object; if a process with this name
+ − 355 already exists, then @var{name} is modified (by adding @samp{<1>}, etc.)
+ − 356 to be unique. The buffer @var{buffer-or-name} is the buffer to
+ − 357 associate with the process.
+ − 358
+ − 359 The remaining arguments, @var{args}, are strings that specify command
+ − 360 line arguments for the program.
+ − 361
+ − 362 In the example below, the first process is started and runs (rather,
+ − 363 sleeps) for 100 seconds. Meanwhile, the second process is started, and
+ − 364 given the name @samp{my-process<1>} for the sake of uniqueness. It
+ − 365 inserts the directory listing at the end of the buffer @samp{foo},
+ − 366 before the first process finishes. Then it finishes, and a message to
+ − 367 that effect is inserted in the buffer. Much later, the first process
+ − 368 finishes, and another message is inserted in the buffer for it.
+ − 369
+ − 370 @smallexample
+ − 371 @group
+ − 372 (start-process "my-process" "foo" "sleep" "100")
+ − 373 @result{} #<process my-process>
+ − 374 @end group
+ − 375
+ − 376 @group
+ − 377 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
+ − 378 @result{} #<process my-process<1>>
+ − 379
+ − 380 ---------- Buffer: foo ----------
+ − 381 total 2
+ − 382 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
+ − 383 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
+ − 384
+ − 385 Process my-process<1> finished
+ − 386
+ − 387 Process my-process finished
+ − 388 ---------- Buffer: foo ----------
+ − 389 @end group
+ − 390 @end smallexample
+ − 391 @end defun
+ − 392
+ − 393 @defun start-process-shell-command name buffer-or-name command &rest command-args
+ − 394 This function is like @code{start-process} except that it uses a shell
+ − 395 to execute the specified command. The argument @var{command} is a shell
+ − 396 command name, and @var{command-args} are the arguments for the shell
+ − 397 command.
+ − 398 @end defun
+ − 399
+ − 400 @defvar process-connection-type
+ − 401 @cindex pipes
+ − 402 @cindex @sc{pty}s
+ − 403 This variable controls the type of device used to communicate with
+ − 404 asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are
+ − 405 used, when available. Otherwise, pipes are used.
+ − 406
+ − 407 @sc{pty}s are usually preferable for processes visible to the user, as
+ − 408 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
+ − 409 etc.) to work between the process and its children whereas pipes do not.
+ − 410 For subprocesses used for internal purposes by programs, it is often
+ − 411 better to use a pipe, because they are more efficient. In addition, the
+ − 412 total number of @sc{pty}s is limited on many systems and it is good not
444
+ − 413 to waste them. A rule of thumb is to use ptys for processes the user
+ − 414 interacts with directly, and pipes for processes that are hidden from
+ − 415 the user.
0
+ − 416
+ − 417 The value @code{process-connection-type} is used when
+ − 418 @code{start-process} is called. So you can specify how to communicate
+ − 419 with one subprocess by binding the variable around the call to
+ − 420 @code{start-process}.
+ − 421
+ − 422 @smallexample
+ − 423 @group
+ − 424 (let ((process-connection-type nil)) ; @r{Use a pipe.}
+ − 425 (start-process @dots{}))
+ − 426 @end group
+ − 427 @end smallexample
+ − 428
+ − 429 To determine whether a given subprocess actually got a pipe or a
+ − 430 @sc{pty}, use the function @code{process-tty-name} (@pxref{Process
+ − 431 Information}).
+ − 432 @end defvar
+ − 433
444
+ − 434 Lisp functions that manipulate processes usually accept a @var{process}
+ − 435 argument. Besides using an actual process object for this argument, you
+ − 436 can use a process name, a buffer object, the name of a buffer, or
+ − 437 @code{nil}. Specifying a buffer or buffer name for the @var{process}
+ − 438 argument means use the process associated with the buffer (or the most
+ − 439 recent one, if there is more than one). @code{nil} means use the
+ − 440 process associated with the current buffer.
+ − 441 @xref{Process Information}.
+ − 442 @xref{Process Buffers}.
+ − 443
0
+ − 444 @node Deleting Processes
+ − 445 @section Deleting Processes
+ − 446 @cindex deleting processes
+ − 447
+ − 448 @dfn{Deleting a process} disconnects XEmacs immediately from the
+ − 449 subprocess, and removes it from the list of active processes. It sends
+ − 450 a signal to the subprocess to make the subprocess terminate, but this is
+ − 451 not guaranteed to happen immediately. The process object itself
+ − 452 continues to exist as long as other Lisp objects point to it.
+ − 453
+ − 454 You can delete a process explicitly at any time. Processes are
+ − 455 deleted automatically after they terminate, but not necessarily right
+ − 456 away. If you delete a terminated process explicitly before it is
+ − 457 deleted automatically, no harm results.
+ − 458
+ − 459 @defvar delete-exited-processes
+ − 460 This variable controls automatic deletion of processes that have
+ − 461 terminated (due to calling @code{exit} or to a signal). If it is
+ − 462 @code{nil}, then they continue to exist until the user runs
+ − 463 @code{list-processes}. Otherwise, they are deleted immediately after
+ − 464 they exit.
+ − 465 @end defvar
+ − 466
+ − 467 @defun delete-process name
+ − 468 This function deletes the process associated with @var{name}, killing it
+ − 469 with a @code{SIGHUP} signal. The argument @var{name} may be a process,
+ − 470 the name of a process, a buffer, or the name of a buffer.
+ − 471
+ − 472 @smallexample
+ − 473 @group
+ − 474 (delete-process "*shell*")
+ − 475 @result{} nil
+ − 476 @end group
+ − 477 @end smallexample
+ − 478 @end defun
+ − 479
+ − 480 @defun process-kill-without-query process &optional require-query-p
+ − 481 This function declares that XEmacs need not query the user if
+ − 482 @var{process} is still running when XEmacs is exited. The process will
+ − 483 be deleted silently. If @var{require-query-p} is non-@code{nil},
+ − 484 then XEmacs @emph{will} query the user (this is the default). The
+ − 485 return value is @code{t} if a query was formerly required, and
+ − 486 @code{nil} otherwise.
+ − 487
+ − 488 @smallexample
+ − 489 @group
+ − 490 (process-kill-without-query (get-process "shell"))
+ − 491 @result{} t
+ − 492 @end group
+ − 493 @end smallexample
+ − 494 @end defun
+ − 495
+ − 496 @node Process Information
+ − 497 @section Process Information
+ − 498
+ − 499 Several functions return information about processes.
+ − 500 @code{list-processes} is provided for interactive use.
+ − 501
+ − 502 @deffn Command list-processes
+ − 503 This command displays a listing of all living processes. In addition,
+ − 504 it finally deletes any process whose status was @samp{Exited} or
+ − 505 @samp{Signaled}. It returns @code{nil}.
+ − 506 @end deffn
+ − 507
+ − 508 @defun process-list
+ − 509 This function returns a list of all processes that have not been deleted.
+ − 510
+ − 511 @smallexample
+ − 512 @group
+ − 513 (process-list)
+ − 514 @result{} (#<process display-time> #<process shell>)
+ − 515 @end group
+ − 516 @end smallexample
+ − 517 @end defun
+ − 518
444
+ − 519 @defun get-process process-name
+ − 520 This function returns the process named @var{process-name}. If
+ − 521 @var{process-name} is a string and there is no process with that name, the
+ − 522 value is @code{nil}. If @var{process-name} is actually a process, it is
+ − 523 returned as given. (That is not very useful, so the argument is usually
+ − 524 a name.) For example:
0
+ − 525
+ − 526 @smallexample
+ − 527 @group
+ − 528 (get-process "shell")
+ − 529 @result{} #<process shell>
+ − 530 @end group
+ − 531 @end smallexample
+ − 532 @end defun
+ − 533
+ − 534 @defun process-command process
+ − 535 This function returns the command that was executed to start
+ − 536 @var{process}. This is a list of strings, the first string being the
+ − 537 program executed and the rest of the strings being the arguments that
+ − 538 were given to the program.
+ − 539
+ − 540 @smallexample
+ − 541 @group
+ − 542 (process-command (get-process "shell"))
+ − 543 @result{} ("/bin/csh" "-i")
+ − 544 @end group
+ − 545 @end smallexample
+ − 546 @end defun
+ − 547
+ − 548 @defun process-id process
+ − 549 This function returns the @sc{pid} of @var{process}. This is an
+ − 550 integer that distinguishes the process @var{process} from all other
+ − 551 processes running on the same computer at the current time. The
+ − 552 @sc{pid} of a process is chosen by the operating system kernel when the
+ − 553 process is started and remains constant as long as the process exists.
+ − 554 @end defun
+ − 555
+ − 556 @defun process-name process
+ − 557 This function returns the name of @var{process}.
+ − 558 @end defun
+ − 559
444
+ − 560 @defun process-status process
+ − 561 This function returns the status of @var{process} as a symbol.
+ − 562 The argument @var{process} must be a process, a buffer, a
0
+ − 563 process name (string) or a buffer name (string).
+ − 564
+ − 565 The possible values for an actual subprocess are:
+ − 566
+ − 567 @table @code
+ − 568 @item run
+ − 569 for a process that is running.
+ − 570 @item stop
+ − 571 for a process that is stopped but continuable.
+ − 572 @item exit
+ − 573 for a process that has exited.
+ − 574 @item signal
+ − 575 for a process that has received a fatal signal.
+ − 576 @item open
+ − 577 for a network connection that is open.
+ − 578 @item closed
+ − 579 for a network connection that is closed. Once a connection
+ − 580 is closed, you cannot reopen it, though you might be able to open
+ − 581 a new connection to the same place.
+ − 582 @item nil
444
+ − 583 if @var{process} does not identify an existing process.
0
+ − 584 @end table
+ − 585
+ − 586 @smallexample
+ − 587 @group
+ − 588 (process-status "shell")
+ − 589 @result{} run
+ − 590 @end group
+ − 591 @group
+ − 592 (process-status (get-buffer "*shell*"))
+ − 593 @result{} run
+ − 594 @end group
+ − 595 @group
+ − 596 x
+ − 597 @result{} #<process xx<1>>
+ − 598 (process-status x)
+ − 599 @result{} exit
+ − 600 @end group
+ − 601 @end smallexample
+ − 602
+ − 603 For a network connection, @code{process-status} returns one of the symbols
+ − 604 @code{open} or @code{closed}. The latter means that the other side
+ − 605 closed the connection, or XEmacs did @code{delete-process}.
+ − 606
+ − 607 In earlier Emacs versions (prior to version 19), the status of a network
+ − 608 connection was @code{run} if open, and @code{exit} if closed.
+ − 609 @end defun
+ − 610
+ − 611 @defun process-kill-without-query-p process
+ − 612 This function returns whether @var{process} will be killed without
+ − 613 querying the user, if it is running when XEmacs is exited. The default
+ − 614 value is @code{nil}.
+ − 615 @end defun
+ − 616
+ − 617 @defun process-exit-status process
+ − 618 This function returns the exit status of @var{process} or the signal
+ − 619 number that killed it. (Use the result of @code{process-status} to
+ − 620 determine which of those it is.) If @var{process} has not yet
+ − 621 terminated, the value is 0.
+ − 622 @end defun
+ − 623
+ − 624 @defun process-tty-name process
+ − 625 This function returns the terminal name that @var{process} is using for
+ − 626 its communication with Emacs---or @code{nil} if it is using pipes
+ − 627 instead of a terminal (see @code{process-connection-type} in
+ − 628 @ref{Asynchronous Processes}).
+ − 629 @end defun
+ − 630
+ − 631 @node Input to Processes
+ − 632 @section Sending Input to Processes
+ − 633 @cindex process input
+ − 634
+ − 635 Asynchronous subprocesses receive input when it is sent to them by
+ − 636 XEmacs, which is done with the functions in this section. You must
+ − 637 specify the process to send input to, and the input data to send. The
+ − 638 data appears on the ``standard input'' of the subprocess.
+ − 639
+ − 640 Some operating systems have limited space for buffered input in a
444
+ − 641 @sc{pty}. On these systems, XEmacs sends long input in chunks, with
+ − 642 @sc{eof} characters added amidst the other characters, to force the
+ − 643 operating system to periodically drain the input buffer. For most
+ − 644 programs, these @sc{eof}s do no harm.
0
+ − 645
444
+ − 646 @defun process-send-string process string &optional start end
+ − 647 This function sends @var{process} the contents of @var{string} as
+ − 648 standard input.
+ − 649
+ − 650 The argument @var{process} may be a process or the name of a process, or
+ − 651 a buffer or the name of a buffer, in which case the buffer's process is
+ − 652 used. If it is @code{nil}, the current buffer's process is used.
+ − 653
+ − 654 Optional arguments @var{start} and @var{end} specify part of @var{string};
+ − 655 see @code{substring}.
0
+ − 656
+ − 657 The function returns @code{nil}.
+ − 658
+ − 659 @smallexample
+ − 660 @group
+ − 661 (process-send-string "shell<1>" "ls\n")
+ − 662 @result{} nil
+ − 663 @end group
+ − 664
+ − 665
+ − 666 @group
+ − 667 ---------- Buffer: *shell* ----------
+ − 668 ...
+ − 669 introduction.texi syntax-tables.texi~
+ − 670 introduction.texi~ text.texi
+ − 671 introduction.txt text.texi~
+ − 672 ...
+ − 673 ---------- Buffer: *shell* ----------
+ − 674 @end group
+ − 675 @end smallexample
+ − 676 @end defun
+ − 677
444
+ − 678 @defun process-send-region process start end &optional buffer
0
+ − 679 This function sends the text in the region defined by @var{start} and
444
+ − 680 @var{end} as standard input to @var{process}.
+ − 681
+ − 682 The argument @var{process} may be a process or the name of a process, or
+ − 683 a buffer or the name of a buffer, in which case the buffer's process is
+ − 684 used. If it is @code{nil}, the current buffer's process is used.
0
+ − 685
+ − 686 An error is signaled unless both @var{start} and @var{end} are
+ − 687 integers or markers that indicate positions in the current buffer. (It
+ − 688 is unimportant which number is larger.)
444
+ − 689 @end defun
0
+ − 690
444
+ − 691 @defun process-send-eof &optional process
+ − 692 This function makes @var{process} see an end-of-file in its
0
+ − 693 input. The @sc{eof} comes after any text already sent to it.
+ − 694
444
+ − 695 @var{process} may be a process, a buffer, the name of a process or
+ − 696 buffer, or @code{nil}, indicating the current buffer's process. An
+ − 697 error is signaled if @var{process} does not identify any process.
0
+ − 698
444
+ − 699 The function returns the process object identified by @var{process}.
0
+ − 700
+ − 701 @smallexample
+ − 702 @group
+ − 703 (process-send-eof "shell")
+ − 704 @result{} "shell"
+ − 705 @end group
+ − 706 @end smallexample
+ − 707 @end defun
+ − 708
+ − 709 @node Signals to Processes
+ − 710 @section Sending Signals to Processes
+ − 711 @cindex process signals
+ − 712 @cindex sending signals
+ − 713 @cindex signals
+ − 714
+ − 715 @dfn{Sending a signal} to a subprocess is a way of interrupting its
+ − 716 activities. There are several different signals, each with its own
+ − 717 meaning. The set of signals and their names is defined by the operating
+ − 718 system. For example, the signal @code{SIGINT} means that the user has
+ − 719 typed @kbd{C-c}, or that some analogous thing has happened.
+ − 720
+ − 721 Each signal has a standard effect on the subprocess. Most signals
+ − 722 kill the subprocess, but some stop or resume execution instead. Most
+ − 723 signals can optionally be handled by programs; if the program handles
+ − 724 the signal, then we can say nothing in general about its effects.
+ − 725
+ − 726 The set of signals and their names is defined by the operating system;
+ − 727 XEmacs has facilities for sending only a few of the signals that are
+ − 728 defined. XEmacs can send signals only to its own subprocesses.
+ − 729
+ − 730 You can send signals explicitly by calling the functions in this
+ − 731 section. XEmacs also sends signals automatically at certain times:
+ − 732 killing a buffer sends a @code{SIGHUP} signal to all its associated
+ − 733 processes; killing XEmacs sends a @code{SIGHUP} signal to all remaining
442
+ − 734 processes. (@code{SIGHUP} is a signal that indicates that the
+ − 735 connection between the user and the process is broken, for example if a
+ − 736 connection via a telephone line is hung up.)
0
+ − 737
+ − 738 Each of the signal-sending functions takes two optional arguments:
442
+ − 739 @var{process} and @var{current-group}.
0
+ − 740
442
+ − 741 The argument @var{process} must be either a process or a buffer,
+ − 742 the name of one, or @code{nil}. If it is @code{nil}, the process
+ − 743 defaults to the process associated with the current buffer. An error is
+ − 744 signaled if @var{process} does not identify a process.
0
+ − 745
+ − 746 The argument @var{current-group} is a flag that makes a difference
+ − 747 when you are running a job-control shell as an XEmacs subprocess. If it
442
+ − 748 is non-@code{nil}, then the signal is sent to the current foreground
+ − 749 process group of the terminal that XEmacs uses to communicate with the
+ − 750 subprocess. If the process is a job-control shell, this means the
+ − 751 shell's current subjob. If it is @code{nil}, the signal is sent to the
+ − 752 process group of the immediate subprocess of XEmacs. If the subprocess
+ − 753 is a job-control shell, this is the shell itself.
0
+ − 754
+ − 755 The flag @var{current-group} has no effect when a pipe is used to
+ − 756 communicate with the subprocess, because the operating system does not
+ − 757 support the distinction in the case of pipes. For the same reason,
+ − 758 job-control shells won't work when a pipe is used. See
+ − 759 @code{process-connection-type} in @ref{Asynchronous Processes}.
+ − 760
442
+ − 761 Some of the functions below take a @var{signal} argument, which
+ − 762 identifies a signal to be sent. It must be either an integer or a
+ − 763 symbol which names the signal, like @code{SIGSEGV}.
+ − 764
+ − 765 @defun process-send-signal signal &optional process current-group
+ − 766 This function sends the signal @var{signal} to the process @var{process}.
+ − 767 The following functions can be implemented in terms of
+ − 768 @code{process-send-signal}.
0
+ − 769 @end defun
+ − 770
442
+ − 771 @defun interrupt-process &optional process current-group
+ − 772 This function interrupts the process @var{process} by sending the signal
+ − 773 @code{SIGINT}. Outside of XEmacs, typing the ``interrupt character''
+ − 774 (normally @kbd{C-c}) sends this signal. When the argument
+ − 775 @var{current-group} is non-@code{nil}, you can think of this function as
+ − 776 ``typing @kbd{C-c}'' on the terminal by which XEmacs talks to the
+ − 777 subprocess.
+ − 778 @end defun
+ − 779
+ − 780 @defun kill-process &optional process current-group
+ − 781 This function kills the process @var{process} by sending the
0
+ − 782 signal @code{SIGKILL}. This signal kills the subprocess immediately,
+ − 783 and cannot be handled by the subprocess.
+ − 784 @end defun
+ − 785
442
+ − 786 @defun quit-process &optional process current-group
0
+ − 787 This function sends the signal @code{SIGQUIT} to the process
442
+ − 788 @var{process}. This signal is the one sent by the ``quit
+ − 789 character'' (usually @kbd{C-\}) when you are not inside XEmacs.
0
+ − 790 @end defun
+ − 791
442
+ − 792 @defun stop-process &optional process current-group
+ − 793 This function stops the process @var{process} by sending the
0
+ − 794 signal @code{SIGTSTP}. Use @code{continue-process} to resume its
+ − 795 execution.
+ − 796
+ − 797 On systems with job control, the ``stop character'' (usually @kbd{C-z})
+ − 798 sends this signal (outside of XEmacs). When @var{current-group} is
+ − 799 non-@code{nil}, you can think of this function as ``typing @kbd{C-z}''
+ − 800 on the terminal XEmacs uses to communicate with the subprocess.
+ − 801 @end defun
+ − 802
442
+ − 803 @defun continue-process &optional process current-group
0
+ − 804 This function resumes execution of the process @var{process} by sending
442
+ − 805 it the signal @code{SIGCONT}. This presumes that @var{process} was
0
+ − 806 stopped previously.
+ − 807 @end defun
+ − 808
444
+ − 809 @deffn Command signal-process pid signal
442
+ − 810 This function sends a signal to the process with process id @var{pid},
+ − 811 which need not be a child of XEmacs. The argument @var{signal}
+ − 812 specifies which signal to send.
444
+ − 813 @end deffn
0
+ − 814
+ − 815 @node Output from Processes
+ − 816 @section Receiving Output from Processes
+ − 817 @cindex process output
+ − 818 @cindex output from processes
+ − 819
+ − 820 There are two ways to receive the output that a subprocess writes to
+ − 821 its standard output stream. The output can be inserted in a buffer,
+ − 822 which is called the associated buffer of the process, or a function
+ − 823 called the @dfn{filter function} can be called to act on the output. If
+ − 824 the process has no buffer and no filter function, its output is
+ − 825 discarded.
+ − 826
+ − 827 @menu
+ − 828 * Process Buffers:: If no filter, output is put in a buffer.
+ − 829 * Filter Functions:: Filter functions accept output from the process.
+ − 830 * Accepting Output:: Explicitly permitting subprocess output.
+ − 831 Waiting for subprocess output.
+ − 832 @end menu
+ − 833
+ − 834 @node Process Buffers
+ − 835 @subsection Process Buffers
+ − 836
+ − 837 A process can (and usually does) have an @dfn{associated buffer},
+ − 838 which is an ordinary Emacs buffer that is used for two purposes: storing
+ − 839 the output from the process, and deciding when to kill the process. You
+ − 840 can also use the buffer to identify a process to operate on, since in
+ − 841 normal practice only one process is associated with any given buffer.
+ − 842 Many applications of processes also use the buffer for editing input to
+ − 843 be sent to the process, but this is not built into XEmacs Lisp.
+ − 844
+ − 845 Unless the process has a filter function (@pxref{Filter Functions}),
+ − 846 its output is inserted in the associated buffer. The position to insert
+ − 847 the output is determined by the @code{process-mark}, which is then
+ − 848 updated to point to the end of the text just inserted. Usually, but not
+ − 849 always, the @code{process-mark} is at the end of the buffer.
+ − 850
+ − 851 @defun process-buffer process
+ − 852 This function returns the associated buffer of the process
+ − 853 @var{process}.
+ − 854
+ − 855 @smallexample
+ − 856 @group
+ − 857 (process-buffer (get-process "shell"))
+ − 858 @result{} #<buffer *shell*>
+ − 859 @end group
+ − 860 @end smallexample
+ − 861 @end defun
+ − 862
+ − 863 @defun process-mark process
+ − 864 This function returns the process marker for @var{process}, which is the
+ − 865 marker that says where to insert output from the process.
+ − 866
+ − 867 If @var{process} does not have a buffer, @code{process-mark} returns a
+ − 868 marker that points nowhere.
+ − 869
+ − 870 Insertion of process output in a buffer uses this marker to decide where
+ − 871 to insert, and updates it to point after the inserted text. That is why
+ − 872 successive batches of output are inserted consecutively.
+ − 873
+ − 874 Filter functions normally should use this marker in the same fashion
+ − 875 as is done by direct insertion of output in the buffer. A good
+ − 876 example of a filter function that uses @code{process-mark} is found at
+ − 877 the end of the following section.
+ − 878
+ − 879 When the user is expected to enter input in the process buffer for
+ − 880 transmission to the process, the process marker is useful for
+ − 881 distinguishing the new input from previous output.
+ − 882 @end defun
+ − 883
+ − 884 @defun set-process-buffer process buffer
+ − 885 This function sets the buffer associated with @var{process} to
+ − 886 @var{buffer}. If @var{buffer} is @code{nil}, the process becomes
+ − 887 associated with no buffer.
+ − 888 @end defun
+ − 889
+ − 890 @defun get-buffer-process buffer-or-name
+ − 891 This function returns the process associated with @var{buffer-or-name}.
444
+ − 892 If there are several processes associated with @var{buffer-or-name},
+ − 893 then one is chosen. (Presently, the one chosen is the one most recently
+ − 894 created.) It is usually a bad idea to have more than one process
+ − 895 associated with the same buffer.
0
+ − 896
+ − 897 @smallexample
+ − 898 @group
+ − 899 (get-buffer-process "*shell*")
+ − 900 @result{} #<process shell>
+ − 901 @end group
+ − 902 @end smallexample
+ − 903
+ − 904 Killing the process's buffer deletes the process, which kills the
+ − 905 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
+ − 906 @end defun
+ − 907
+ − 908 @node Filter Functions
+ − 909 @subsection Process Filter Functions
+ − 910 @cindex filter function
+ − 911 @cindex process filter
+ − 912
+ − 913 A process @dfn{filter function} is a function that receives the
+ − 914 standard output from the associated process. If a process has a filter,
+ − 915 then @emph{all} output from that process is passed to the filter. The
+ − 916 process buffer is used directly for output from the process only when
+ − 917 there is no filter.
+ − 918
+ − 919 A filter function must accept two arguments: the associated process and
+ − 920 a string, which is the output. The function is then free to do whatever it
+ − 921 chooses with the output.
+ − 922
+ − 923 A filter function runs only while XEmacs is waiting (e.g., for terminal
+ − 924 input, or for time to elapse, or for process output). This avoids the
+ − 925 timing errors that could result from running filters at random places in
+ − 926 the middle of other Lisp programs. You may explicitly cause Emacs to
+ − 927 wait, so that filter functions will run, by calling @code{sit-for} or
+ − 928 @code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output}
+ − 929 (@pxref{Accepting Output}). Emacs is also waiting when the command loop
+ − 930 is reading input.
+ − 931
+ − 932 Quitting is normally inhibited within a filter function---otherwise,
+ − 933 the effect of typing @kbd{C-g} at command level or to quit a user
+ − 934 command would be unpredictable. If you want to permit quitting inside a
+ − 935 filter function, bind @code{inhibit-quit} to @code{nil}.
+ − 936 @xref{Quitting}.
+ − 937
+ − 938 If an error happens during execution of a filter function, it is
+ − 939 caught automatically, so that it doesn't stop the execution of whatever
+ − 940 program was running when the filter function was started. However, if
+ − 941 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
+ − 942 off. This makes it possible to use the Lisp debugger to debug the
+ − 943 filter function. @xref{Debugger}.
+ − 944
+ − 945 Many filter functions sometimes or always insert the text in the
+ − 946 process's buffer, mimicking the actions of XEmacs when there is no
+ − 947 filter. Such filter functions need to use @code{set-buffer} in order to
+ − 948 be sure to insert in that buffer. To avoid setting the current buffer
+ − 949 semipermanently, these filter functions must use @code{unwind-protect}
+ − 950 to make sure to restore the previous current buffer. They should also
+ − 951 update the process marker, and in some cases update the value of point.
+ − 952 Here is how to do these things:
+ − 953
+ − 954 @smallexample
+ − 955 @group
444
+ − 956 (defun ordinary-insertion-filter (process string)
0
+ − 957 (let ((old-buffer (current-buffer)))
+ − 958 (unwind-protect
+ − 959 (let (moving)
444
+ − 960 (set-buffer (process-buffer process))
+ − 961 (setq moving (= (point) (process-mark process)))
0
+ − 962 @end group
+ − 963 @group
+ − 964 (save-excursion
+ − 965 ;; @r{Insert the text, moving the process-marker.}
444
+ − 966 (goto-char (process-mark process))
0
+ − 967 (insert string)
444
+ − 968 (set-marker (process-mark process) (point)))
+ − 969 (if moving (goto-char (process-mark process))))
0
+ − 970 (set-buffer old-buffer))))
+ − 971 @end group
+ − 972 @end smallexample
+ − 973
+ − 974 @noindent
+ − 975 The reason to use an explicit @code{unwind-protect} rather than letting
+ − 976 @code{save-excursion} restore the current buffer is so as to preserve
+ − 977 the change in point made by @code{goto-char}.
+ − 978
+ − 979 To make the filter force the process buffer to be visible whenever new
+ − 980 text arrives, insert the following line just before the
+ − 981 @code{unwind-protect}:
+ − 982
+ − 983 @smallexample
444
+ − 984 (display-buffer (process-buffer process))
0
+ − 985 @end smallexample
+ − 986
+ − 987 To force point to move to the end of the new output no matter where
+ − 988 it was previously, eliminate the variable @code{moving} and call
+ − 989 @code{goto-char} unconditionally.
+ − 990
+ − 991 In earlier Emacs versions, every filter function that did regexp
+ − 992 searching or matching had to explicitly save and restore the match data.
+ − 993 Now Emacs does this automatically; filter functions never need to do it
+ − 994 explicitly. @xref{Match Data}.
+ − 995
+ − 996 A filter function that writes the output into the buffer of the
+ − 997 process should check whether the buffer is still alive. If it tries to
+ − 998 insert into a dead buffer, it will get an error. If the buffer is dead,
+ − 999 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
+ − 1000
+ − 1001 The output to the function may come in chunks of any size. A program
+ − 1002 that produces the same output twice in a row may send it as one batch
+ − 1003 of 200 characters one time, and five batches of 40 characters the next.
+ − 1004
+ − 1005 @defun set-process-filter process filter
+ − 1006 This function gives @var{process} the filter function @var{filter}. If
+ − 1007 @var{filter} is @code{nil}, then the process will have no filter. If
+ − 1008 @var{filter} is @code{t}, then no output from the process will be
+ − 1009 accepted until the filter is changed. (Output received during this
+ − 1010 time is not discarded, but is queued, and will be processed as soon
+ − 1011 as the filter is changed.)
+ − 1012 @end defun
+ − 1013
+ − 1014 @defun process-filter process
+ − 1015 This function returns the filter function of @var{process}, or @code{nil}
+ − 1016 if it has none. @code{t} means that output processing has been stopped.
+ − 1017 @end defun
+ − 1018
+ − 1019 Here is an example of use of a filter function:
+ − 1020
+ − 1021 @smallexample
+ − 1022 @group
+ − 1023 (defun keep-output (process output)
+ − 1024 (setq kept (cons output kept)))
+ − 1025 @result{} keep-output
+ − 1026 @end group
+ − 1027 @group
+ − 1028 (setq kept nil)
+ − 1029 @result{} nil
+ − 1030 @end group
+ − 1031 @group
+ − 1032 (set-process-filter (get-process "shell") 'keep-output)
+ − 1033 @result{} keep-output
+ − 1034 @end group
+ − 1035 @group
+ − 1036 (process-send-string "shell" "ls ~/other\n")
+ − 1037 @result{} nil
+ − 1038 kept
+ − 1039 @result{} ("lewis@@slug[8] % "
+ − 1040 @end group
+ − 1041 @group
+ − 1042 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
+ − 1043 address.txt backup.psf kolstad.psf
+ − 1044 backup.bib~ david.mss resume-Dec-86.mss~
+ − 1045 backup.err david.psf resume-Dec.psf
+ − 1046 backup.mss dland syllabus.mss
+ − 1047 "
+ − 1048 "#backups.mss# backup.mss~ kolstad.mss
+ − 1049 ")
+ − 1050 @end group
+ − 1051 @end smallexample
+ − 1052
+ − 1053 @ignore @c The code in this example doesn't show the right way to do things.
+ − 1054 Here is another, more realistic example, which demonstrates how to use
+ − 1055 the process mark to do insertion in the same fashion as is done when
+ − 1056 there is no filter function:
+ − 1057
+ − 1058 @smallexample
+ − 1059 @group
+ − 1060 ;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
+ − 1061 ;; @r{and make sure that buffer is shown in some window.}
444
+ − 1062 (defun my-process-filter (process string)
0
+ − 1063 (let ((cur (selected-window))
+ − 1064 (pop-up-windows t))
+ − 1065 (pop-to-buffer my-shell-buffer)
+ − 1066 @end group
+ − 1067 @group
+ − 1068 (goto-char (point-max))
444
+ − 1069 (insert string)
+ − 1070 (set-marker (process-mark process) (point-max))
0
+ − 1071 (select-window cur)))
+ − 1072 @end group
+ − 1073 @end smallexample
+ − 1074 @end ignore
+ − 1075
+ − 1076 @node Accepting Output
+ − 1077 @subsection Accepting Output from Processes
+ − 1078
+ − 1079 Output from asynchronous subprocesses normally arrives only while
+ − 1080 XEmacs is waiting for some sort of external event, such as elapsed time
+ − 1081 or terminal input. Occasionally it is useful in a Lisp program to
+ − 1082 explicitly permit output to arrive at a specific point, or even to wait
+ − 1083 until output arrives from a process.
+ − 1084
+ − 1085 @defun accept-process-output &optional process seconds millisec
+ − 1086 This function allows XEmacs to read pending output from processes. The
+ − 1087 output is inserted in the associated buffers or given to their filter
+ − 1088 functions. If @var{process} is non-@code{nil} then this function does
+ − 1089 not return until some output has been received from @var{process}.
+ − 1090
+ − 1091 @c Emacs 19 feature
+ − 1092 The arguments @var{seconds} and @var{millisec} let you specify timeout
+ − 1093 periods. The former specifies a period measured in seconds and the
+ − 1094 latter specifies one measured in milliseconds. The two time periods
+ − 1095 thus specified are added together, and @code{accept-process-output}
+ − 1096 returns after that much time whether or not there has been any
+ − 1097 subprocess output. Note that @var{seconds} is allowed to be a
+ − 1098 floating-point number; thus, there is no need to ever use
+ − 1099 @var{millisec}. (It is retained for compatibility purposes.)
+ − 1100 @ignore Not in XEmacs
+ − 1101
+ − 1102 The argument @var{seconds} need not be an integer. If it is a floating
+ − 1103 point number, this function waits for a fractional number of seconds.
+ − 1104 Some systems support only a whole number of seconds; on these systems,
+ − 1105 @var{seconds} is rounded down. If the system doesn't support waiting
+ − 1106 fractions of a second, you get an error if you specify nonzero
+ − 1107 @var{millisec}.
+ − 1108
+ − 1109 Not all operating systems support waiting periods other than multiples
+ − 1110 of a second; on those that do not, you get an error if you specify
+ − 1111 nonzero @var{millisec}.
+ − 1112 @end ignore
+ − 1113
+ − 1114 The function @code{accept-process-output} returns non-@code{nil} if it
+ − 1115 did get some output, or @code{nil} if the timeout expired before output
+ − 1116 arrived.
+ − 1117 @end defun
+ − 1118
+ − 1119 @node Sentinels
+ − 1120 @section Sentinels: Detecting Process Status Changes
+ − 1121 @cindex process sentinel
+ − 1122 @cindex sentinel
+ − 1123
+ − 1124 A @dfn{process sentinel} is a function that is called whenever the
+ − 1125 associated process changes status for any reason, including signals
+ − 1126 (whether sent by XEmacs or caused by the process's own actions) that
+ − 1127 terminate, stop, or continue the process. The process sentinel is also
+ − 1128 called if the process exits. The sentinel receives two arguments: the
+ − 1129 process for which the event occurred, and a string describing the type
+ − 1130 of event.
+ − 1131
+ − 1132 The string describing the event looks like one of the following:
+ − 1133
+ − 1134 @itemize @bullet
442
+ − 1135 @item
0
+ − 1136 @code{"finished\n"}.
+ − 1137
+ − 1138 @item
+ − 1139 @code{"exited abnormally with code @var{exitcode}\n"}.
+ − 1140
+ − 1141 @item
+ − 1142 @code{"@var{name-of-signal}\n"}.
+ − 1143
+ − 1144 @item
+ − 1145 @code{"@var{name-of-signal} (core dumped)\n"}.
+ − 1146 @end itemize
+ − 1147
+ − 1148 A sentinel runs only while XEmacs is waiting (e.g., for terminal input,
+ − 1149 or for time to elapse, or for process output). This avoids the timing
+ − 1150 errors that could result from running them at random places in the
+ − 1151 middle of other Lisp programs. A program can wait, so that sentinels
+ − 1152 will run, by calling @code{sit-for} or @code{sleep-for}
+ − 1153 (@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
+ − 1154 Output}). Emacs is also waiting when the command loop is reading input.
+ − 1155
+ − 1156 Quitting is normally inhibited within a sentinel---otherwise, the
+ − 1157 effect of typing @kbd{C-g} at command level or to quit a user command
+ − 1158 would be unpredictable. If you want to permit quitting inside a
+ − 1159 sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}.
+ − 1160
+ − 1161 A sentinel that writes the output into the buffer of the process
+ − 1162 should check whether the buffer is still alive. If it tries to insert
+ − 1163 into a dead buffer, it will get an error. If the buffer is dead,
+ − 1164 @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
+ − 1165
+ − 1166 If an error happens during execution of a sentinel, it is caught
+ − 1167 automatically, so that it doesn't stop the execution of whatever
+ − 1168 programs was running when the sentinel was started. However, if
+ − 1169 @code{debug-on-error} is non-@code{nil}, the error-catching is turned
+ − 1170 off. This makes it possible to use the Lisp debugger to debug the
+ − 1171 sentinel. @xref{Debugger}.
+ − 1172
+ − 1173 In earlier Emacs versions, every sentinel that did regexp searching or
+ − 1174 matching had to explicitly save and restore the match data. Now Emacs
+ − 1175 does this automatically; sentinels never need to do it explicitly.
+ − 1176 @xref{Match Data}.
+ − 1177
+ − 1178 @defun set-process-sentinel process sentinel
+ − 1179 This function associates @var{sentinel} with @var{process}. If
+ − 1180 @var{sentinel} is @code{nil}, then the process will have no sentinel.
+ − 1181 The default behavior when there is no sentinel is to insert a message in
+ − 1182 the process's buffer when the process status changes.
+ − 1183
+ − 1184 @smallexample
+ − 1185 @group
+ − 1186 (defun msg-me (process event)
+ − 1187 (princ
+ − 1188 (format "Process: %s had the event `%s'" process event)))
+ − 1189 (set-process-sentinel (get-process "shell") 'msg-me)
+ − 1190 @result{} msg-me
+ − 1191 @end group
+ − 1192 @group
+ − 1193 (kill-process (get-process "shell"))
+ − 1194 @print{} Process: #<process shell> had the event `killed'
+ − 1195 @result{} #<process shell>
+ − 1196 @end group
+ − 1197 @end smallexample
+ − 1198 @end defun
+ − 1199
+ − 1200 @defun process-sentinel process
+ − 1201 This function returns the sentinel of @var{process}, or @code{nil} if it
+ − 1202 has none.
+ − 1203 @end defun
+ − 1204
+ − 1205 @defun waiting-for-user-input-p
+ − 1206 While a sentinel or filter function is running, this function returns
+ − 1207 non-@code{nil} if XEmacs was waiting for keyboard input from the user at
+ − 1208 the time the sentinel or filter function was called, @code{nil} if it
+ − 1209 was not.
+ − 1210 @end defun
+ − 1211
+ − 1212 @c XEmacs feature
+ − 1213 @node Process Window Size
+ − 1214 @section Process Window Size
+ − 1215 @cindex process window size
+ − 1216
+ − 1217 @defun set-process-window-size process height width
+ − 1218 This function tells @var{process} that its logical window size is
+ − 1219 @var{height} by @var{width} characters. This is principally useful
+ − 1220 with pty's.
+ − 1221 @end defun
+ − 1222
+ − 1223 @node Transaction Queues
+ − 1224 @section Transaction Queues
+ − 1225 @cindex transaction queue
+ − 1226
+ − 1227 You can use a @dfn{transaction queue} for more convenient communication
+ − 1228 with subprocesses using transactions. First use @code{tq-create} to
+ − 1229 create a transaction queue communicating with a specified process. Then
+ − 1230 you can call @code{tq-enqueue} to send a transaction.
+ − 1231
+ − 1232 @defun tq-create process
+ − 1233 This function creates and returns a transaction queue communicating with
+ − 1234 @var{process}. The argument @var{process} should be a subprocess
+ − 1235 capable of sending and receiving streams of bytes. It may be a child
+ − 1236 process, or it may be a TCP connection to a server, possibly on another
+ − 1237 machine.
+ − 1238 @end defun
+ − 1239
+ − 1240 @defun tq-enqueue queue question regexp closure fn
+ − 1241 This function sends a transaction to queue @var{queue}. Specifying the
+ − 1242 queue has the effect of specifying the subprocess to talk to.
+ − 1243
+ − 1244 The argument @var{question} is the outgoing message that starts the
+ − 1245 transaction. The argument @var{fn} is the function to call when the
+ − 1246 corresponding answer comes back; it is called with two arguments:
+ − 1247 @var{closure}, and the answer received.
+ − 1248
+ − 1249 The argument @var{regexp} is a regular expression that should match the
+ − 1250 entire answer, but nothing less; that's how @code{tq-enqueue} determines
+ − 1251 where the answer ends.
+ − 1252
+ − 1253 The return value of @code{tq-enqueue} itself is not meaningful.
+ − 1254 @end defun
+ − 1255
+ − 1256 @defun tq-close queue
+ − 1257 Shut down transaction queue @var{queue}, waiting for all pending transactions
+ − 1258 to complete, and then terminate the connection or child process.
+ − 1259 @end defun
+ − 1260
+ − 1261 Transaction queues are implemented by means of a filter function.
+ − 1262 @xref{Filter Functions}.
+ − 1263
+ − 1264 @node Network
+ − 1265 @section Network Connections
+ − 1266 @cindex network connection
+ − 1267 @cindex TCP
+ − 1268
+ − 1269 XEmacs Lisp programs can open TCP network connections to other processes on
+ − 1270 the same machine or other machines. A network connection is handled by Lisp
+ − 1271 much like a subprocess, and is represented by a process object.
+ − 1272 However, the process you are communicating with is not a child of the
+ − 1273 XEmacs process, so you can't kill it or send it signals. All you can do
+ − 1274 is send and receive data. @code{delete-process} closes the connection,
+ − 1275 but does not kill the process at the other end; that process must decide
+ − 1276 what to do about closure of the connection.
+ − 1277
+ − 1278 You can distinguish process objects representing network connections
+ − 1279 from those representing subprocesses with the @code{process-status}
+ − 1280 function. It always returns either @code{open} or @code{closed} for a
+ − 1281 network connection, and it never returns either of those values for a
+ − 1282 real subprocess. @xref{Process Information}.
+ − 1283
444
+ − 1284 @defun open-network-stream name buffer-or-name host service &optional protocol
0
+ − 1285 This function opens a TCP connection for a service to a host. It
+ − 1286 returns a process object to represent the connection.
+ − 1287
444
+ − 1288 Input and output work as for other process objects.
+ − 1289 @code{delete-process} closes the connection.
+ − 1290
0
+ − 1291 The @var{name} argument specifies the name for the process object. It
+ − 1292 is modified as necessary to make it unique.
+ − 1293
+ − 1294 The @var{buffer-or-name} argument is the buffer to associate with the
444
+ − 1295 connection. It can be a buffer or the name of one. Output from the
+ − 1296 connection is inserted in the buffer, unless you specify a filter
+ − 1297 function to handle the output. If @var{buffer-or-name} is @code{nil},
+ − 1298 it means that the connection is not associated with any buffer.
0
+ − 1299
+ − 1300 The arguments @var{host} and @var{service} specify where to connect to;
+ − 1301 @var{host} is the host name or IP address (a string), and @var{service}
+ − 1302 is the name of a defined network service (a string) or a port number (an
+ − 1303 integer).
444
+ − 1304
+ − 1305 Optional fifth arg @var{protocol} is the network protocol to use.
+ − 1306 Currently only @code{tcp} (Transmission Control Protocol) and @code{udp}
+ − 1307 (User Datagram Protocol) are supported. When omitted, @code{tcp} is assumed.
+ − 1308
+ − 1309 Output via @code{process-send-string} and input via buffer or filter
+ − 1310 (see @code{set-process-filter}) are stream-oriented. That means
+ − 1311 UDP datagrams are not guaranteed to be sent and received in
+ − 1312 discrete packets. (But small datagrams around 500 bytes that are not
+ − 1313 truncated by @code{process-send-string} are usually fine.) Note further
+ − 1314 that the UDP protocol does not guard against lost packets.
0
+ − 1315 @end defun