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: Beeping, Prev: Display Tables, Up: Display
58 You can make XEmacs ring a bell, play a sound, or blink the screen to
59 attract the user's attention. Be conservative about how often you do
60 this; frequent bells can become irritating. Also be careful not to use
61 beeping alone when signaling an error is appropriate. (*Note Errors::.)
63 - Function: ding &optional dont-terminate sound device
64 This function beeps, or flashes the screen (see `visible-bell'
65 below). It also terminates any keyboard macro currently executing
66 unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
67 should be a symbol specifying which sound to make. This sound
68 will be played if `visible-bell' is `nil'. (This only works if
69 sound support was compiled into the executable and you are running
70 on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
71 PC. Otherwise you just get a beep.) The optional third argument
72 specifies what device to make the sound on, and defaults to the
75 - Function: beep &optional dont-terminate sound device
76 This is a synonym for `ding'.
78 - User Option: visible-bell
79 This variable determines whether XEmacs should flash the screen to
80 represent a bell. Non-`nil' means yes, `nil' means no. On TTY
81 devices, this is effective only if the Termcap entry for the
82 terminal type has the visible bell flag (`vb') set.
84 - Variable: sound-alist
85 This variable holds an alist associating names with sounds. When
86 `beep' or `ding' is called with one of the name symbols, the
87 associated sound will be generated instead of the standard beep.
89 Each element of `sound-alist' is a list describing a sound. The
90 first element of the list is the name of the sound being defined.
91 Subsequent elements of the list are alternating keyword/value
95 A string of raw sound data, or the name of another sound to
96 play. The symbol `t' here means use the default X beep.
99 An integer from 0-100, defaulting to `bell-volume'.
102 If using the default X beep, the pitch (Hz) to generate.
105 If using the default X beep, the duration (milliseconds).
107 For compatibility, elements of `sound-alist' may also be:
109 * `( sound-name . <sound> )'
111 * `( sound-name <volume> <sound> )'
113 You should probably add things to this list by calling the function
118 - You can only play audio data if running on the console screen
119 of a Sun SparcStation, SGI, or HP9000s700.
121 - The pitch, duration, and volume options are available
122 everywhere, but many X servers ignore the `pitch' option.
124 The following beep-types are used by XEmacs itself:
127 when an auto-save does not succeed
130 when the XEmacs command loop catches an error
133 when you type a key that is undefined
136 when you use an undefined mouse-click combination
139 during completing-read
142 when you type something other than 'y' or 'n'
145 when you type something other than 'yes' or 'no'
148 used when nothing else is appropriate.
150 Other lisp packages may use other beep types, but these are the
151 ones that the C kernel of XEmacs uses.
153 - User Option: bell-volume
154 This variable specifies the default volume for sounds, from 0 to
157 - Command: load-default-sounds
158 This function loads and installs some sound files as beep-types.
160 - Command: load-sound-file filename sound-name &optional volume
161 This function reads in an audio file and adds it to `sound-alist'.
162 The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
163 should be a symbol, specifying the name of the sound. If VOLUME
164 is specified, the sound will be played at that volume; otherwise,
165 the value of BELL-VOLUME will be used.
167 - Function: play-sound sound &optional volume device
168 This function plays sound SOUND, which should be a symbol
169 mentioned in `sound-alist'. If VOLUME is specified, it overrides
170 the value (if any) specified in `sound-alist'. DEVICE specifies
171 the device to play the sound on, and defaults to the selected
174 - Command: play-sound-file file &optional volume device
175 This function plays the named sound file at volume VOLUME, which
176 defaults to `bell-volume'. DEVICE specifies the device to play
177 the sound on, and defaults to the selected device.
180 File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
185 - Function: hash-table-p object
186 This function returns `t' if OBJECT is a hash table, else `nil'.
190 * Introduction to Hash Tables:: Hash tables are fast data structures for
191 implementing simple tables (i.e. finite
192 mappings from keys to values).
193 * Working With Hash Tables:: Hash table functions.
194 * Weak Hash Tables:: Hash tables with special garbage-collection
198 File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
200 Introduction to Hash Tables
201 ===========================
203 A "hash table" is a data structure that provides mappings from
204 arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
205 called "values". A key/value pair is sometimes called an "entry" in
206 the hash table. There are many ways other than hash tables of
207 implementing the same sort of mapping, e.g. association lists (*note
208 Association Lists::) and property lists (*note Property Lists::), but
209 hash tables provide much faster lookup when there are many entries in
210 the mapping. Hash tables are an implementation of the abstract data
211 type "dictionary", also known as "associative array".
213 Internally, hash tables are hashed using the "linear probing" hash
214 table implementation method. This method hashes each key to a
215 particular spot in the hash table, and then scans forward sequentially
216 until a blank entry is found. To look up a key, hash to the appropriate
217 spot, then search forward for the key until either a key is found or a
218 blank entry stops the search. This method is used in preference to
219 double hashing because of changes in recent hardware. The penalty for
220 non-sequential access to memory has been increasing, and this
221 compensates for the problem of clustering that linear probing entails.
223 When hash tables are created, the user may (but is not required to)
224 specify initial properties that influence performance.
226 Use the `:size' parameter to specify the number of entries that are
227 likely to be stored in the hash table, to avoid the overhead of resizing
228 the table. But if the pre-allocated space for the entries is never
229 used, it is simply wasted and makes XEmacs slower. Excess unused hash
230 table entries exact a small continuous performance penalty, since they
231 must be scanned at every garbage collection. If the number of entries
232 in the hash table is unknown, simply avoid using the `:size' keyword.
234 Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
235 the algorithm for deciding when to rehash the hash table. For
236 temporary hash tables that are going to be very heavily used, use a
237 small rehash threshold, for example, 0.4 and a large rehash size, for
238 example 2.0. For permanent hash tables that will be infrequently used,
239 specify a large rehash threshold, for example 0.8.
241 Hash tables can also be created by the lisp reader using structure
243 #s(hash-table size 20 data (foo 1 bar 2))
245 The structure syntax accepts the same keywords as `make-hash-table'
246 (without the `:' character), as well as the additional keyword `data',
247 which specifies the initial hash table contents.
249 - Function: make-hash-table &key `test' `size' `rehash-size'
250 `rehash-threshold' `weakness'
251 This function returns a new empty hash table object.
253 Keyword `:test' can be `eq', `eql' (default) or `equal'.
254 Comparison between keys is done using this function. If speed is
255 important, consider using `eq'. When storing strings in the hash
256 table, you will likely need to use `equal'.
258 Keyword `:size' specifies the number of keys likely to be inserted.
259 This number of entries can be inserted without enlarging the hash
262 Keyword `:rehash-size' must be a float greater than 1.0, and
263 specifies the factor by which to increase the size of the hash
264 table when enlarging.
266 Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
267 and specifies the load factor of the hash table which triggers
270 Keyword `:weakness' can be `nil' (default), `t', `key' or `value'.
272 A weak hash table is one whose pointers do not count as GC
273 referents: for any key-value pair in the hash table, if the only
274 remaining pointer to either the key or the value is in a weak hash
275 table, then the pair will be removed from the hash table, and the
276 key and value collected. A non-weak hash table (or any other
277 pointer) would prevent the object from being collected.
279 A key-weak hash table is similar to a fully-weak hash table except
280 that a key-value pair will be removed only if the key remains
281 unmarked outside of weak hash tables. The pair will remain in the
282 hash table if the key is pointed to by something other than a weak
283 hash table, even if the value is not.
285 A value-weak hash table is similar to a fully-weak hash table
286 except that a key-value pair will be removed only if the value
287 remains unmarked outside of weak hash tables. The pair will
288 remain in the hash table if the value is pointed to by something
289 other than a weak hash table, even if the key is not.
291 - Function: copy-hash-table hash-table
292 This function returns a new hash table which contains the same
293 keys and values as HASH-TABLE. The keys and values will not
294 themselves be copied.
296 - Function: hash-table-count hash-table
297 This function returns the number of entries in HASH-TABLE.
299 - Function: hash-table-test hash-table
300 This function returns the test function of HASH-TABLE. This can
301 be one of `eq', `eql' or `equal'.
303 - Function: hash-table-size hash-table
304 This function returns the current number of slots in HASH-TABLE,
305 whether occupied or not.
307 - Function: hash-table-rehash-size hash-table
308 This function returns the current rehash size of HASH-TABLE. This
309 is a float greater than 1.0; the factor by which HASH-TABLE is
310 enlarged when the rehash threshold is exceeded.
312 - Function: hash-table-rehash-threshold hash-table
313 This function returns the current rehash threshold of HASH-TABLE.
314 This is a float between 0.0 and 1.0; the maximum "load factor" of
315 HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
317 - Function: hash-table-weakness hash-table
318 This function returns the weakness of HASH-TABLE. This can be one
319 of `nil', `t', `key' or `value'.
322 File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
324 Working With Hash Tables
325 ========================
327 - Function: puthash key value hash-table
328 This function hashes KEY to VALUE in HASH-TABLE.
330 - Function: gethash key hash-table &optional default
331 This function finds the hash value for KEY in HASH-TABLE. If
332 there is no entry for KEY in HASH-TABLE, DEFAULT is returned
333 (which in turn defaults to `nil').
335 - Function: remhash key hash-table
336 This function removes the entry for KEY from HASH-TABLE. Does
337 nothing if there is no entry for KEY in HASH-TABLE.
339 - Function: clrhash hash-table
340 This function removes all entries from HASH-TABLE, leaving it
343 - Function: maphash function hash-table
344 This function maps FUNCTION over entries in HASH-TABLE, calling it
345 with two args, each key and value in the hash table.
347 FUNCTION may not modify HASH-TABLE, with the one exception that
348 FUNCTION may remhash or puthash the entry currently being
349 processed by FUNCTION.
352 File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
357 A "weak hash table" is a special variety of hash table whose
358 elements do not count as GC referents. For any key-value pair in such a
359 hash table, if either the key or value (or in some cases, if one
360 particular one of the two) has no references to it outside of weak hash
361 tables (and similar structures such as weak lists), the pair will be
362 removed from the table, and the key and value collected. A non-weak
363 hash table (or any other pointer) would prevent the objects from being
366 Weak hash tables are useful for keeping track of information in a
367 non-obtrusive way, for example to implement caching. If the cache
368 contains objects such as buffers, markers, image instances, etc. that
369 will eventually disappear and get garbage-collected, using a weak hash
370 table ensures that these objects are collected normally rather than
371 remaining around forever, long past their actual period of use.
372 (Otherwise, you'd have to explicitly map over the hash table every so
373 often and remove unnecessary elements.)
375 There are three types of weak hash tables:
377 fully weak hash tables
378 In these hash tables, a pair disappears if either the key or the
379 value is unreferenced outside of the table.
382 In these hash tables, a pair disappears if the key is unreferenced
383 outside of the table, regardless of how the value is referenced.
385 value-weak hash tables
386 In these hash tables, a pair disappears if the value is
387 unreferenced outside of the table, regardless of how the key is
390 Also see *Note Weak Lists::.
392 Weak hash tables are created by specifying the `:weakness' keyword to
396 File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
401 A range table is a table that efficiently associated values with
404 Note that range tables have a read syntax, like this:
406 #s(range-table data ((-3 2) foo (5 20) bar))
408 This maps integers in the range (-3, 2) to `foo' and integers in the
409 range (5, 20) to `bar'.
411 - Function: range-table-p object
412 Return non-`nil' if OBJECT is a range table.
416 * Introduction to Range Tables:: Range tables efficiently map ranges of
418 * Working With Range Tables:: Range table functions.
421 File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
423 Introduction to Range Tables
424 ============================
426 - Function: make-range-table
427 Make a new, empty range table.
429 - Function: copy-range-table old-table
430 Make a new range table which contains the same values for the same
431 ranges as the given table. The values will not themselves be
435 File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
437 Working With Range Tables
438 =========================
440 - Function: get-range-table pos table &optional default
441 This function finds value for position POS in TABLE. If there is
442 no corresponding value, return DEFAULT (defaults to `nil').
444 - Function: put-range-table start end val table
445 This function sets the value for range (START, END) to be VAL in
448 - Function: remove-range-table start end table
449 This function removes the value for range (START, END) in TABLE.
451 - Function: clear-range-table table
452 This function flushes TABLE.
454 - Function: map-range-table function table
455 This function maps FUNCTION over entries in TABLE, calling it with
456 three args, the beginning and end of the range and the
460 File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
465 - Function: databasep object
466 This function returns non-`nil' if OBJECT is a database.
470 * Connecting to a Database::
471 * Working With a Database::
472 * Other Database Functions::
475 File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
477 Connecting to a Database
478 ========================
480 - Function: open-database file &optional type subtype access mode
481 This function opens database FILE, using database method TYPE and
482 SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
483 can be any combination of `r' `w' and `+', for read, write, and
486 TYPE can have the value `'dbm' or `'berkeley_db' to select the
487 type of database file to use. (Note: XEmacs may not support both
490 For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should by
493 For a TYPE of `'berkeley_db', the following subtypes are
494 available: `'hash', `'btree', and `'recno'. See the manpages for
495 the Berkeley DB functions to more information about these types.
497 - Function: close-database obj
498 This function closes database OBJ.
500 - Function: database-live-p obj
501 This function returns `t' iff OBJ is an active database, else
505 File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
507 Working With a Database
508 =======================
510 - Function: get-database key dbase &optional default
511 This function finds the value for KEY in DATABASE. If there is no
512 corresponding value, DEFAULT is returned (`nil' if DEFAULT is
515 - Function: map-database function dbase
516 This function maps FUNCTION over entries in DATABASE, calling it
517 with two args, each key and value in the database.
519 - Function: put-database key val dbase &optional replace
520 This function stores KEY and VAL in DATABASE. If optional fourth
521 arg REPLACE is non-`nil', replace any existing entry in the
524 - Function: remove-database key dbase
525 This function removes KEY from DATABASE.
528 File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
530 Other Database Functions
531 ========================
533 - Function: database-file-name obj
534 This function returns the filename associated with the database
537 - Function: database-last-error &optional obj
538 This function returns the last error associated with database OBJ.
540 - Function: database-subtype obj
541 This function returns the subtype of database OBJ, if any.
543 - Function: database-type obj
544 This function returns the type of database OBJ.
547 File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
552 In the terminology of operating systems, a "process" is a space in
553 which a program can execute. XEmacs runs in a process. XEmacs Lisp
554 programs can invoke other programs in processes of their own. These are
555 called "subprocesses" or "child processes" of the XEmacs process, which
556 is their "parent process".
558 A subprocess of XEmacs may be "synchronous" or "asynchronous",
559 depending on how it is created. When you create a synchronous
560 subprocess, the Lisp program waits for the subprocess to terminate
561 before continuing execution. When you create an asynchronous
562 subprocess, it can run in parallel with the Lisp program. This kind of
563 subprocess is represented within XEmacs by a Lisp object which is also
564 called a "process". Lisp programs can use this object to communicate
565 with the subprocess or to control it. For example, you can send
566 signals, obtain status information, receive output from the process, or
569 - Function: processp object
570 This function returns `t' if OBJECT is a process, `nil' otherwise.
574 * Subprocess Creation:: Functions that start subprocesses.
575 * Synchronous Processes:: Details of using synchronous subprocesses.
576 * MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
577 for data sent to and from a subprocess.
578 * Asynchronous Processes:: Starting up an asynchronous subprocess.
579 * Deleting Processes:: Eliminating an asynchronous subprocess.
580 * Process Information:: Accessing run-status and other attributes.
581 * Input to Processes:: Sending input to an asynchronous subprocess.
582 * Signals to Processes:: Stopping, continuing or interrupting
583 an asynchronous subprocess.
584 * Output from Processes:: Collecting output from an asynchronous subprocess.
585 * Sentinels:: Sentinels run when process run-status changes.
586 * Process Window Size:: Changing the logical window size of a process.
587 * Transaction Queues:: Transaction-based communication with subprocesses.
588 * Network:: Opening network connections.
591 File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
593 Functions that Create Subprocesses
594 ==================================
596 There are three functions that create a new subprocess in which to
597 run a program. One of them, `start-process', creates an asynchronous
598 process and returns a process object (*note Asynchronous Processes::).
599 The other two, `call-process' and `call-process-region', create a
600 synchronous process and do not return a process object (*note
601 Synchronous Processes::).
603 Synchronous and asynchronous processes are explained in following
604 sections. Since the three functions are all called in a similar
605 fashion, their common arguments are described here.
607 In all cases, the function's PROGRAM argument specifies the program
608 to be run. An error is signaled if the file is not found or cannot be
609 executed. If the file name is relative, the variable `exec-path'
610 contains a list of directories to search. Emacs initializes
611 `exec-path' when it starts up, based on the value of the environment
612 variable `PATH'. The standard file name constructs, `~', `.', and
613 `..', are interpreted as usual in `exec-path', but environment variable
614 substitutions (`$HOME', etc.) are not recognized; use
615 `substitute-in-file-name' to perform them (*note File Name Expansion::).
617 Each of the subprocess-creating functions has a BUFFER-OR-NAME
618 argument which specifies where the standard output from the program will
619 go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
620 a filter function handles it. (*Note Filter Functions::, and *Note
621 Read and Print::.) Normally, you should avoid having multiple
622 processes send output to the same buffer because their output would be
625 All three of the subprocess-creating functions have a `&rest'
626 argument, ARGS. The ARGS must all be strings, and they are supplied to
627 PROGRAM as separate command line arguments. Wildcard characters and
628 other shell constructs are not allowed in these strings, since they are
629 passed directly to the specified program.
631 *Please note:* The argument PROGRAM contains only the name of the
632 program; it may not contain any command-line arguments. You must use
633 ARGS to provide those.
635 The subprocess gets its current directory from the value of
636 `default-directory' (*note File Name Expansion::).
638 The subprocess inherits its environment from XEmacs; but you can
639 specify overrides for it with `process-environment'. *Note System
642 - Variable: exec-directory
643 The value of this variable is the name of a directory (a string)
644 that contains programs that come with XEmacs, that are intended
645 for XEmacs to invoke. The program `wakeup' is an example of such
646 a program; the `display-time' command uses it to get a reminder
649 - User Option: exec-path
650 The value of this variable is a list of directories to search for
651 programs to run in subprocesses. Each element is either the name
652 of a directory (i.e., a string), or `nil', which stands for the
653 default directory (which is the value of `default-directory').
655 The value of `exec-path' is used by `call-process' and
656 `start-process' when the PROGRAM argument is not an absolute file
660 File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
662 Creating a Synchronous Process
663 ==============================
665 After a "synchronous process" is created, XEmacs waits for the
666 process to terminate before continuing. Starting Dired is an example of
667 this: it runs `ls' in a synchronous process, then modifies the output
668 slightly. Because the process is synchronous, the entire directory
669 listing arrives in the buffer before XEmacs tries to do anything with
672 While Emacs waits for the synchronous subprocess to terminate, the
673 user can quit by typing `C-g'. The first `C-g' tries to kill the
674 subprocess with a `SIGINT' signal; but it waits until the subprocess
675 actually terminates before quitting. If during that time the user
676 types another `C-g', that kills the subprocess instantly with `SIGKILL'
677 and quits immediately. *Note Quitting::.
679 The synchronous subprocess functions returned `nil' in version 18.
680 In version 19, they return an indication of how the process terminated.
682 - Function: call-process program &optional infile destination display
684 This function calls PROGRAM in a separate process and waits for it
687 The standard input for the process comes from file INFILE if
688 INFILE is not `nil' and from `/dev/null' otherwise. The argument
689 DESTINATION says where to put the process output. Here are the
693 Insert the output in that buffer, before point. This
694 includes both the standard output stream and the standard
695 error stream of the process.
698 Find or create a buffer with that name, then insert the
699 output in that buffer, before point.
702 Insert the output in the current buffer, before point.
708 Discard the output, and return immediately without waiting
709 for the subprocess to finish.
711 In this case, the process is not truly synchronous, since it
712 can run in parallel with Emacs; but you can think of it as
713 synchronous in that Emacs is essentially finished with the
714 subprocess as soon as this function returns.
716 (REAL-DESTINATION ERROR-DESTINATION)
717 Keep the standard output stream separate from the standard
718 error stream; deal with the ordinary output as specified by
719 REAL-DESTINATION, and dispose of the error output according
720 to ERROR-DESTINATION. The value `nil' means discard it, `t'
721 means mix it with the ordinary output, and a string specifies
722 a file name to redirect error output into.
724 You can't directly specify a buffer to put the error output
725 in; that is too difficult to implement. But you can achieve
726 this result by sending the error output to a temporary file
727 and then inserting the file into a buffer.
729 If DISPLAY is non-`nil', then `call-process' redisplays the buffer
730 as output is inserted. Otherwise the function does no redisplay,
731 and the results become visible on the screen only when XEmacs
732 redisplays that buffer in the normal course of events.
734 The remaining arguments, ARGS, are strings that specify command
735 line arguments for the program.
737 The value returned by `call-process' (unless you told it not to
738 wait) indicates the reason for process termination. A number
739 gives the exit status of the subprocess; 0 means success, and any
740 other value means failure. If the process terminated with a
741 signal, `call-process' returns a string describing the signal.
743 In the examples below, the buffer `foo' is current.
745 (call-process "pwd" nil t)
748 ---------- Buffer: foo ----------
749 /usr/user/lewis/manual
750 ---------- Buffer: foo ----------
752 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
755 ---------- Buffer: bar ----------
756 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
758 ---------- Buffer: bar ----------
760 The `insert-directory' function contains a good example of the use
763 (call-process insert-directory-program nil t nil switches
765 (concat (file-name-as-directory file) ".")
768 - Function: call-process-region start end program &optional delete
769 destination display &rest args
770 This function sends the text between START to END as standard
771 input to a process running PROGRAM. It deletes the text sent if
772 DELETE is non-`nil'; this is useful when BUFFER is `t', to insert
773 the output in the current buffer.
775 The arguments DESTINATION and DISPLAY control what to do with the
776 output from the subprocess, and whether to update the display as
777 it comes in. For details, see the description of `call-process',
778 above. If DESTINATION is the integer 0, `call-process-region'
779 discards the output and returns `nil' immediately, without waiting
780 for the subprocess to finish.
782 The remaining arguments, ARGS, are strings that specify command
783 line arguments for the program.
785 The return value of `call-process-region' is just like that of
786 `call-process': `nil' if you told it to return without waiting;
787 otherwise, a number or string which indicates how the subprocess
790 In the following example, we use `call-process-region' to run the
791 `cat' utility, with standard input being the first five characters
792 in buffer `foo' (the word `input'). `cat' copies its standard
793 input into its standard output. Since the argument DESTINATION is
794 `t', this output is inserted in the current buffer.
796 ---------- Buffer: foo ----------
798 ---------- Buffer: foo ----------
800 (call-process-region 1 6 "cat" nil t)
803 ---------- Buffer: foo ----------
805 ---------- Buffer: foo ----------
807 The `shell-command-on-region' command uses `call-process-region'
812 shell-file-name ; Name of program.
813 nil ; Do not delete region.
814 buffer ; Send output to `buffer'.
815 nil ; No redisplay during output.
816 "-c" command) ; Arguments for the shell.
819 File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
824 On MS-DOS, you must indicate whether the data going to and from a
825 synchronous subprocess are text or binary. Text data requires
826 translation between the end-of-line convention used within Emacs (a
827 single newline character) and the convention used outside Emacs (the
828 two-character sequence, CRLF).
830 The variable `binary-process-input' applies to input sent to the
831 subprocess, and `binary-process-output' applies to output received from
832 it. A non-`nil' value means the data is non-text; `nil' means the data
833 is text, and calls for conversion.
835 - Variable: binary-process-input
836 If this variable is `nil', convert newlines to CRLF sequences in
837 the input to a synchronous subprocess.
839 - Variable: binary-process-output
840 If this variable is `nil', convert CRLF sequences to newlines in
841 the output from a synchronous subprocess.
843 *Note Files and MS-DOS::, for related information.
846 File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
848 Creating an Asynchronous Process
849 ================================
851 After an "asynchronous process" is created, Emacs and the Lisp
852 program both continue running immediately. The process may thereafter
853 run in parallel with Emacs, and the two may communicate with each other
854 using the functions described in following sections. Here we describe
855 how to create an asynchronous process with `start-process'.
857 - Function: start-process name buffer-or-name program &rest args
858 This function creates a new asynchronous subprocess and starts the
859 program PROGRAM running in it. It returns a process object that
860 stands for the new subprocess in Lisp. The argument NAME
861 specifies the name for the process object; if a process with this
862 name already exists, then NAME is modified (by adding `<1>', etc.)
863 to be unique. The buffer BUFFER-OR-NAME is the buffer to
864 associate with the process.
866 The remaining arguments, ARGS, are strings that specify command
867 line arguments for the program.
869 In the example below, the first process is started and runs
870 (rather, sleeps) for 100 seconds. Meanwhile, the second process
871 is started, and given the name `my-process<1>' for the sake of
872 uniqueness. It inserts the directory listing at the end of the
873 buffer `foo', before the first process finishes. Then it
874 finishes, and a message to that effect is inserted in the buffer.
875 Much later, the first process finishes, and another message is
876 inserted in the buffer for it.
878 (start-process "my-process" "foo" "sleep" "100")
879 => #<process my-process>
881 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
882 => #<process my-process<1>>
884 ---------- Buffer: foo ----------
886 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
887 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
889 Process my-process<1> finished
891 Process my-process finished
892 ---------- Buffer: foo ----------
894 - Function: start-process-shell-command name buffer-or-name command
896 This function is like `start-process' except that it uses a shell
897 to execute the specified command. The argument COMMAND is a shell
898 command name, and COMMAND-ARGS are the arguments for the shell
901 - Variable: process-connection-type
902 This variable controls the type of device used to communicate with
903 asynchronous subprocesses. If it is non-`nil', then PTYs are
904 used, when available. Otherwise, pipes are used.
906 PTYs are usually preferable for processes visible to the user, as
907 in Shell mode, because they allow job control (`C-c', `C-z', etc.)
908 to work between the process and its children whereas pipes do not.
909 For subprocesses used for internal purposes by programs, it is
910 often better to use a pipe, because they are more efficient. In
911 addition, the total number of PTYs is limited on many systems and
912 it is good not to waste them.
914 The value `process-connection-type' is used when `start-process'
915 is called. So you can specify how to communicate with one
916 subprocess by binding the variable around the call to
919 (let ((process-connection-type nil)) ; Use a pipe.
922 To determine whether a given subprocess actually got a pipe or a
923 PTY, use the function `process-tty-name' (*note Process
927 File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
932 "Deleting a process" disconnects XEmacs immediately from the
933 subprocess, and removes it from the list of active processes. It sends
934 a signal to the subprocess to make the subprocess terminate, but this is
935 not guaranteed to happen immediately. The process object itself
936 continues to exist as long as other Lisp objects point to it.
938 You can delete a process explicitly at any time. Processes are
939 deleted automatically after they terminate, but not necessarily right
940 away. If you delete a terminated process explicitly before it is
941 deleted automatically, no harm results.
943 - Variable: delete-exited-processes
944 This variable controls automatic deletion of processes that have
945 terminated (due to calling `exit' or to a signal). If it is
946 `nil', then they continue to exist until the user runs
947 `list-processes'. Otherwise, they are deleted immediately after
950 - Function: delete-process name
951 This function deletes the process associated with NAME, killing it
952 with a `SIGHUP' signal. The argument NAME may be a process, the
953 name of a process, a buffer, or the name of a buffer.
955 (delete-process "*shell*")
958 - Function: process-kill-without-query process &optional
960 This function declares that XEmacs need not query the user if
961 PROCESS is still running when XEmacs is exited. The process will
962 be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
963 _will_ query the user (this is the default). The return value is
964 `t' if a query was formerly required, and `nil' otherwise.
966 (process-kill-without-query (get-process "shell"))
970 File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
975 Several functions return information about processes.
976 `list-processes' is provided for interactive use.
978 - Command: list-processes
979 This command displays a listing of all living processes. In
980 addition, it finally deletes any process whose status was `Exited'
981 or `Signaled'. It returns `nil'.
983 - Function: process-list
984 This function returns a list of all processes that have not been
988 => (#<process display-time> #<process shell>)
990 - Function: get-process name
991 This function returns the process named NAME, or `nil' if there is
992 none. An error is signaled if NAME is not a string.
994 (get-process "shell")
997 - Function: process-command process
998 This function returns the command that was executed to start
999 PROCESS. This is a list of strings, the first string being the
1000 program executed and the rest of the strings being the arguments
1001 that were given to the program.
1003 (process-command (get-process "shell"))
1004 => ("/bin/csh" "-i")
1006 - Function: process-id process
1007 This function returns the PID of PROCESS. This is an integer that
1008 distinguishes the process PROCESS from all other processes running
1009 on the same computer at the current time. The PID of a process is
1010 chosen by the operating system kernel when the process is started
1011 and remains constant as long as the process exists.
1013 - Function: process-name process
1014 This function returns the name of PROCESS.
1016 - Function: process-status process-name
1017 This function returns the status of PROCESS-NAME as a symbol. The
1018 argument PROCESS-NAME must be a process, a buffer, a process name
1019 (string) or a buffer name (string).
1021 The possible values for an actual subprocess are:
1024 for a process that is running.
1027 for a process that is stopped but continuable.
1030 for a process that has exited.
1033 for a process that has received a fatal signal.
1036 for a network connection that is open.
1039 for a network connection that is closed. Once a connection
1040 is closed, you cannot reopen it, though you might be able to
1041 open a new connection to the same place.
1044 if PROCESS-NAME is not the name of an existing process.
1046 (process-status "shell")
1048 (process-status (get-buffer "*shell*"))
1055 For a network connection, `process-status' returns one of the
1056 symbols `open' or `closed'. The latter means that the other side
1057 closed the connection, or XEmacs did `delete-process'.
1059 In earlier Emacs versions (prior to version 19), the status of a
1060 network connection was `run' if open, and `exit' if closed.
1062 - Function: process-kill-without-query-p process
1063 This function returns whether PROCESS will be killed without
1064 querying the user, if it is running when XEmacs is exited. The
1065 default value is `nil'.
1067 - Function: process-exit-status process
1068 This function returns the exit status of PROCESS or the signal
1069 number that killed it. (Use the result of `process-status' to
1070 determine which of those it is.) If PROCESS has not yet
1071 terminated, the value is 0.
1073 - Function: process-tty-name process
1074 This function returns the terminal name that PROCESS is using for
1075 its communication with Emacs--or `nil' if it is using pipes
1076 instead of a terminal (see `process-connection-type' in *Note
1077 Asynchronous Processes::).
1080 File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
1082 Sending Input to Processes
1083 ==========================
1085 Asynchronous subprocesses receive input when it is sent to them by
1086 XEmacs, which is done with the functions in this section. You must
1087 specify the process to send input to, and the input data to send. The
1088 data appears on the "standard input" of the subprocess.
1090 Some operating systems have limited space for buffered input in a
1091 PTY. On these systems, Emacs sends an EOF periodically amidst the
1092 other characters, to force them through. For most programs, these EOFs
1095 - Function: process-send-string process-name string
1096 This function sends PROCESS-NAME the contents of STRING as
1097 standard input. The argument PROCESS-NAME must be a process or
1098 the name of a process. If it is `nil', the current buffer's
1101 The function returns `nil'.
1103 (process-send-string "shell<1>" "ls\n")
1107 ---------- Buffer: *shell* ----------
1109 introduction.texi syntax-tables.texi~
1110 introduction.texi~ text.texi
1111 introduction.txt text.texi~
1113 ---------- Buffer: *shell* ----------
1115 - Command: process-send-region process-name start end
1116 This function sends the text in the region defined by START and
1117 END as standard input to PROCESS-NAME, which is a process or a
1118 process name. (If it is `nil', the current buffer's process is
1121 An error is signaled unless both START and END are integers or
1122 markers that indicate positions in the current buffer. (It is
1123 unimportant which number is larger.)
1125 - Function: process-send-eof &optional process-name
1126 This function makes PROCESS-NAME see an end-of-file in its input.
1127 The EOF comes after any text already sent to it.
1129 If PROCESS-NAME is not supplied, or if it is `nil', then this
1130 function sends the EOF to the current buffer's process. An error
1131 is signaled if the current buffer has no process.
1133 The function returns PROCESS-NAME.
1135 (process-send-eof "shell")
1139 File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
1141 Sending Signals to Processes
1142 ============================
1144 "Sending a signal" to a subprocess is a way of interrupting its
1145 activities. There are several different signals, each with its own
1146 meaning. The set of signals and their names is defined by the operating
1147 system. For example, the signal `SIGINT' means that the user has typed
1148 `C-c', or that some analogous thing has happened.
1150 Each signal has a standard effect on the subprocess. Most signals
1151 kill the subprocess, but some stop or resume execution instead. Most
1152 signals can optionally be handled by programs; if the program handles
1153 the signal, then we can say nothing in general about its effects.
1155 The set of signals and their names is defined by the operating
1156 system; XEmacs has facilities for sending only a few of the signals
1157 that are defined. XEmacs can send signals only to its own subprocesses.
1159 You can send signals explicitly by calling the functions in this
1160 section. XEmacs also sends signals automatically at certain times:
1161 killing a buffer sends a `SIGHUP' signal to all its associated
1162 processes; killing XEmacs sends a `SIGHUP' signal to all remaining
1163 processes. (`SIGHUP' is a signal that usually indicates that the user
1166 Each of the signal-sending functions takes two optional arguments:
1167 PROCESS-NAME and CURRENT-GROUP.
1169 The argument PROCESS-NAME must be either a process, the name of one,
1170 or `nil'. If it is `nil', the process defaults to the process
1171 associated with the current buffer. An error is signaled if
1172 PROCESS-NAME does not identify a process.
1174 The argument CURRENT-GROUP is a flag that makes a difference when
1175 you are running a job-control shell as an XEmacs subprocess. If it is
1176 non-`nil', then the signal is sent to the current process-group of the
1177 terminal that XEmacs uses to communicate with the subprocess. If the
1178 process is a job-control shell, this means the shell's current subjob.
1179 If it is `nil', the signal is sent to the process group of the
1180 immediate subprocess of XEmacs. If the subprocess is a job-control
1181 shell, this is the shell itself.
1183 The flag CURRENT-GROUP has no effect when a pipe is used to
1184 communicate with the subprocess, because the operating system does not
1185 support the distinction in the case of pipes. For the same reason,
1186 job-control shells won't work when a pipe is used. See
1187 `process-connection-type' in *Note Asynchronous Processes::.
1189 - Function: interrupt-process &optional process-name current-group
1190 This function interrupts the process PROCESS-NAME by sending the
1191 signal `SIGINT'. Outside of XEmacs, typing the "interrupt
1192 character" (normally `C-c' on some systems, and `DEL' on others)
1193 sends this signal. When the argument CURRENT-GROUP is non-`nil',
1194 you can think of this function as "typing `C-c'" on the terminal
1195 by which XEmacs talks to the subprocess.
1197 - Function: kill-process &optional process-name current-group
1198 This function kills the process PROCESS-NAME by sending the signal
1199 `SIGKILL'. This signal kills the subprocess immediately, and
1200 cannot be handled by the subprocess.
1202 - Function: quit-process &optional process-name current-group
1203 This function sends the signal `SIGQUIT' to the process
1204 PROCESS-NAME. This signal is the one sent by the "quit character"
1205 (usually `C-b' or `C-\') when you are not inside XEmacs.
1207 - Function: stop-process &optional process-name current-group
1208 This function stops the process PROCESS-NAME by sending the signal
1209 `SIGTSTP'. Use `continue-process' to resume its execution.
1211 On systems with job control, the "stop character" (usually `C-z')
1212 sends this signal (outside of XEmacs). When CURRENT-GROUP is
1213 non-`nil', you can think of this function as "typing `C-z'" on the
1214 terminal XEmacs uses to communicate with the subprocess.
1216 - Function: continue-process &optional process-name current-group
1217 This function resumes execution of the process PROCESS by sending
1218 it the signal `SIGCONT'. This presumes that PROCESS-NAME was
1221 - Function: signal-process pid signal
1222 This function sends a signal to process PID, which need not be a
1223 child of XEmacs. The argument SIGNAL specifies which signal to
1224 send; it should be an integer.
1227 File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
1229 Receiving Output from Processes
1230 ===============================
1232 There are two ways to receive the output that a subprocess writes to
1233 its standard output stream. The output can be inserted in a buffer,
1234 which is called the associated buffer of the process, or a function
1235 called the "filter function" can be called to act on the output. If
1236 the process has no buffer and no filter function, its output is
1241 * Process Buffers:: If no filter, output is put in a buffer.
1242 * Filter Functions:: Filter functions accept output from the process.
1243 * Accepting Output:: Explicitly permitting subprocess output.
1244 Waiting for subprocess output.