1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
55 Working With a Database
56 =======================
58 - Function: get-database key dbase &optional default
59 This function finds the value for KEY in DATABASE. If there is no
60 corresponding value, DEFAULT is returned (`nil' if DEFAULT is
63 - Function: map-database function dbase
64 This function maps FUNCTION over entries in DATABASE, calling it
65 with two args, each key and value in the database.
67 - Function: put-database key val dbase &optional replace
68 This function stores KEY and VAL in DATABASE. If optional fourth
69 arg REPLACE is non-`nil', replace any existing entry in the
72 - Function: remove-database key dbase
73 This function removes KEY from DATABASE.
76 File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
78 Other Database Functions
79 ========================
81 - Function: database-file-name obj
82 This function returns the filename associated with the database
85 - Function: database-last-error &optional obj
86 This function returns the last error associated with database OBJ.
88 - Function: database-subtype obj
89 This function returns the subtype of database OBJ, if any.
91 - Function: database-type obj
92 This function returns the type of database OBJ.
95 File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
100 In the terminology of operating systems, a "process" is a space in
101 which a program can execute. XEmacs runs in a process. XEmacs Lisp
102 programs can invoke other programs in processes of their own. These are
103 called "subprocesses" or "child processes" of the XEmacs process, which
104 is their "parent process".
106 A subprocess of XEmacs may be "synchronous" or "asynchronous",
107 depending on how it is created. When you create a synchronous
108 subprocess, the Lisp program waits for the subprocess to terminate
109 before continuing execution. When you create an asynchronous
110 subprocess, it can run in parallel with the Lisp program. This kind of
111 subprocess is represented within XEmacs by a Lisp object which is also
112 called a "process". Lisp programs can use this object to communicate
113 with the subprocess or to control it. For example, you can send
114 signals, obtain status information, receive output from the process, or
117 - Function: processp object
118 This function returns `t' if OBJECT is a process, `nil' otherwise.
122 * Subprocess Creation:: Functions that start subprocesses.
123 * Synchronous Processes:: Details of using synchronous subprocesses.
124 * MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
125 for data sent to and from a subprocess.
126 * Asynchronous Processes:: Starting up an asynchronous subprocess.
127 * Deleting Processes:: Eliminating an asynchronous subprocess.
128 * Process Information:: Accessing run-status and other attributes.
129 * Input to Processes:: Sending input to an asynchronous subprocess.
130 * Signals to Processes:: Stopping, continuing or interrupting
131 an asynchronous subprocess.
132 * Output from Processes:: Collecting output from an asynchronous subprocess.
133 * Sentinels:: Sentinels run when process run-status changes.
134 * Process Window Size:: Changing the logical window size of a process.
135 * Transaction Queues:: Transaction-based communication with subprocesses.
136 * Network:: Opening network connections.
139 File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
141 Functions that Create Subprocesses
142 ==================================
144 There are three functions that create a new subprocess in which to
145 run a program. One of them, `start-process', creates an asynchronous
146 process and returns a process object (*note Asynchronous Processes::).
147 The other two, `call-process' and `call-process-region', create a
148 synchronous process and do not return a process object (*note
149 Synchronous Processes::).
151 Synchronous and asynchronous processes are explained in following
152 sections. Since the three functions are all called in a similar
153 fashion, their common arguments are described here.
155 In all cases, the function's PROGRAM argument specifies the program
156 to be run. An error is signaled if the file is not found or cannot be
157 executed. If the file name is relative, the variable `exec-path'
158 contains a list of directories to search. Emacs initializes
159 `exec-path' when it starts up, based on the value of the environment
160 variable `PATH'. The standard file name constructs, `~', `.', and
161 `..', are interpreted as usual in `exec-path', but environment variable
162 substitutions (`$HOME', etc.) are not recognized; use
163 `substitute-in-file-name' to perform them (*note File Name Expansion::).
165 Each of the subprocess-creating functions has a BUFFER-OR-NAME
166 argument which specifies where the standard output from the program will
167 go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
168 a filter function handles it. (*Note Filter Functions::, and *Note
169 Read and Print::.) Normally, you should avoid having multiple
170 processes send output to the same buffer because their output would be
173 All three of the subprocess-creating functions have a `&rest'
174 argument, ARGS. The ARGS must all be strings, and they are supplied to
175 PROGRAM as separate command line arguments. Wildcard characters and
176 other shell constructs are not allowed in these strings, since they are
177 passed directly to the specified program.
179 *Please note:* The argument PROGRAM contains only the name of the
180 program; it may not contain any command-line arguments. You must use
181 ARGS to provide those.
183 The subprocess gets its current directory from the value of
184 `default-directory' (*note File Name Expansion::).
186 The subprocess inherits its environment from XEmacs; but you can
187 specify overrides for it with `process-environment'. *Note System
190 - Variable: exec-directory
191 The value of this variable is the name of a directory (a string)
192 that contains programs that come with XEmacs, that are intended
193 for XEmacs to invoke. The program `wakeup' is an example of such
194 a program; the `display-time' command uses it to get a reminder
197 - User Option: exec-path
198 The value of this variable is a list of directories to search for
199 programs to run in subprocesses. Each element is either the name
200 of a directory (i.e., a string), or `nil', which stands for the
201 default directory (which is the value of `default-directory').
203 The value of `exec-path' is used by `call-process' and
204 `start-process' when the PROGRAM argument is not an absolute file
208 File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
210 Creating a Synchronous Process
211 ==============================
213 After a "synchronous process" is created, XEmacs waits for the
214 process to terminate before continuing. Starting Dired is an example of
215 this: it runs `ls' in a synchronous process, then modifies the output
216 slightly. Because the process is synchronous, the entire directory
217 listing arrives in the buffer before XEmacs tries to do anything with
220 While Emacs waits for the synchronous subprocess to terminate, the
221 user can quit by typing `C-g'. The first `C-g' tries to kill the
222 subprocess with a `SIGINT' signal; but it waits until the subprocess
223 actually terminates before quitting. If during that time the user
224 types another `C-g', that kills the subprocess instantly with `SIGKILL'
225 and quits immediately. *Note Quitting::.
227 The synchronous subprocess functions returned `nil' in version 18.
228 In version 19, they return an indication of how the process terminated.
230 - Function: call-process program &optional infile destination display
232 This function calls PROGRAM in a separate process and waits for it
235 The standard input for the process comes from file INFILE if
236 INFILE is not `nil' and from `/dev/null' otherwise. The argument
237 DESTINATION says where to put the process output. Here are the
241 Insert the output in that buffer, before point. This
242 includes both the standard output stream and the standard
243 error stream of the process.
246 Find or create a buffer with that name, then insert the
247 output in that buffer, before point.
250 Insert the output in the current buffer, before point.
256 Discard the output, and return immediately without waiting
257 for the subprocess to finish.
259 In this case, the process is not truly synchronous, since it
260 can run in parallel with Emacs; but you can think of it as
261 synchronous in that Emacs is essentially finished with the
262 subprocess as soon as this function returns.
264 (REAL-DESTINATION ERROR-DESTINATION)
265 Keep the standard output stream separate from the standard
266 error stream; deal with the ordinary output as specified by
267 REAL-DESTINATION, and dispose of the error output according
268 to ERROR-DESTINATION. The value `nil' means discard it, `t'
269 means mix it with the ordinary output, and a string specifies
270 a file name to redirect error output into.
272 You can't directly specify a buffer to put the error output
273 in; that is too difficult to implement. But you can achieve
274 this result by sending the error output to a temporary file
275 and then inserting the file into a buffer.
277 If DISPLAY is non-`nil', then `call-process' redisplays the buffer
278 as output is inserted. Otherwise the function does no redisplay,
279 and the results become visible on the screen only when XEmacs
280 redisplays that buffer in the normal course of events.
282 The remaining arguments, ARGS, are strings that specify command
283 line arguments for the program.
285 The value returned by `call-process' (unless you told it not to
286 wait) indicates the reason for process termination. A number
287 gives the exit status of the subprocess; 0 means success, and any
288 other value means failure. If the process terminated with a
289 signal, `call-process' returns a string describing the signal.
291 In the examples below, the buffer `foo' is current.
293 (call-process "pwd" nil t)
296 ---------- Buffer: foo ----------
297 /usr/user/lewis/manual
298 ---------- Buffer: foo ----------
300 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
303 ---------- Buffer: bar ----------
304 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
306 ---------- Buffer: bar ----------
308 The `insert-directory' function contains a good example of the use
311 (call-process insert-directory-program nil t nil switches
313 (concat (file-name-as-directory file) ".")
316 - Function: call-process-region start end program &optional delete
317 destination display &rest args
318 This function sends the text between START to END as standard
319 input to a process running PROGRAM. It deletes the text sent if
320 DELETE is non-`nil'; this is useful when BUFFER is `t', to insert
321 the output in the current buffer.
323 The arguments DESTINATION and DISPLAY control what to do with the
324 output from the subprocess, and whether to update the display as
325 it comes in. For details, see the description of `call-process',
326 above. If DESTINATION is the integer 0, `call-process-region'
327 discards the output and returns `nil' immediately, without waiting
328 for the subprocess to finish.
330 The remaining arguments, ARGS, are strings that specify command
331 line arguments for the program.
333 The return value of `call-process-region' is just like that of
334 `call-process': `nil' if you told it to return without waiting;
335 otherwise, a number or string which indicates how the subprocess
338 In the following example, we use `call-process-region' to run the
339 `cat' utility, with standard input being the first five characters
340 in buffer `foo' (the word `input'). `cat' copies its standard
341 input into its standard output. Since the argument DESTINATION is
342 `t', this output is inserted in the current buffer.
344 ---------- Buffer: foo ----------
346 ---------- Buffer: foo ----------
348 (call-process-region 1 6 "cat" nil t)
351 ---------- Buffer: foo ----------
353 ---------- Buffer: foo ----------
355 The `shell-command-on-region' command uses `call-process-region'
360 shell-file-name ; Name of program.
361 nil ; Do not delete region.
362 buffer ; Send output to `buffer'.
363 nil ; No redisplay during output.
364 "-c" command) ; Arguments for the shell.
367 File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
372 On MS-DOS, you must indicate whether the data going to and from a
373 synchronous subprocess are text or binary. Text data requires
374 translation between the end-of-line convention used within Emacs (a
375 single newline character) and the convention used outside Emacs (the
376 two-character sequence, CRLF).
378 The variable `binary-process-input' applies to input sent to the
379 subprocess, and `binary-process-output' applies to output received from
380 it. A non-`nil' value means the data is non-text; `nil' means the data
381 is text, and calls for conversion.
383 - Variable: binary-process-input
384 If this variable is `nil', convert newlines to CRLF sequences in
385 the input to a synchronous subprocess.
387 - Variable: binary-process-output
388 If this variable is `nil', convert CRLF sequences to newlines in
389 the output from a synchronous subprocess.
391 *Note Files and MS-DOS::, for related information.
394 File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
396 Creating an Asynchronous Process
397 ================================
399 After an "asynchronous process" is created, Emacs and the Lisp
400 program both continue running immediately. The process may thereafter
401 run in parallel with Emacs, and the two may communicate with each other
402 using the functions described in following sections. Here we describe
403 how to create an asynchronous process with `start-process'.
405 - Function: start-process name buffer-or-name program &rest args
406 This function creates a new asynchronous subprocess and starts the
407 program PROGRAM running in it. It returns a process object that
408 stands for the new subprocess in Lisp. The argument NAME
409 specifies the name for the process object; if a process with this
410 name already exists, then NAME is modified (by adding `<1>', etc.)
411 to be unique. The buffer BUFFER-OR-NAME is the buffer to
412 associate with the process.
414 The remaining arguments, ARGS, are strings that specify command
415 line arguments for the program.
417 In the example below, the first process is started and runs
418 (rather, sleeps) for 100 seconds. Meanwhile, the second process
419 is started, and given the name `my-process<1>' for the sake of
420 uniqueness. It inserts the directory listing at the end of the
421 buffer `foo', before the first process finishes. Then it
422 finishes, and a message to that effect is inserted in the buffer.
423 Much later, the first process finishes, and another message is
424 inserted in the buffer for it.
426 (start-process "my-process" "foo" "sleep" "100")
427 => #<process my-process>
429 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
430 => #<process my-process<1>>
432 ---------- Buffer: foo ----------
434 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
435 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
437 Process my-process<1> finished
439 Process my-process finished
440 ---------- Buffer: foo ----------
442 - Function: start-process-shell-command name buffer-or-name command
444 This function is like `start-process' except that it uses a shell
445 to execute the specified command. The argument COMMAND is a shell
446 command name, and COMMAND-ARGS are the arguments for the shell
449 - Variable: process-connection-type
450 This variable controls the type of device used to communicate with
451 asynchronous subprocesses. If it is non-`nil', then PTYs are
452 used, when available. Otherwise, pipes are used.
454 PTYs are usually preferable for processes visible to the user, as
455 in Shell mode, because they allow job control (`C-c', `C-z', etc.)
456 to work between the process and its children whereas pipes do not.
457 For subprocesses used for internal purposes by programs, it is
458 often better to use a pipe, because they are more efficient. In
459 addition, the total number of PTYs is limited on many systems and
460 it is good not to waste them.
462 The value `process-connection-type' is used when `start-process'
463 is called. So you can specify how to communicate with one
464 subprocess by binding the variable around the call to
467 (let ((process-connection-type nil)) ; Use a pipe.
470 To determine whether a given subprocess actually got a pipe or a
471 PTY, use the function `process-tty-name' (*note Process
475 File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
480 "Deleting a process" disconnects XEmacs immediately from the
481 subprocess, and removes it from the list of active processes. It sends
482 a signal to the subprocess to make the subprocess terminate, but this is
483 not guaranteed to happen immediately. The process object itself
484 continues to exist as long as other Lisp objects point to it.
486 You can delete a process explicitly at any time. Processes are
487 deleted automatically after they terminate, but not necessarily right
488 away. If you delete a terminated process explicitly before it is
489 deleted automatically, no harm results.
491 - Variable: delete-exited-processes
492 This variable controls automatic deletion of processes that have
493 terminated (due to calling `exit' or to a signal). If it is
494 `nil', then they continue to exist until the user runs
495 `list-processes'. Otherwise, they are deleted immediately after
498 - Function: delete-process name
499 This function deletes the process associated with NAME, killing it
500 with a `SIGHUP' signal. The argument NAME may be a process, the
501 name of a process, a buffer, or the name of a buffer.
503 (delete-process "*shell*")
506 - Function: process-kill-without-query process &optional
508 This function declares that XEmacs need not query the user if
509 PROCESS is still running when XEmacs is exited. The process will
510 be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
511 _will_ query the user (this is the default). The return value is
512 `t' if a query was formerly required, and `nil' otherwise.
514 (process-kill-without-query (get-process "shell"))
518 File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
523 Several functions return information about processes.
524 `list-processes' is provided for interactive use.
526 - Command: list-processes
527 This command displays a listing of all living processes. In
528 addition, it finally deletes any process whose status was `Exited'
529 or `Signaled'. It returns `nil'.
531 - Function: process-list
532 This function returns a list of all processes that have not been
536 => (#<process display-time> #<process shell>)
538 - Function: get-process name
539 This function returns the process named NAME, or `nil' if there is
540 none. An error is signaled if NAME is not a string.
542 (get-process "shell")
545 - Function: process-command process
546 This function returns the command that was executed to start
547 PROCESS. This is a list of strings, the first string being the
548 program executed and the rest of the strings being the arguments
549 that were given to the program.
551 (process-command (get-process "shell"))
554 - Function: process-id process
555 This function returns the PID of PROCESS. This is an integer that
556 distinguishes the process PROCESS from all other processes running
557 on the same computer at the current time. The PID of a process is
558 chosen by the operating system kernel when the process is started
559 and remains constant as long as the process exists.
561 - Function: process-name process
562 This function returns the name of PROCESS.
564 - Function: process-status process-name
565 This function returns the status of PROCESS-NAME as a symbol. The
566 argument PROCESS-NAME must be a process, a buffer, a process name
567 (string) or a buffer name (string).
569 The possible values for an actual subprocess are:
572 for a process that is running.
575 for a process that is stopped but continuable.
578 for a process that has exited.
581 for a process that has received a fatal signal.
584 for a network connection that is open.
587 for a network connection that is closed. Once a connection
588 is closed, you cannot reopen it, though you might be able to
589 open a new connection to the same place.
592 if PROCESS-NAME is not the name of an existing process.
594 (process-status "shell")
596 (process-status (get-buffer "*shell*"))
603 For a network connection, `process-status' returns one of the
604 symbols `open' or `closed'. The latter means that the other side
605 closed the connection, or XEmacs did `delete-process'.
607 In earlier Emacs versions (prior to version 19), the status of a
608 network connection was `run' if open, and `exit' if closed.
610 - Function: process-kill-without-query-p process
611 This function returns whether PROCESS will be killed without
612 querying the user, if it is running when XEmacs is exited. The
613 default value is `nil'.
615 - Function: process-exit-status process
616 This function returns the exit status of PROCESS or the signal
617 number that killed it. (Use the result of `process-status' to
618 determine which of those it is.) If PROCESS has not yet
619 terminated, the value is 0.
621 - Function: process-tty-name process
622 This function returns the terminal name that PROCESS is using for
623 its communication with Emacs--or `nil' if it is using pipes
624 instead of a terminal (see `process-connection-type' in *Note
625 Asynchronous Processes::).
628 File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
630 Sending Input to Processes
631 ==========================
633 Asynchronous subprocesses receive input when it is sent to them by
634 XEmacs, which is done with the functions in this section. You must
635 specify the process to send input to, and the input data to send. The
636 data appears on the "standard input" of the subprocess.
638 Some operating systems have limited space for buffered input in a
639 PTY. On these systems, Emacs sends an EOF periodically amidst the
640 other characters, to force them through. For most programs, these EOFs
643 - Function: process-send-string process-name string
644 This function sends PROCESS-NAME the contents of STRING as
645 standard input. The argument PROCESS-NAME must be a process or
646 the name of a process. If it is `nil', the current buffer's
649 The function returns `nil'.
651 (process-send-string "shell<1>" "ls\n")
655 ---------- Buffer: *shell* ----------
657 introduction.texi syntax-tables.texi~
658 introduction.texi~ text.texi
659 introduction.txt text.texi~
661 ---------- Buffer: *shell* ----------
663 - Command: process-send-region process-name start end
664 This function sends the text in the region defined by START and
665 END as standard input to PROCESS-NAME, which is a process or a
666 process name. (If it is `nil', the current buffer's process is
669 An error is signaled unless both START and END are integers or
670 markers that indicate positions in the current buffer. (It is
671 unimportant which number is larger.)
673 - Function: process-send-eof &optional process-name
674 This function makes PROCESS-NAME see an end-of-file in its input.
675 The EOF comes after any text already sent to it.
677 If PROCESS-NAME is not supplied, or if it is `nil', then this
678 function sends the EOF to the current buffer's process. An error
679 is signaled if the current buffer has no process.
681 The function returns PROCESS-NAME.
683 (process-send-eof "shell")
687 File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
689 Sending Signals to Processes
690 ============================
692 "Sending a signal" to a subprocess is a way of interrupting its
693 activities. There are several different signals, each with its own
694 meaning. The set of signals and their names is defined by the operating
695 system. For example, the signal `SIGINT' means that the user has typed
696 `C-c', or that some analogous thing has happened.
698 Each signal has a standard effect on the subprocess. Most signals
699 kill the subprocess, but some stop or resume execution instead. Most
700 signals can optionally be handled by programs; if the program handles
701 the signal, then we can say nothing in general about its effects.
703 The set of signals and their names is defined by the operating
704 system; XEmacs has facilities for sending only a few of the signals
705 that are defined. XEmacs can send signals only to its own subprocesses.
707 You can send signals explicitly by calling the functions in this
708 section. XEmacs also sends signals automatically at certain times:
709 killing a buffer sends a `SIGHUP' signal to all its associated
710 processes; killing XEmacs sends a `SIGHUP' signal to all remaining
711 processes. (`SIGHUP' is a signal that usually indicates that the user
714 Each of the signal-sending functions takes two optional arguments:
715 PROCESS-NAME and CURRENT-GROUP.
717 The argument PROCESS-NAME must be either a process, the name of one,
718 or `nil'. If it is `nil', the process defaults to the process
719 associated with the current buffer. An error is signaled if
720 PROCESS-NAME does not identify a process.
722 The argument CURRENT-GROUP is a flag that makes a difference when
723 you are running a job-control shell as an XEmacs subprocess. If it is
724 non-`nil', then the signal is sent to the current process-group of the
725 terminal that XEmacs uses to communicate with the subprocess. If the
726 process is a job-control shell, this means the shell's current subjob.
727 If it is `nil', the signal is sent to the process group of the
728 immediate subprocess of XEmacs. If the subprocess is a job-control
729 shell, this is the shell itself.
731 The flag CURRENT-GROUP has no effect when a pipe is used to
732 communicate with the subprocess, because the operating system does not
733 support the distinction in the case of pipes. For the same reason,
734 job-control shells won't work when a pipe is used. See
735 `process-connection-type' in *Note Asynchronous Processes::.
737 - Function: interrupt-process &optional process-name current-group
738 This function interrupts the process PROCESS-NAME by sending the
739 signal `SIGINT'. Outside of XEmacs, typing the "interrupt
740 character" (normally `C-c' on some systems, and `DEL' on others)
741 sends this signal. When the argument CURRENT-GROUP is non-`nil',
742 you can think of this function as "typing `C-c'" on the terminal
743 by which XEmacs talks to the subprocess.
745 - Function: kill-process &optional process-name current-group
746 This function kills the process PROCESS-NAME by sending the signal
747 `SIGKILL'. This signal kills the subprocess immediately, and
748 cannot be handled by the subprocess.
750 - Function: quit-process &optional process-name current-group
751 This function sends the signal `SIGQUIT' to the process
752 PROCESS-NAME. This signal is the one sent by the "quit character"
753 (usually `C-b' or `C-\') when you are not inside XEmacs.
755 - Function: stop-process &optional process-name current-group
756 This function stops the process PROCESS-NAME by sending the signal
757 `SIGTSTP'. Use `continue-process' to resume its execution.
759 On systems with job control, the "stop character" (usually `C-z')
760 sends this signal (outside of XEmacs). When CURRENT-GROUP is
761 non-`nil', you can think of this function as "typing `C-z'" on the
762 terminal XEmacs uses to communicate with the subprocess.
764 - Function: continue-process &optional process-name current-group
765 This function resumes execution of the process PROCESS by sending
766 it the signal `SIGCONT'. This presumes that PROCESS-NAME was
769 - Function: signal-process pid signal
770 This function sends a signal to process PID, which need not be a
771 child of XEmacs. The argument SIGNAL specifies which signal to
772 send; it should be an integer.
775 File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
777 Receiving Output from Processes
778 ===============================
780 There are two ways to receive the output that a subprocess writes to
781 its standard output stream. The output can be inserted in a buffer,
782 which is called the associated buffer of the process, or a function
783 called the "filter function" can be called to act on the output. If
784 the process has no buffer and no filter function, its output is
789 * Process Buffers:: If no filter, output is put in a buffer.
790 * Filter Functions:: Filter functions accept output from the process.
791 * Accepting Output:: Explicitly permitting subprocess output.
792 Waiting for subprocess output.
795 File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
800 A process can (and usually does) have an "associated buffer", which
801 is an ordinary Emacs buffer that is used for two purposes: storing the
802 output from the process, and deciding when to kill the process. You
803 can also use the buffer to identify a process to operate on, since in
804 normal practice only one process is associated with any given buffer.
805 Many applications of processes also use the buffer for editing input to
806 be sent to the process, but this is not built into XEmacs Lisp.
808 Unless the process has a filter function (*note Filter Functions::),
809 its output is inserted in the associated buffer. The position to insert
810 the output is determined by the `process-mark', which is then updated
811 to point to the end of the text just inserted. Usually, but not
812 always, the `process-mark' is at the end of the buffer.
814 - Function: process-buffer process
815 This function returns the associated buffer of the process PROCESS.
817 (process-buffer (get-process "shell"))
820 - Function: process-mark process
821 This function returns the process marker for PROCESS, which is the
822 marker that says where to insert output from the process.
824 If PROCESS does not have a buffer, `process-mark' returns a marker
827 Insertion of process output in a buffer uses this marker to decide
828 where to insert, and updates it to point after the inserted text.
829 That is why successive batches of output are inserted
832 Filter functions normally should use this marker in the same
833 fashion as is done by direct insertion of output in the buffer. A
834 good example of a filter function that uses `process-mark' is
835 found at the end of the following section.
837 When the user is expected to enter input in the process buffer for
838 transmission to the process, the process marker is useful for
839 distinguishing the new input from previous output.
841 - Function: set-process-buffer process buffer
842 This function sets the buffer associated with PROCESS to BUFFER.
843 If BUFFER is `nil', the process becomes associated with no buffer.
845 - Function: get-buffer-process buffer-or-name
846 This function returns the process associated with BUFFER-OR-NAME.
847 If there are several processes associated with it, then one is
848 chosen. (Presently, the one chosen is the one most recently
849 created.) It is usually a bad idea to have more than one process
850 associated with the same buffer.
852 (get-buffer-process "*shell*")
855 Killing the process's buffer deletes the process, which kills the
856 subprocess with a `SIGHUP' signal (*note Signals to Processes::).
859 File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
861 Process Filter Functions
862 ------------------------
864 A process "filter function" is a function that receives the standard
865 output from the associated process. If a process has a filter, then
866 _all_ output from that process is passed to the filter. The process
867 buffer is used directly for output from the process only when there is
870 A filter function must accept two arguments: the associated process
871 and a string, which is the output. The function is then free to do
872 whatever it chooses with the output.
874 A filter function runs only while XEmacs is waiting (e.g., for
875 terminal input, or for time to elapse, or for process output). This
876 avoids the timing errors that could result from running filters at
877 random places in the middle of other Lisp programs. You may explicitly
878 cause Emacs to wait, so that filter functions will run, by calling
879 `sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
880 (*note Accepting Output::). Emacs is also waiting when the command loop
883 Quitting is normally inhibited within a filter function--otherwise,
884 the effect of typing `C-g' at command level or to quit a user command
885 would be unpredictable. If you want to permit quitting inside a filter
886 function, bind `inhibit-quit' to `nil'. *Note Quitting::.
888 If an error happens during execution of a filter function, it is
889 caught automatically, so that it doesn't stop the execution of whatever
890 program was running when the filter function was started. However, if
891 `debug-on-error' is non-`nil', the error-catching is turned off. This
892 makes it possible to use the Lisp debugger to debug the filter
893 function. *Note Debugger::.
895 Many filter functions sometimes or always insert the text in the
896 process's buffer, mimicking the actions of XEmacs when there is no
897 filter. Such filter functions need to use `set-buffer' in order to be
898 sure to insert in that buffer. To avoid setting the current buffer
899 semipermanently, these filter functions must use `unwind-protect' to
900 make sure to restore the previous current buffer. They should also
901 update the process marker, and in some cases update the value of point.
902 Here is how to do these things:
904 (defun ordinary-insertion-filter (proc string)
905 (let ((old-buffer (current-buffer)))
908 (set-buffer (process-buffer proc))
909 (setq moving (= (point) (process-mark proc)))
911 ;; Insert the text, moving the process-marker.
912 (goto-char (process-mark proc))
914 (set-marker (process-mark proc) (point)))
915 (if moving (goto-char (process-mark proc))))
916 (set-buffer old-buffer))))
918 The reason to use an explicit `unwind-protect' rather than letting
919 `save-excursion' restore the current buffer is so as to preserve the
920 change in point made by `goto-char'.
922 To make the filter force the process buffer to be visible whenever
923 new text arrives, insert the following line just before the
926 (display-buffer (process-buffer proc))
928 To force point to move to the end of the new output no matter where
929 it was previously, eliminate the variable `moving' and call `goto-char'
932 In earlier Emacs versions, every filter function that did regexp
933 searching or matching had to explicitly save and restore the match data.
934 Now Emacs does this automatically; filter functions never need to do it
935 explicitly. *Note Match Data::.
937 A filter function that writes the output into the buffer of the
938 process should check whether the buffer is still alive. If it tries to
939 insert into a dead buffer, it will get an error. If the buffer is dead,
940 `(buffer-name (process-buffer PROCESS))' returns `nil'.
942 The output to the function may come in chunks of any size. A program
943 that produces the same output twice in a row may send it as one batch
944 of 200 characters one time, and five batches of 40 characters the next.
946 - Function: set-process-filter process filter
947 This function gives PROCESS the filter function FILTER. If FILTER
948 is `nil', then the process will have no filter. If FILTER is `t',
949 then no output from the process will be accepted until the filter
950 is changed. (Output received during this time is not discarded,
951 but is queued, and will be processed as soon as the filter is
954 - Function: process-filter process
955 This function returns the filter function of PROCESS, or `nil' if
956 it has none. `t' means that output processing has been stopped.
958 Here is an example of use of a filter function:
960 (defun keep-output (process output)
961 (setq kept (cons output kept)))
965 (set-process-filter (get-process "shell") 'keep-output)
967 (process-send-string "shell" "ls ~/other\n")
970 => ("lewis@slug[8] % "
971 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
972 address.txt backup.psf kolstad.psf
973 backup.bib~ david.mss resume-Dec-86.mss~
974 backup.err david.psf resume-Dec.psf
975 backup.mss dland syllabus.mss
977 "#backups.mss# backup.mss~ kolstad.mss
981 File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
983 Accepting Output from Processes
984 -------------------------------
986 Output from asynchronous subprocesses normally arrives only while
987 XEmacs is waiting for some sort of external event, such as elapsed time
988 or terminal input. Occasionally it is useful in a Lisp program to
989 explicitly permit output to arrive at a specific point, or even to wait
990 until output arrives from a process.
992 - Function: accept-process-output &optional process seconds millisec
993 This function allows XEmacs to read pending output from processes.
994 The output is inserted in the associated buffers or given to
995 their filter functions. If PROCESS is non-`nil' then this
996 function does not return until some output has been received from
999 The arguments SECONDS and MILLISEC let you specify timeout
1000 periods. The former specifies a period measured in seconds and the
1001 latter specifies one measured in milliseconds. The two time
1002 periods thus specified are added together, and
1003 `accept-process-output' returns after that much time whether or
1004 not there has been any subprocess output. Note that SECONDS is
1005 allowed to be a floating-point number; thus, there is no need to
1006 ever use MILLISEC. (It is retained for compatibility purposes.)
1008 The function `accept-process-output' returns non-`nil' if it did
1009 get some output, or `nil' if the timeout expired before output
1013 File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
1015 Sentinels: Detecting Process Status Changes
1016 ===========================================
1018 A "process sentinel" is a function that is called whenever the
1019 associated process changes status for any reason, including signals
1020 (whether sent by XEmacs or caused by the process's own actions) that
1021 terminate, stop, or continue the process. The process sentinel is also
1022 called if the process exits. The sentinel receives two arguments: the
1023 process for which the event occurred, and a string describing the type
1026 The string describing the event looks like one of the following:
1030 * `"exited abnormally with code EXITCODE\n"'.
1032 * `"NAME-OF-SIGNAL\n"'.
1034 * `"NAME-OF-SIGNAL (core dumped)\n"'.
1036 A sentinel runs only while XEmacs is waiting (e.g., for terminal
1037 input, or for time to elapse, or for process output). This avoids the
1038 timing errors that could result from running them at random places in
1039 the middle of other Lisp programs. A program can wait, so that
1040 sentinels will run, by calling `sit-for' or `sleep-for' (*note
1041 Waiting::), or `accept-process-output' (*note Accepting Output::).
1042 Emacs is also waiting when the command loop is reading input.
1044 Quitting is normally inhibited within a sentinel--otherwise, the
1045 effect of typing `C-g' at command level or to quit a user command would
1046 be unpredictable. If you want to permit quitting inside a sentinel,
1047 bind `inhibit-quit' to `nil'. *Note Quitting::.
1049 A sentinel that writes the output into the buffer of the process
1050 should check whether the buffer is still alive. If it tries to insert
1051 into a dead buffer, it will get an error. If the buffer is dead,
1052 `(buffer-name (process-buffer PROCESS))' returns `nil'.
1054 If an error happens during execution of a sentinel, it is caught
1055 automatically, so that it doesn't stop the execution of whatever
1056 programs was running when the sentinel was started. However, if
1057 `debug-on-error' is non-`nil', the error-catching is turned off. This
1058 makes it possible to use the Lisp debugger to debug the sentinel.
1061 In earlier Emacs versions, every sentinel that did regexp searching
1062 or matching had to explicitly save and restore the match data. Now
1063 Emacs does this automatically; sentinels never need to do it explicitly.
1066 - Function: set-process-sentinel process sentinel
1067 This function associates SENTINEL with PROCESS. If SENTINEL is
1068 `nil', then the process will have no sentinel. The default
1069 behavior when there is no sentinel is to insert a message in the
1070 process's buffer when the process status changes.
1072 (defun msg-me (process event)
1074 (format "Process: %s had the event `%s'" process event)))
1075 (set-process-sentinel (get-process "shell") 'msg-me)
1077 (kill-process (get-process "shell"))
1078 -| Process: #<process shell> had the event `killed'
1081 - Function: process-sentinel process
1082 This function returns the sentinel of PROCESS, or `nil' if it has
1085 - Function: waiting-for-user-input-p
1086 While a sentinel or filter function is running, this function
1087 returns non-`nil' if XEmacs was waiting for keyboard input from
1088 the user at the time the sentinel or filter function was called,
1089 `nil' if it was not.
1092 File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
1097 - Function: set-process-window-size process height width
1098 This function tells PROCESS that its logical window size is HEIGHT
1099 by WIDTH characters. This is principally useful with pty's.
1102 File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
1107 You can use a "transaction queue" for more convenient communication
1108 with subprocesses using transactions. First use `tq-create' to create
1109 a transaction queue communicating with a specified process. Then you
1110 can call `tq-enqueue' to send a transaction.
1112 - Function: tq-create process
1113 This function creates and returns a transaction queue
1114 communicating with PROCESS. The argument PROCESS should be a
1115 subprocess capable of sending and receiving streams of bytes. It
1116 may be a child process, or it may be a TCP connection to a server,
1117 possibly on another machine.
1119 - Function: tq-enqueue queue question regexp closure fn
1120 This function sends a transaction to queue QUEUE. Specifying the
1121 queue has the effect of specifying the subprocess to talk to.
1123 The argument QUESTION is the outgoing message that starts the
1124 transaction. The argument FN is the function to call when the
1125 corresponding answer comes back; it is called with two arguments:
1126 CLOSURE, and the answer received.
1128 The argument REGEXP is a regular expression that should match the
1129 entire answer, but nothing less; that's how `tq-enqueue' determines
1130 where the answer ends.
1132 The return value of `tq-enqueue' itself is not meaningful.
1134 - Function: tq-close queue
1135 Shut down transaction queue QUEUE, waiting for all pending
1136 transactions to complete, and then terminate the connection or
1139 Transaction queues are implemented by means of a filter function.
1140 *Note Filter Functions::.
1143 File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
1148 XEmacs Lisp programs can open TCP network connections to other
1149 processes on the same machine or other machines. A network connection
1150 is handled by Lisp much like a subprocess, and is represented by a
1151 process object. However, the process you are communicating with is not
1152 a child of the XEmacs process, so you can't kill it or send it signals.
1153 All you can do is send and receive data. `delete-process' closes the
1154 connection, but does not kill the process at the other end; that
1155 process must decide what to do about closure of the connection.
1157 You can distinguish process objects representing network connections
1158 from those representing subprocesses with the `process-status'
1159 function. It always returns either `open' or `closed' for a network
1160 connection, and it never returns either of those values for a real
1161 subprocess. *Note Process Information::.
1163 - Function: open-network-stream name buffer-or-name host service
1164 This function opens a TCP connection for a service to a host. It
1165 returns a process object to represent the connection.
1167 The NAME argument specifies the name for the process object. It
1168 is modified as necessary to make it unique.
1170 The BUFFER-OR-NAME argument is the buffer to associate with the
1171 connection. Output from the connection is inserted in the buffer,
1172 unless you specify a filter function to handle the output. If
1173 BUFFER-OR-NAME is `nil', it means that the connection is not
1174 associated with any buffer.
1176 The arguments HOST and SERVICE specify where to connect to; HOST
1177 is the host name or IP address (a string), and SERVICE is the name
1178 of a defined network service (a string) or a port number (an
projects / chise / xemacs-chise.git- / blob