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: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
58 A "weak hash table" is a special variety of hash table whose
59 elements do not count as GC referents. For any key-value pair in such a
60 hash table, if either the key or value (or in some cases, if one
61 particular one of the two) has no references to it outside of weak hash
62 tables (and similar structures such as weak lists), the pair will be
63 removed from the table, and the key and value collected. A non-weak
64 hash table (or any other pointer) would prevent the objects from being
67 Weak hash tables are useful for keeping track of information in a
68 non-obtrusive way, for example to implement caching. If the cache
69 contains objects such as buffers, markers, image instances, etc. that
70 will eventually disappear and get garbage-collected, using a weak hash
71 table ensures that these objects are collected normally rather than
72 remaining around forever, long past their actual period of use.
73 (Otherwise, you'd have to explicitly map over the hash table every so
74 often and remove unnecessary elements.)
76 There are three types of weak hash tables:
78 fully weak hash tables
79 In these hash tables, a pair disappears if either the key or the
80 value is unreferenced outside of the table.
83 In these hash tables, a pair disappears if the key is unreferenced
84 outside of the table, regardless of how the value is referenced.
86 value-weak hash tables
87 In these hash tables, a pair disappears if the value is
88 unreferenced outside of the table, regardless of how the key is
91 Also see *Note Weak Lists::.
93 Weak hash tables are created by specifying the `:weakness' keyword to
97 File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
102 A range table is a table that efficiently associated values with
105 Note that range tables have a read syntax, like this:
107 #s(range-table data ((-3 2) foo (5 20) bar))
109 This maps integers in the range (-3, 2) to `foo' and integers in the
110 range (5, 20) to `bar'.
112 - Function: range-table-p object
113 Return non-`nil' if OBJECT is a range table.
117 * Introduction to Range Tables:: Range tables efficiently map ranges of
119 * Working With Range Tables:: Range table functions.
122 File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
124 Introduction to Range Tables
125 ============================
127 - Function: make-range-table
128 Make a new, empty range table.
130 - Function: copy-range-table old-table
131 Make a new range table which contains the same values for the same
132 ranges as the given table. The values will not themselves be
136 File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
138 Working With Range Tables
139 =========================
141 - Function: get-range-table pos table &optional default
142 This function finds value for position POS in TABLE. If there is
143 no corresponding value, return DEFAULT (defaults to `nil').
145 - Function: put-range-table start end val table
146 This function sets the value for range (START, END) to be VAL in
149 - Function: remove-range-table start end table
150 This function removes the value for range (START, END) in TABLE.
152 - Function: clear-range-table table
153 This function flushes TABLE.
155 - Function: map-range-table function table
156 This function maps FUNCTION over entries in TABLE, calling it with
157 three args, the beginning and end of the range and the
161 File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
166 - Function: databasep object
167 This function returns non-`nil' if OBJECT is a database.
171 * Connecting to a Database::
172 * Working With a Database::
173 * Other Database Functions::
176 File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
178 Connecting to a Database
179 ========================
181 - Function: open-database file &optional type subtype access mode
182 This function opens database FILE, using database method TYPE and
183 SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
184 can be any combination of `r' `w' and `+', for read, write, and
187 TYPE can have the value `'dbm' or `'berkeley_db' to select the
188 type of database file to use. (Note: XEmacs may not support both
191 For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be
194 For a TYPE of `'berkeley_db', the following subtypes are
195 available: `'hash', `'btree', and `'recno'. See the manpages for
196 the Berkeley DB functions to more information about these types.
198 - Function: close-database obj
199 This function closes database OBJ.
201 - Function: database-live-p obj
202 This function returns `t' iff OBJ is an active database, else
206 File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
208 Working With a Database
209 =======================
211 - Function: get-database key dbase &optional default
212 This function finds the value for KEY in DATABASE. If there is no
213 corresponding value, DEFAULT is returned (`nil' if DEFAULT is
216 - Function: map-database function dbase
217 This function maps FUNCTION over entries in DATABASE, calling it
218 with two args, each key and value in the database.
220 - Function: put-database key val dbase &optional replace
221 This function stores KEY and VAL in DATABASE. If optional fourth
222 arg REPLACE is non-`nil', replace any existing entry in the
225 - Function: remove-database key dbase
226 This function removes KEY from DATABASE.
229 File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
231 Other Database Functions
232 ========================
234 - Function: database-file-name obj
235 This function returns the filename associated with the database
238 - Function: database-last-error &optional obj
239 This function returns the last error associated with database OBJ.
241 - Function: database-subtype obj
242 This function returns the subtype of database OBJ, if any.
244 - Function: database-type obj
245 This function returns the type of database OBJ.
248 File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
253 In the terminology of operating systems, a "process" is a space in
254 which a program can execute. XEmacs runs in a process. XEmacs Lisp
255 programs can invoke other programs in processes of their own. These are
256 called "subprocesses" or "child processes" of the XEmacs process, which
257 is their "parent process".
259 A subprocess of XEmacs may be "synchronous" or "asynchronous",
260 depending on how it is created. When you create a synchronous
261 subprocess, the Lisp program waits for the subprocess to terminate
262 before continuing execution. When you create an asynchronous
263 subprocess, it can run in parallel with the Lisp program. This kind of
264 subprocess is represented within XEmacs by a Lisp object which is also
265 called a "process". Lisp programs can use this object to communicate
266 with the subprocess or to control it. For example, you can send
267 signals, obtain status information, receive output from the process, or
270 - Function: processp object
271 This function returns `t' if OBJECT is a process, `nil' otherwise.
275 * Subprocess Creation:: Functions that start subprocesses.
276 * Synchronous Processes:: Details of using synchronous subprocesses.
277 * MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
278 for data sent to and from a subprocess.
279 * Asynchronous Processes:: Starting up an asynchronous subprocess.
280 * Deleting Processes:: Eliminating an asynchronous subprocess.
281 * Process Information:: Accessing run-status and other attributes.
282 * Input to Processes:: Sending input to an asynchronous subprocess.
283 * Signals to Processes:: Stopping, continuing or interrupting
284 an asynchronous subprocess.
285 * Output from Processes:: Collecting output from an asynchronous subprocess.
286 * Sentinels:: Sentinels run when process run-status changes.
287 * Process Window Size:: Changing the logical window size of a process.
288 * Transaction Queues:: Transaction-based communication with subprocesses.
289 * Network:: Opening network connections.
292 File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
294 Functions that Create Subprocesses
295 ==================================
297 There are three functions that create a new subprocess in which to
298 run a program. One of them, `start-process', creates an asynchronous
299 process and returns a process object (*note Asynchronous Processes::).
300 The other two, `call-process' and `call-process-region', create a
301 synchronous process and do not return a process object (*note
302 Synchronous Processes::).
304 Synchronous and asynchronous processes are explained in following
305 sections. Since the three functions are all called in a similar
306 fashion, their common arguments are described here.
308 In all cases, the function's PROGRAM argument specifies the program
309 to be run. An error is signaled if the file is not found or cannot be
310 executed. If the file name is relative, the variable `exec-path'
311 contains a list of directories to search. Emacs initializes
312 `exec-path' when it starts up, based on the value of the environment
313 variable `PATH'. The standard file name constructs, `~', `.', and
314 `..', are interpreted as usual in `exec-path', but environment variable
315 substitutions (`$HOME', etc.) are not recognized; use
316 `substitute-in-file-name' to perform them (*note File Name Expansion::).
318 Each of the subprocess-creating functions has a BUFFER-OR-NAME
319 argument which specifies where the standard output from the program will
320 go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
321 a filter function handles it. (*Note Filter Functions::, and *Note
322 Read and Print::.) Normally, you should avoid having multiple
323 processes send output to the same buffer because their output would be
326 All three of the subprocess-creating functions have a `&rest'
327 argument, ARGS. The ARGS must all be strings, and they are supplied to
328 PROGRAM as separate command line arguments. Wildcard characters and
329 other shell constructs are not allowed in these strings, since they are
330 passed directly to the specified program.
332 *Please note:* The argument PROGRAM contains only the name of the
333 program; it may not contain any command-line arguments. You must use
334 ARGS to provide those.
336 The subprocess gets its current directory from the value of
337 `default-directory' (*note File Name Expansion::).
339 The subprocess inherits its environment from XEmacs; but you can
340 specify overrides for it with `process-environment'. *Note System
343 - Variable: exec-directory
344 The value of this variable is the name of a directory (a string)
345 that contains programs that come with XEmacs, that are intended
346 for XEmacs to invoke. The program `wakeup' is an example of such
347 a program; the `display-time' command uses it to get a reminder
350 - User Option: exec-path
351 The value of this variable is a list of directories to search for
352 programs to run in subprocesses. Each element is either the name
353 of a directory (i.e., a string), or `nil', which stands for the
354 default directory (which is the value of `default-directory').
356 The value of `exec-path' is used by `call-process' and
357 `start-process' when the PROGRAM argument is not an absolute file
361 File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
363 Creating a Synchronous Process
364 ==============================
366 After a "synchronous process" is created, XEmacs waits for the
367 process to terminate before continuing. Starting Dired is an example of
368 this: it runs `ls' in a synchronous process, then modifies the output
369 slightly. Because the process is synchronous, the entire directory
370 listing arrives in the buffer before XEmacs tries to do anything with
373 While Emacs waits for the synchronous subprocess to terminate, the
374 user can quit by typing `C-g'. The first `C-g' tries to kill the
375 subprocess with a `SIGINT' signal; but it waits until the subprocess
376 actually terminates before quitting. If during that time the user
377 types another `C-g', that kills the subprocess instantly with `SIGKILL'
378 and quits immediately. *Note Quitting::.
380 The synchronous subprocess functions returned `nil' in version 18.
381 In version 19, they return an indication of how the process terminated.
383 - Function: call-process program &optional infile destination display
385 This function calls PROGRAM in a separate process and waits for it
388 The standard input for the process comes from file INFILE if
389 INFILE is not `nil' and from `/dev/null' otherwise. The argument
390 DESTINATION says where to put the process output. Here are the
394 Insert the output in that buffer, before point. This
395 includes both the standard output stream and the standard
396 error stream of the process.
399 Find or create a buffer with that name, then insert the
400 output in that buffer, before point.
403 Insert the output in the current buffer, before point.
409 Discard the output, and return immediately without waiting
410 for the subprocess to finish.
412 In this case, the process is not truly synchronous, since it
413 can run in parallel with Emacs; but you can think of it as
414 synchronous in that Emacs is essentially finished with the
415 subprocess as soon as this function returns.
417 (REAL-DESTINATION ERROR-DESTINATION)
418 Keep the standard output stream separate from the standard
419 error stream; deal with the ordinary output as specified by
420 REAL-DESTINATION, and dispose of the error output according
421 to ERROR-DESTINATION. The value `nil' means discard it, `t'
422 means mix it with the ordinary output, and a string specifies
423 a file name to redirect error output into.
425 You can't directly specify a buffer to put the error output
426 in; that is too difficult to implement. But you can achieve
427 this result by sending the error output to a temporary file
428 and then inserting the file into a buffer.
430 If DISPLAY is non-`nil', then `call-process' redisplays the buffer
431 as output is inserted. Otherwise the function does no redisplay,
432 and the results become visible on the screen only when XEmacs
433 redisplays that buffer in the normal course of events.
435 The remaining arguments, ARGS, are strings that specify command
436 line arguments for the program.
438 The value returned by `call-process' (unless you told it not to
439 wait) indicates the reason for process termination. A number
440 gives the exit status of the subprocess; 0 means success, and any
441 other value means failure. If the process terminated with a
442 signal, `call-process' returns a string describing the signal.
444 In the examples below, the buffer `foo' is current.
446 (call-process "pwd" nil t)
449 ---------- Buffer: foo ----------
450 /usr/user/lewis/manual
451 ---------- Buffer: foo ----------
453 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
456 ---------- Buffer: bar ----------
457 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
459 ---------- Buffer: bar ----------
461 The `insert-directory' function contains a good example of the use
464 (call-process insert-directory-program nil t nil switches
466 (concat (file-name-as-directory file) ".")
469 - Function: call-process-region start end program &optional delete
470 destination display &rest args
471 This function sends the text between START to END as standard
472 input to a process running PROGRAM. It deletes the text sent if
473 DELETE is non-`nil'; this is useful when BUFFER is `t', to insert
474 the output in the current buffer.
476 The arguments DESTINATION and DISPLAY control what to do with the
477 output from the subprocess, and whether to update the display as
478 it comes in. For details, see the description of `call-process',
479 above. If DESTINATION is the integer 0, `call-process-region'
480 discards the output and returns `nil' immediately, without waiting
481 for the subprocess to finish.
483 The remaining arguments, ARGS, are strings that specify command
484 line arguments for the program.
486 The return value of `call-process-region' is just like that of
487 `call-process': `nil' if you told it to return without waiting;
488 otherwise, a number or string which indicates how the subprocess
491 In the following example, we use `call-process-region' to run the
492 `cat' utility, with standard input being the first five characters
493 in buffer `foo' (the word `input'). `cat' copies its standard
494 input into its standard output. Since the argument DESTINATION is
495 `t', this output is inserted in the current buffer.
497 ---------- Buffer: foo ----------
499 ---------- Buffer: foo ----------
501 (call-process-region 1 6 "cat" nil t)
504 ---------- Buffer: foo ----------
506 ---------- Buffer: foo ----------
508 The `shell-command-on-region' command uses `call-process-region'
513 shell-file-name ; Name of program.
514 nil ; Do not delete region.
515 buffer ; Send output to `buffer'.
516 nil ; No redisplay during output.
517 "-c" command) ; Arguments for the shell.
520 File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
525 On MS-DOS, you must indicate whether the data going to and from a
526 synchronous subprocess are text or binary. Text data requires
527 translation between the end-of-line convention used within Emacs (a
528 single newline character) and the convention used outside Emacs (the
529 two-character sequence, CRLF).
531 The variable `binary-process-input' applies to input sent to the
532 subprocess, and `binary-process-output' applies to output received from
533 it. A non-`nil' value means the data is non-text; `nil' means the data
534 is text, and calls for conversion.
536 - Variable: binary-process-input
537 If this variable is `nil', convert newlines to CRLF sequences in
538 the input to a synchronous subprocess.
540 - Variable: binary-process-output
541 If this variable is `nil', convert CRLF sequences to newlines in
542 the output from a synchronous subprocess.
544 *Note Files and MS-DOS::, for related information.
547 File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
549 Creating an Asynchronous Process
550 ================================
552 After an "asynchronous process" is created, Emacs and the Lisp
553 program both continue running immediately. The process may thereafter
554 run in parallel with Emacs, and the two may communicate with each other
555 using the functions described in following sections. Here we describe
556 how to create an asynchronous process with `start-process'.
558 - Function: start-process name buffer-or-name program &rest args
559 This function creates a new asynchronous subprocess and starts the
560 program PROGRAM running in it. It returns a process object that
561 stands for the new subprocess in Lisp. The argument NAME
562 specifies the name for the process object; if a process with this
563 name already exists, then NAME is modified (by adding `<1>', etc.)
564 to be unique. The buffer BUFFER-OR-NAME is the buffer to
565 associate with the process.
567 The remaining arguments, ARGS, are strings that specify command
568 line arguments for the program.
570 In the example below, the first process is started and runs
571 (rather, sleeps) for 100 seconds. Meanwhile, the second process
572 is started, and given the name `my-process<1>' for the sake of
573 uniqueness. It inserts the directory listing at the end of the
574 buffer `foo', before the first process finishes. Then it
575 finishes, and a message to that effect is inserted in the buffer.
576 Much later, the first process finishes, and another message is
577 inserted in the buffer for it.
579 (start-process "my-process" "foo" "sleep" "100")
580 => #<process my-process>
582 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
583 => #<process my-process<1>>
585 ---------- Buffer: foo ----------
587 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
588 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
590 Process my-process<1> finished
592 Process my-process finished
593 ---------- Buffer: foo ----------
595 - Function: start-process-shell-command name buffer-or-name command
597 This function is like `start-process' except that it uses a shell
598 to execute the specified command. The argument COMMAND is a shell
599 command name, and COMMAND-ARGS are the arguments for the shell
602 - Variable: process-connection-type
603 This variable controls the type of device used to communicate with
604 asynchronous subprocesses. If it is non-`nil', then PTYs are
605 used, when available. Otherwise, pipes are used.
607 PTYs are usually preferable for processes visible to the user, as
608 in Shell mode, because they allow job control (`C-c', `C-z', etc.)
609 to work between the process and its children whereas pipes do not.
610 For subprocesses used for internal purposes by programs, it is
611 often better to use a pipe, because they are more efficient. In
612 addition, the total number of PTYs is limited on many systems and
613 it is good not to waste them.
615 The value `process-connection-type' is used when `start-process'
616 is called. So you can specify how to communicate with one
617 subprocess by binding the variable around the call to
620 (let ((process-connection-type nil)) ; Use a pipe.
623 To determine whether a given subprocess actually got a pipe or a
624 PTY, use the function `process-tty-name' (*note Process
628 File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
633 "Deleting a process" disconnects XEmacs immediately from the
634 subprocess, and removes it from the list of active processes. It sends
635 a signal to the subprocess to make the subprocess terminate, but this is
636 not guaranteed to happen immediately. The process object itself
637 continues to exist as long as other Lisp objects point to it.
639 You can delete a process explicitly at any time. Processes are
640 deleted automatically after they terminate, but not necessarily right
641 away. If you delete a terminated process explicitly before it is
642 deleted automatically, no harm results.
644 - Variable: delete-exited-processes
645 This variable controls automatic deletion of processes that have
646 terminated (due to calling `exit' or to a signal). If it is
647 `nil', then they continue to exist until the user runs
648 `list-processes'. Otherwise, they are deleted immediately after
651 - Function: delete-process name
652 This function deletes the process associated with NAME, killing it
653 with a `SIGHUP' signal. The argument NAME may be a process, the
654 name of a process, a buffer, or the name of a buffer.
656 (delete-process "*shell*")
659 - Function: process-kill-without-query process &optional
661 This function declares that XEmacs need not query the user if
662 PROCESS is still running when XEmacs is exited. The process will
663 be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
664 _will_ query the user (this is the default). The return value is
665 `t' if a query was formerly required, and `nil' otherwise.
667 (process-kill-without-query (get-process "shell"))
671 File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
676 Several functions return information about processes.
677 `list-processes' is provided for interactive use.
679 - Command: list-processes
680 This command displays a listing of all living processes. In
681 addition, it finally deletes any process whose status was `Exited'
682 or `Signaled'. It returns `nil'.
684 - Function: process-list
685 This function returns a list of all processes that have not been
689 => (#<process display-time> #<process shell>)
691 - Function: get-process name
692 This function returns the process named NAME, or `nil' if there is
693 none. An error is signaled if NAME is not a string.
695 (get-process "shell")
698 - Function: process-command process
699 This function returns the command that was executed to start
700 PROCESS. This is a list of strings, the first string being the
701 program executed and the rest of the strings being the arguments
702 that were given to the program.
704 (process-command (get-process "shell"))
707 - Function: process-id process
708 This function returns the PID of PROCESS. This is an integer that
709 distinguishes the process PROCESS from all other processes running
710 on the same computer at the current time. The PID of a process is
711 chosen by the operating system kernel when the process is started
712 and remains constant as long as the process exists.
714 - Function: process-name process
715 This function returns the name of PROCESS.
717 - Function: process-status process-name
718 This function returns the status of PROCESS-NAME as a symbol. The
719 argument PROCESS-NAME must be a process, a buffer, a process name
720 (string) or a buffer name (string).
722 The possible values for an actual subprocess are:
725 for a process that is running.
728 for a process that is stopped but continuable.
731 for a process that has exited.
734 for a process that has received a fatal signal.
737 for a network connection that is open.
740 for a network connection that is closed. Once a connection
741 is closed, you cannot reopen it, though you might be able to
742 open a new connection to the same place.
745 if PROCESS-NAME is not the name of an existing process.
747 (process-status "shell")
749 (process-status (get-buffer "*shell*"))
756 For a network connection, `process-status' returns one of the
757 symbols `open' or `closed'. The latter means that the other side
758 closed the connection, or XEmacs did `delete-process'.
760 In earlier Emacs versions (prior to version 19), the status of a
761 network connection was `run' if open, and `exit' if closed.
763 - Function: process-kill-without-query-p process
764 This function returns whether PROCESS will be killed without
765 querying the user, if it is running when XEmacs is exited. The
766 default value is `nil'.
768 - Function: process-exit-status process
769 This function returns the exit status of PROCESS or the signal
770 number that killed it. (Use the result of `process-status' to
771 determine which of those it is.) If PROCESS has not yet
772 terminated, the value is 0.
774 - Function: process-tty-name process
775 This function returns the terminal name that PROCESS is using for
776 its communication with Emacs--or `nil' if it is using pipes
777 instead of a terminal (see `process-connection-type' in *Note
778 Asynchronous Processes::).
781 File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
783 Sending Input to Processes
784 ==========================
786 Asynchronous subprocesses receive input when it is sent to them by
787 XEmacs, which is done with the functions in this section. You must
788 specify the process to send input to, and the input data to send. The
789 data appears on the "standard input" of the subprocess.
791 Some operating systems have limited space for buffered input in a
792 PTY. On these systems, Emacs sends an EOF periodically amidst the
793 other characters, to force them through. For most programs, these EOFs
796 - Function: process-send-string process-name string
797 This function sends PROCESS-NAME the contents of STRING as
798 standard input. The argument PROCESS-NAME must be a process or
799 the name of a process. If it is `nil', the current buffer's
802 The function returns `nil'.
804 (process-send-string "shell<1>" "ls\n")
808 ---------- Buffer: *shell* ----------
810 introduction.texi syntax-tables.texi~
811 introduction.texi~ text.texi
812 introduction.txt text.texi~
814 ---------- Buffer: *shell* ----------
816 - Command: process-send-region process-name start end
817 This function sends the text in the region defined by START and
818 END as standard input to PROCESS-NAME, which is a process or a
819 process name. (If it is `nil', the current buffer's process is
822 An error is signaled unless both START and END are integers or
823 markers that indicate positions in the current buffer. (It is
824 unimportant which number is larger.)
826 - Function: process-send-eof &optional process-name
827 This function makes PROCESS-NAME see an end-of-file in its input.
828 The EOF comes after any text already sent to it.
830 If PROCESS-NAME is not supplied, or if it is `nil', then this
831 function sends the EOF to the current buffer's process. An error
832 is signaled if the current buffer has no process.
834 The function returns PROCESS-NAME.
836 (process-send-eof "shell")
840 File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
842 Sending Signals to Processes
843 ============================
845 "Sending a signal" to a subprocess is a way of interrupting its
846 activities. There are several different signals, each with its own
847 meaning. The set of signals and their names is defined by the operating
848 system. For example, the signal `SIGINT' means that the user has typed
849 `C-c', or that some analogous thing has happened.
851 Each signal has a standard effect on the subprocess. Most signals
852 kill the subprocess, but some stop or resume execution instead. Most
853 signals can optionally be handled by programs; if the program handles
854 the signal, then we can say nothing in general about its effects.
856 The set of signals and their names is defined by the operating
857 system; XEmacs has facilities for sending only a few of the signals
858 that are defined. XEmacs can send signals only to its own subprocesses.
860 You can send signals explicitly by calling the functions in this
861 section. XEmacs also sends signals automatically at certain times:
862 killing a buffer sends a `SIGHUP' signal to all its associated
863 processes; killing XEmacs sends a `SIGHUP' signal to all remaining
864 processes. (`SIGHUP' is a signal that usually indicates that the user
867 Each of the signal-sending functions takes two optional arguments:
868 PROCESS-NAME and CURRENT-GROUP.
870 The argument PROCESS-NAME must be either a process, the name of one,
871 or `nil'. If it is `nil', the process defaults to the process
872 associated with the current buffer. An error is signaled if
873 PROCESS-NAME does not identify a process.
875 The argument CURRENT-GROUP is a flag that makes a difference when
876 you are running a job-control shell as an XEmacs subprocess. If it is
877 non-`nil', then the signal is sent to the current process-group of the
878 terminal that XEmacs uses to communicate with the subprocess. If the
879 process is a job-control shell, this means the shell's current subjob.
880 If it is `nil', the signal is sent to the process group of the
881 immediate subprocess of XEmacs. If the subprocess is a job-control
882 shell, this is the shell itself.
884 The flag CURRENT-GROUP has no effect when a pipe is used to
885 communicate with the subprocess, because the operating system does not
886 support the distinction in the case of pipes. For the same reason,
887 job-control shells won't work when a pipe is used. See
888 `process-connection-type' in *Note Asynchronous Processes::.
890 - Function: interrupt-process &optional process-name current-group
891 This function interrupts the process PROCESS-NAME by sending the
892 signal `SIGINT'. Outside of XEmacs, typing the "interrupt
893 character" (normally `C-c' on some systems, and `DEL' on others)
894 sends this signal. When the argument CURRENT-GROUP is non-`nil',
895 you can think of this function as "typing `C-c'" on the terminal
896 by which XEmacs talks to the subprocess.
898 - Function: kill-process &optional process-name current-group
899 This function kills the process PROCESS-NAME by sending the signal
900 `SIGKILL'. This signal kills the subprocess immediately, and
901 cannot be handled by the subprocess.
903 - Function: quit-process &optional process-name current-group
904 This function sends the signal `SIGQUIT' to the process
905 PROCESS-NAME. This signal is the one sent by the "quit character"
906 (usually `C-b' or `C-\') when you are not inside XEmacs.
908 - Function: stop-process &optional process-name current-group
909 This function stops the process PROCESS-NAME by sending the signal
910 `SIGTSTP'. Use `continue-process' to resume its execution.
912 On systems with job control, the "stop character" (usually `C-z')
913 sends this signal (outside of XEmacs). When CURRENT-GROUP is
914 non-`nil', you can think of this function as "typing `C-z'" on the
915 terminal XEmacs uses to communicate with the subprocess.
917 - Function: continue-process &optional process-name current-group
918 This function resumes execution of the process PROCESS by sending
919 it the signal `SIGCONT'. This presumes that PROCESS-NAME was
922 - Function: signal-process pid signal
923 This function sends a signal to process PID, which need not be a
924 child of XEmacs. The argument SIGNAL specifies which signal to
925 send; it should be an integer.
928 File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
930 Receiving Output from Processes
931 ===============================
933 There are two ways to receive the output that a subprocess writes to
934 its standard output stream. The output can be inserted in a buffer,
935 which is called the associated buffer of the process, or a function
936 called the "filter function" can be called to act on the output. If
937 the process has no buffer and no filter function, its output is
942 * Process Buffers:: If no filter, output is put in a buffer.
943 * Filter Functions:: Filter functions accept output from the process.
944 * Accepting Output:: Explicitly permitting subprocess output.
945 Waiting for subprocess output.
948 File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
953 A process can (and usually does) have an "associated buffer", which
954 is an ordinary Emacs buffer that is used for two purposes: storing the
955 output from the process, and deciding when to kill the process. You
956 can also use the buffer to identify a process to operate on, since in
957 normal practice only one process is associated with any given buffer.
958 Many applications of processes also use the buffer for editing input to
959 be sent to the process, but this is not built into XEmacs Lisp.
961 Unless the process has a filter function (*note Filter Functions::),
962 its output is inserted in the associated buffer. The position to insert
963 the output is determined by the `process-mark', which is then updated
964 to point to the end of the text just inserted. Usually, but not
965 always, the `process-mark' is at the end of the buffer.
967 - Function: process-buffer process
968 This function returns the associated buffer of the process PROCESS.
970 (process-buffer (get-process "shell"))
973 - Function: process-mark process
974 This function returns the process marker for PROCESS, which is the
975 marker that says where to insert output from the process.
977 If PROCESS does not have a buffer, `process-mark' returns a marker
980 Insertion of process output in a buffer uses this marker to decide
981 where to insert, and updates it to point after the inserted text.
982 That is why successive batches of output are inserted
985 Filter functions normally should use this marker in the same
986 fashion as is done by direct insertion of output in the buffer. A
987 good example of a filter function that uses `process-mark' is
988 found at the end of the following section.
990 When the user is expected to enter input in the process buffer for
991 transmission to the process, the process marker is useful for
992 distinguishing the new input from previous output.
994 - Function: set-process-buffer process buffer
995 This function sets the buffer associated with PROCESS to BUFFER.
996 If BUFFER is `nil', the process becomes associated with no buffer.
998 - Function: get-buffer-process buffer-or-name
999 This function returns the process associated with BUFFER-OR-NAME.
1000 If there are several processes associated with it, then one is
1001 chosen. (Presently, the one chosen is the one most recently
1002 created.) It is usually a bad idea to have more than one process
1003 associated with the same buffer.
1005 (get-buffer-process "*shell*")
1008 Killing the process's buffer deletes the process, which kills the
1009 subprocess with a `SIGHUP' signal (*note Signals to Processes::).
1012 File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
1014 Process Filter Functions
1015 ------------------------
1017 A process "filter function" is a function that receives the standard
1018 output from the associated process. If a process has a filter, then
1019 _all_ output from that process is passed to the filter. The process
1020 buffer is used directly for output from the process only when there is
1023 A filter function must accept two arguments: the associated process
1024 and a string, which is the output. The function is then free to do
1025 whatever it chooses with the output.
1027 A filter function runs only while XEmacs is waiting (e.g., for
1028 terminal input, or for time to elapse, or for process output). This
1029 avoids the timing errors that could result from running filters at
1030 random places in the middle of other Lisp programs. You may explicitly
1031 cause Emacs to wait, so that filter functions will run, by calling
1032 `sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
1033 (*note Accepting Output::). Emacs is also waiting when the command loop
1036 Quitting is normally inhibited within a filter function--otherwise,
1037 the effect of typing `C-g' at command level or to quit a user command
1038 would be unpredictable. If you want to permit quitting inside a filter
1039 function, bind `inhibit-quit' to `nil'. *Note Quitting::.
1041 If an error happens during execution of a filter function, it is
1042 caught automatically, so that it doesn't stop the execution of whatever
1043 program was running when the filter function was started. However, if
1044 `debug-on-error' is non-`nil', the error-catching is turned off. This
1045 makes it possible to use the Lisp debugger to debug the filter
1046 function. *Note Debugger::.
1048 Many filter functions sometimes or always insert the text in the
1049 process's buffer, mimicking the actions of XEmacs when there is no
1050 filter. Such filter functions need to use `set-buffer' in order to be
1051 sure to insert in that buffer. To avoid setting the current buffer
1052 semipermanently, these filter functions must use `unwind-protect' to
1053 make sure to restore the previous current buffer. They should also
1054 update the process marker, and in some cases update the value of point.
1055 Here is how to do these things:
1057 (defun ordinary-insertion-filter (proc string)
1058 (let ((old-buffer (current-buffer)))
1061 (set-buffer (process-buffer proc))
1062 (setq moving (= (point) (process-mark proc)))
1064 ;; Insert the text, moving the process-marker.
1065 (goto-char (process-mark proc))
1067 (set-marker (process-mark proc) (point)))
1068 (if moving (goto-char (process-mark proc))))
1069 (set-buffer old-buffer))))
1071 The reason to use an explicit `unwind-protect' rather than letting
1072 `save-excursion' restore the current buffer is so as to preserve the
1073 change in point made by `goto-char'.
1075 To make the filter force the process buffer to be visible whenever
1076 new text arrives, insert the following line just before the
1079 (display-buffer (process-buffer proc))
1081 To force point to move to the end of the new output no matter where
1082 it was previously, eliminate the variable `moving' and call `goto-char'
1085 In earlier Emacs versions, every filter function that did regexp
1086 searching or matching had to explicitly save and restore the match data.
1087 Now Emacs does this automatically; filter functions never need to do it
1088 explicitly. *Note Match Data::.
1090 A filter function that writes the output into the buffer of the
1091 process should check whether the buffer is still alive. If it tries to
1092 insert into a dead buffer, it will get an error. If the buffer is dead,
1093 `(buffer-name (process-buffer PROCESS))' returns `nil'.
1095 The output to the function may come in chunks of any size. A program
1096 that produces the same output twice in a row may send it as one batch
1097 of 200 characters one time, and five batches of 40 characters the next.
1099 - Function: set-process-filter process filter
1100 This function gives PROCESS the filter function FILTER. If FILTER
1101 is `nil', then the process will have no filter. If FILTER is `t',
1102 then no output from the process will be accepted until the filter
1103 is changed. (Output received during this time is not discarded,
1104 but is queued, and will be processed as soon as the filter is
1107 - Function: process-filter process
1108 This function returns the filter function of PROCESS, or `nil' if
1109 it has none. `t' means that output processing has been stopped.
1111 Here is an example of use of a filter function:
1113 (defun keep-output (process output)
1114 (setq kept (cons output kept)))
1118 (set-process-filter (get-process "shell") 'keep-output)
1120 (process-send-string "shell" "ls ~/other\n")
1123 => ("lewis@slug[8] % "
1124 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
1125 address.txt backup.psf kolstad.psf
1126 backup.bib~ david.mss resume-Dec-86.mss~
1127 backup.err david.psf resume-Dec.psf
1128 backup.mss dland syllabus.mss
1130 "#backups.mss# backup.mss~ kolstad.mss
1134 File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
1136 Accepting Output from Processes
1137 -------------------------------
1139 Output from asynchronous subprocesses normally arrives only while
1140 XEmacs is waiting for some sort of external event, such as elapsed time
1141 or terminal input. Occasionally it is useful in a Lisp program to
1142 explicitly permit output to arrive at a specific point, or even to wait
1143 until output arrives from a process.
1145 - Function: accept-process-output &optional process seconds millisec
1146 This function allows XEmacs to read pending output from processes.
1147 The output is inserted in the associated buffers or given to
1148 their filter functions. If PROCESS is non-`nil' then this
1149 function does not return until some output has been received from
1152 The arguments SECONDS and MILLISEC let you specify timeout
1153 periods. The former specifies a period measured in seconds and the
1154 latter specifies one measured in milliseconds. The two time
1155 periods thus specified are added together, and
1156 `accept-process-output' returns after that much time whether or
1157 not there has been any subprocess output. Note that SECONDS is
1158 allowed to be a floating-point number; thus, there is no need to
1159 ever use MILLISEC. (It is retained for compatibility purposes.)
1161 The function `accept-process-output' returns non-`nil' if it did
1162 get some output, or `nil' if the timeout expired before output