1 This is ../info/lispref.info, produced by makeinfo version 4.0b 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: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
58 The active display table is controlled by the variable
59 `current-display-table'. This is a specifier, which means that you can
60 specify separate values for it in individual buffers, windows, frames,
61 and devices, as well as a global value. It also means that you cannot
62 set this variable using `setq'; use `set-specifier' instead. *Note
63 Specifiers::. (FSF Emacs uses `window-display-table',
64 `buffer-display-table', `standard-display-table', etc. to control the
65 display table. However, specifiers are a cleaner and more powerful way
66 of doing the same thing. FSF Emacs also uses a different format for
67 the contents of a display table, using additional indirection to a
68 "glyph table" and such. Note that "glyph" has a different meaning in
71 - Variable: current-display-table
72 The display table currently in use. This is a specifier.
74 Display tables are used to control how characters are displayed.
75 Each time that redisplay processes a character, it is looked up in
76 all the display tables that apply (obtained by calling
77 `specifier-instance' on `current-display-table' and any overriding
78 display tables specified in currently active faces). The first
79 entry found that matches the character determines how the
80 character is displayed. If there is no matching entry, the
81 default display method is used. (Non-control characters are
82 displayed as themselves and control characters are displayed
83 according to the buffer-local variable `ctl-arrow'. Control
84 characters are further affected by `control-arrow-glyph' and
85 `octal-escape-glyph'.)
87 Each instantiator in this specifier and the display-table
88 specifiers in faces is a display table or a list of such tables.
89 If a list, each table will be searched in turn for an entry
90 matching a particular character. Each display table is one of
92 * A vector, specifying values for characters starting at 0.
94 * A char table, either of type `char' or `generic'.
98 Each entry in a display table should be one of
100 * nil (this entry is ignored and the search continues).
102 * A character (use this character; if it happens to be the same
103 as the original character, default processing happens,
104 otherwise redisplay attempts to display this character
105 directly; #### At some point recursive display-table lookup
106 will be implemented).
108 * A string (display each character in the string directly; ####
109 At some point recursive display-table lookup will be
112 * A glyph (display the glyph; #### At some point recursive
113 display-table lookup will be implemented when a string glyph
116 * A cons of the form (format "STRING") where STRING is a
117 printf-like spec used to process the character. ####
118 Unfortunately no formatting directives other than %% are
121 * A vector (each element of the vector is processed recursively;
122 in such a case, nil elements in the vector are simply
125 #### At some point in the near future, display tables are
126 likely to be expanded to include other features, such as
127 referencing characters in particular fonts and allowing the
128 character search to continue all the way up the chain of
129 specifier instantiators. These features are necessary to
130 properly display Unicode characters.
132 Individual faces can also specify an overriding display table; this
133 is set using `set-face-display-table'. *Note Faces::.
135 If no display table can be determined for a particular window, then
136 XEmacs uses the usual display conventions. *Note Usual Display::.
139 File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
141 Character Descriptors
142 ---------------------
144 Each element of the display-table vector describes how to display a
145 particular character and is called a "character descriptor". A
146 character descriptor can be:
149 Display this particular string wherever the character is to be
153 Display this particular glyph wherever the character is to be
157 The vector may contain strings and/or glyphs. Display the
158 elements of the vector one after another wherever the character is
162 Display according to the standard interpretation (*note Usual
166 File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
171 You can make XEmacs ring a bell, play a sound, or blink the screen to
172 attract the user's attention. Be conservative about how often you do
173 this; frequent bells can become irritating. Also be careful not to use
174 beeping alone when signaling an error is appropriate. (*Note Errors::.)
176 - Function: ding &optional dont-terminate sound device
177 This function beeps, or flashes the screen (see `visible-bell'
178 below). It also terminates any keyboard macro currently executing
179 unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
180 should be a symbol specifying which sound to make. This sound
181 will be played if `visible-bell' is `nil'. (This only works if
182 sound support was compiled into the executable and you are running
183 on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
184 PC. Otherwise you just get a beep.) The optional third argument
185 specifies what device to make the sound on, and defaults to the
188 - Function: beep &optional dont-terminate sound device
189 This is a synonym for `ding'.
191 - User Option: visible-bell
192 This variable determines whether XEmacs should flash the screen to
193 represent a bell. Non-`nil' means yes, `nil' means no. On TTY
194 devices, this is effective only if the Termcap entry for the
195 terminal type has the visible bell flag (`vb') set.
197 - Variable: sound-alist
198 This variable holds an alist associating names with sounds. When
199 `beep' or `ding' is called with one of the name symbols, the
200 associated sound will be generated instead of the standard beep.
202 Each element of `sound-alist' is a list describing a sound. The
203 first element of the list is the name of the sound being defined.
204 Subsequent elements of the list are alternating keyword/value
208 A string of raw sound data, or the name of another sound to
209 play. The symbol `t' here means use the default X beep.
212 An integer from 0-100, defaulting to `bell-volume'.
215 If using the default X beep, the pitch (Hz) to generate.
218 If using the default X beep, the duration (milliseconds).
220 For compatibility, elements of `sound-alist' may also be:
222 * `( sound-name . <sound> )'
224 * `( sound-name <volume> <sound> )'
226 You should probably add things to this list by calling the function
231 - You can only play audio data if running on the console screen
232 of a Sun SparcStation, SGI, or HP9000s700.
234 - The pitch, duration, and volume options are available
235 everywhere, but many X servers ignore the `pitch' option.
237 The following beep-types are used by XEmacs itself:
240 when an auto-save does not succeed
243 when the XEmacs command loop catches an error
246 when you type a key that is undefined
249 when you use an undefined mouse-click combination
252 during completing-read
255 when you type something other than 'y' or 'n'
258 when you type something other than 'yes' or 'no'
261 used when nothing else is appropriate.
263 Other lisp packages may use other beep types, but these are the
264 ones that the C kernel of XEmacs uses.
266 - User Option: bell-volume
267 This variable specifies the default volume for sounds, from 0 to
270 - Command: load-default-sounds
271 This function loads and installs some sound files as beep-types.
273 - Command: load-sound-file filename sound-name &optional volume
274 This function reads in an audio file and adds it to `sound-alist'.
275 The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
276 should be a symbol, specifying the name of the sound. If VOLUME
277 is specified, the sound will be played at that volume; otherwise,
278 the value of BELL-VOLUME will be used.
280 - Function: play-sound sound &optional volume device
281 This function plays sound SOUND, which should be a symbol
282 mentioned in `sound-alist'. If VOLUME is specified, it overrides
283 the value (if any) specified in `sound-alist'. DEVICE specifies
284 the device to play the sound on, and defaults to the selected
287 - Command: play-sound-file file &optional volume device
288 This function plays the named sound file at volume VOLUME, which
289 defaults to `bell-volume'. DEVICE specifies the device to play
290 the sound on, and defaults to the selected device.
293 File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
298 - Function: hash-table-p object
299 This function returns `t' if OBJECT is a hash table, else `nil'.
303 * Introduction to Hash Tables:: Hash tables are fast data structures for
304 implementing simple tables (i.e. finite
305 mappings from keys to values).
306 * Working With Hash Tables:: Hash table functions.
307 * Weak Hash Tables:: Hash tables with special garbage-collection
311 File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
313 Introduction to Hash Tables
314 ===========================
316 A "hash table" is a data structure that provides mappings from
317 arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
318 called "values". A key/value pair is sometimes called an "entry" in
319 the hash table. There are many ways other than hash tables of
320 implementing the same sort of mapping, e.g. association lists (*note
321 Association Lists::) and property lists (*note Property Lists::), but
322 hash tables provide much faster lookup when there are many entries in
323 the mapping. Hash tables are an implementation of the abstract data
324 type "dictionary", also known as "associative array".
326 Internally, hash tables are hashed using the "linear probing" hash
327 table implementation method. This method hashes each key to a
328 particular spot in the hash table, and then scans forward sequentially
329 until a blank entry is found. To look up a key, hash to the appropriate
330 spot, then search forward for the key until either a key is found or a
331 blank entry stops the search. This method is used in preference to
332 double hashing because of changes in recent hardware. The penalty for
333 non-sequential access to memory has been increasing, and this
334 compensates for the problem of clustering that linear probing entails.
336 When hash tables are created, the user may (but is not required to)
337 specify initial properties that influence performance.
339 Use the `:size' parameter to specify the number of entries that are
340 likely to be stored in the hash table, to avoid the overhead of resizing
341 the table. But if the pre-allocated space for the entries is never
342 used, it is simply wasted and makes XEmacs slower. Excess unused hash
343 table entries exact a small continuous performance penalty, since they
344 must be scanned at every garbage collection. If the number of entries
345 in the hash table is unknown, simply avoid using the `:size' keyword.
347 Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
348 the algorithm for deciding when to rehash the hash table. For
349 temporary hash tables that are going to be very heavily used, use a
350 small rehash threshold, for example, 0.4 and a large rehash size, for
351 example 2.0. For permanent hash tables that will be infrequently used,
352 specify a large rehash threshold, for example 0.8.
354 Hash tables can also be created by the lisp reader using structure
356 #s(hash-table size 20 data (foo 1 bar 2))
358 The structure syntax accepts the same keywords as `make-hash-table'
359 (without the `:' character), as well as the additional keyword `data',
360 which specifies the initial hash table contents.
362 - Function: make-hash-table &key `test' `size' `rehash-size'
363 `rehash-threshold' `weakness'
364 This function returns a new empty hash table object.
366 Keyword `:test' can be `eq', `eql' (default) or `equal'.
367 Comparison between keys is done using this function. If speed is
368 important, consider using `eq'. When storing strings in the hash
369 table, you will likely need to use `equal'.
371 Keyword `:size' specifies the number of keys likely to be inserted.
372 This number of entries can be inserted without enlarging the hash
375 Keyword `:rehash-size' must be a float greater than 1.0, and
376 specifies the factor by which to increase the size of the hash
377 table when enlarging.
379 Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
380 and specifies the load factor of the hash table which triggers
383 Non-standard keyword `:weakness' can be `nil' (default), `t',
384 `key-and-value', `key', `value' or `key-or-value'. `t' is an
385 alias for `key-and-value'.
387 A key-and-value-weak hash table, also known as a fully-weak or
388 simply as a weak hash table, is one whose pointers do not count as
389 GC referents: for any key-value pair in the hash table, if the only
390 remaining pointer to either the key or the value is in a weak hash
391 table, then the pair will be removed from the hash table, and the
392 key and value collected. A non-weak hash table (or any other
393 pointer) would prevent the object from being collected.
395 A key-weak hash table is similar to a fully-weak hash table except
396 that a key-value pair will be removed only if the key remains
397 unmarked outside of weak hash tables. The pair will remain in the
398 hash table if the key is pointed to by something other than a weak
399 hash table, even if the value is not.
401 A value-weak hash table is similar to a fully-weak hash table
402 except that a key-value pair will be removed only if the value
403 remains unmarked outside of weak hash tables. The pair will
404 remain in the hash table if the value is pointed to by something
405 other than a weak hash table, even if the key is not.
407 A key-or-value-weak hash table is similar to a fully-weak hash
408 table except that a key-value pair will be removed only if the
409 value and the key remain unmarked outside of weak hash tables.
410 The pair will remain in the hash table if the value or key are
411 pointed to by something other than a weak hash table, even if the
414 - Function: copy-hash-table hash-table
415 This function returns a new hash table which contains the same
416 keys and values as HASH-TABLE. The keys and values will not
417 themselves be copied.
419 - Function: hash-table-count hash-table
420 This function returns the number of entries in HASH-TABLE.
422 - Function: hash-table-test hash-table
423 This function returns the test function of HASH-TABLE. This can
424 be one of `eq', `eql' or `equal'.
426 - Function: hash-table-size hash-table
427 This function returns the current number of slots in HASH-TABLE,
428 whether occupied or not.
430 - Function: hash-table-rehash-size hash-table
431 This function returns the current rehash size of HASH-TABLE. This
432 is a float greater than 1.0; the factor by which HASH-TABLE is
433 enlarged when the rehash threshold is exceeded.
435 - Function: hash-table-rehash-threshold hash-table
436 This function returns the current rehash threshold of HASH-TABLE.
437 This is a float between 0.0 and 1.0; the maximum "load factor" of
438 HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
440 - Function: hash-table-weakness hash-table
441 This function returns the weakness of HASH-TABLE. This can be one
442 of `nil', `t', `key' or `value'.
445 File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
447 Working With Hash Tables
448 ========================
450 - Function: puthash key value hash-table
451 This function hashes KEY to VALUE in HASH-TABLE.
453 - Function: gethash key hash-table &optional default
454 This function finds the hash value for KEY in HASH-TABLE. If
455 there is no entry for KEY in HASH-TABLE, DEFAULT is returned
456 (which in turn defaults to `nil').
458 - Function: remhash key hash-table
459 This function removes the entry for KEY from HASH-TABLE. Does
460 nothing if there is no entry for KEY in HASH-TABLE.
462 - Function: clrhash hash-table
463 This function removes all entries from HASH-TABLE, leaving it
466 - Function: maphash function hash-table
467 This function maps FUNCTION over entries in HASH-TABLE, calling it
468 with two args, each key and value in the hash table.
470 FUNCTION may not modify HASH-TABLE, with the one exception that
471 FUNCTION may remhash or puthash the entry currently being
472 processed by FUNCTION.
475 File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
480 A "weak hash table" is a special variety of hash table whose
481 elements do not count as GC referents. For any key-value pair in such a
482 hash table, if either the key or value (or in some cases, if one
483 particular one of the two) has no references to it outside of weak hash
484 tables (and similar structures such as weak lists), the pair will be
485 removed from the table, and the key and value collected. A non-weak
486 hash table (or any other pointer) would prevent the objects from being
489 Weak hash tables are useful for keeping track of information in a
490 non-obtrusive way, for example to implement caching. If the cache
491 contains objects such as buffers, markers, image instances, etc. that
492 will eventually disappear and get garbage-collected, using a weak hash
493 table ensures that these objects are collected normally rather than
494 remaining around forever, long past their actual period of use.
495 (Otherwise, you'd have to explicitly map over the hash table every so
496 often and remove unnecessary elements.)
498 There are four types of weak hash tables:
500 key-and-value-weak hash tables
501 In these hash tables, also known as fully weak or simply as weak
502 hash tables, a pair disappears if either the key or the value is
503 unreferenced outside of the table.
506 In these hash tables, a pair disappears if the key is unreferenced
507 outside of the table, regardless of how the value is referenced.
509 value-weak hash tables
510 In these hash tables, a pair disappears if the value is
511 unreferenced outside of the table, regardless of how the key is
514 key-or-value-weak hash tables
515 In these hash tables, a pair disappears if both the key and the
516 value are unreferenced outside of the table.
518 Also see *Note Weak Lists::.
520 Weak hash tables are created by specifying the `:weakness' keyword to
524 File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
529 A range table is a table that efficiently associated values with
532 Note that range tables have a read syntax, like this:
534 #s(range-table data ((-3 2) foo (5 20) bar))
536 This maps integers in the range (-3, 2) to `foo' and integers in the
537 range (5, 20) to `bar'.
539 - Function: range-table-p object
540 Return non-`nil' if OBJECT is a range table.
544 * Introduction to Range Tables:: Range tables efficiently map ranges of
546 * Working With Range Tables:: Range table functions.
549 File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
551 Introduction to Range Tables
552 ============================
554 - Function: make-range-table
555 Make a new, empty range table.
557 - Function: copy-range-table range-table
558 This function returns a new range table which contains the same
559 values for the same ranges as RANGE-TABLE. The values will not
560 themselves be copied.
563 File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
565 Working With Range Tables
566 =========================
568 - Function: get-range-table pos range-table &optional default
569 This function finds value for position POS in RANGE-TABLE. If
570 there is no corresponding value, return DEFAULT (defaults to
573 - Function: put-range-table start end value range-table
574 This function sets the value for range (START, END) to be VALUE in
577 - Function: remove-range-table start end range-table
578 This function removes the value for range (START, END) in
581 - Function: clear-range-table range-table
582 This function flushes RANGE-TABLE.
584 - Function: map-range-table function range-table
585 This function maps FUNCTION over entries in RANGE-TABLE, calling
586 it with three args, the beginning and end of the range and the
590 File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
595 - Function: databasep object
596 This function returns non-`nil' if OBJECT is a database.
600 * Connecting to a Database::
601 * Working With a Database::
602 * Other Database Functions::
605 File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
607 Connecting to a Database
608 ========================
610 - Function: open-database file &optional type subtype access mode
611 This function opens database FILE, using database method TYPE and
612 SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
613 can be any combination of `r' `w' and `+', for read, write, and
616 TYPE can have the value `'dbm' or `'berkeley-db' to select the
617 type of database file to use. (Note: XEmacs may not support both
620 For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be
623 For a TYPE of `'berkeley-db', the following subtypes are
624 available: `'hash', `'btree', and `'recno'. See the manpages for
625 the Berkeley DB functions for more information about these types.
627 - Function: close-database database
628 This function closes database DATABASE.
630 - Function: database-live-p object
631 This function returns `t' if OBJECT is an active database, else
635 File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
637 Working With a Database
638 =======================
640 - Function: get-database key database &optional default
641 This function finds the value for KEY in DATABASE. If there is no
642 corresponding value, DEFAULT is returned (`nil' if DEFAULT is
645 - Function: map-database function database
646 This function maps FUNCTION over entries in DATABASE, calling it
647 with two args, each key and value in the database.
649 - Function: put-database key value database &optional replace
650 This function stores KEY and VALUE in DATABASE. If optional
651 fourth arg REPLACE is non-`nil', replace any existing entry in the
654 - Function: remove-database key database
655 This function removes KEY from DATABASE.
658 File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
660 Other Database Functions
661 ========================
663 - Function: database-file-name database
664 This function returns the filename associated with DATABASE.
666 - Function: database-last-error &optional database
667 This function returns the last error associated with DATABASE.
669 - Function: database-subtype database
670 This function returns the subtype of DATABASE, if any.
672 - Function: database-type database
673 This function returns the type of DATABASE.
676 File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
681 In the terminology of operating systems, a "process" is a space in
682 which a program can execute. XEmacs runs in a process. XEmacs Lisp
683 programs can invoke other programs in processes of their own. These are
684 called "subprocesses" or "child processes" of the XEmacs process, which
685 is their "parent process".
687 A subprocess of XEmacs may be "synchronous" or "asynchronous",
688 depending on how it is created. When you create a synchronous
689 subprocess, the Lisp program waits for the subprocess to terminate
690 before continuing execution. When you create an asynchronous
691 subprocess, it can run in parallel with the Lisp program. This kind of
692 subprocess is represented within XEmacs by a Lisp object which is also
693 called a "process". Lisp programs can use this object to communicate
694 with the subprocess or to control it. For example, you can send
695 signals, obtain status information, receive output from the process, or
698 - Function: processp object
699 This function returns `t' if OBJECT is a process, `nil' otherwise.
703 * Subprocess Creation:: Functions that start subprocesses.
704 * Synchronous Processes:: Details of using synchronous subprocesses.
705 * MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
706 for data sent to and from a subprocess.
707 * Asynchronous Processes:: Starting up an asynchronous subprocess.
708 * Deleting Processes:: Eliminating an asynchronous subprocess.
709 * Process Information:: Accessing run-status and other attributes.
710 * Input to Processes:: Sending input to an asynchronous subprocess.
711 * Signals to Processes:: Stopping, continuing or interrupting
712 an asynchronous subprocess.
713 * Output from Processes:: Collecting output from an asynchronous subprocess.
714 * Sentinels:: Sentinels run when process run-status changes.
715 * Process Window Size:: Changing the logical window size of a process.
716 * Transaction Queues:: Transaction-based communication with subprocesses.
717 * Network:: Opening network connections.
720 File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
722 Functions that Create Subprocesses
723 ==================================
725 There are three functions that create a new subprocess in which to
726 run a program. One of them, `start-process', creates an asynchronous
727 process and returns a process object (*note Asynchronous Processes::).
728 The other two, `call-process' and `call-process-region', create a
729 synchronous process and do not return a process object (*note
730 Synchronous Processes::).
732 Synchronous and asynchronous processes are explained in the following
733 sections. Since the three functions are all called in a similar
734 fashion, their common arguments are described here.
736 In all cases, the function's PROGRAM argument specifies the program
737 to be run. An error is signaled if the file is not found or cannot be
738 executed. If the file name is relative, the variable `exec-path'
739 contains a list of directories to search. Emacs initializes
740 `exec-path' when it starts up, based on the value of the environment
741 variable `PATH'. The standard file name constructs, `~', `.', and
742 `..', are interpreted as usual in `exec-path', but environment variable
743 substitutions (`$HOME', etc.) are not recognized; use
744 `substitute-in-file-name' to perform them (*note File Name Expansion::).
746 Each of the subprocess-creating functions has a BUFFER-OR-NAME
747 argument which specifies where the standard output from the program will
748 go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
749 a filter function handles it. (*Note Filter Functions::, and *Note
750 Read and Print::.) Normally, you should avoid having multiple
751 processes send output to the same buffer because their output would be
754 All three of the subprocess-creating functions have a `&rest'
755 argument, ARGS. The ARGS must all be strings, and they are supplied to
756 PROGRAM as separate command line arguments. Wildcard characters and
757 other shell constructs are not allowed in these strings, since they are
758 passed directly to the specified program.
760 *Please note:* The argument PROGRAM contains only the name of the
761 program; it may not contain any command-line arguments. You must use
762 ARGS to provide those.
764 If you want to use features of the shell, then invoke the shell
765 directly using, for example, PROGRAM of `"sh"', and ARGS of `"-c"' and
768 The subprocess gets its current directory from the value of
769 `default-directory' (*note File Name Expansion::).
771 The subprocess inherits its environment from XEmacs; but you can
772 specify overrides for it with `process-environment'. *Note System
775 - Variable: exec-directory
776 The value of this variable is the name of a directory (a string)
777 that contains programs that come with XEmacs, that are intended
778 for XEmacs to invoke. The program `wakeup' is an example of such
779 a program; the `display-time' command uses it to get a reminder
782 - User Option: exec-path
783 The value of this variable is a list of directories to search for
784 programs to run in subprocesses. Each element is either the name
785 of a directory (i.e., a string), or `nil', which stands for the
786 default directory (which is the value of `default-directory').
788 The value of `exec-path' is used by `call-process' and
789 `start-process' when the PROGRAM argument is not an absolute file
793 File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
795 Creating a Synchronous Process
796 ==============================
798 After a "synchronous process" is created, XEmacs waits for the
799 process to terminate before continuing. Starting Dired is an example of
800 this: it runs `ls' in a synchronous process, then modifies the output
801 slightly. Because the process is synchronous, the entire directory
802 listing arrives in the buffer before XEmacs tries to do anything with
805 While Emacs waits for the synchronous subprocess to terminate, the
806 user can quit by typing `C-g'. The first `C-g' tries to kill the
807 subprocess with a `SIGINT' signal; but it waits until the subprocess
808 actually terminates before quitting. If during that time the user
809 types another `C-g', that kills the subprocess instantly with `SIGKILL'
810 and quits immediately. *Note Quitting::.
812 The synchronous subprocess functions returned `nil' in version 18.
813 In version 19, they return an indication of how the process terminated.
815 - Function: call-process program &optional infile destination display
817 This function calls PROGRAM in a separate process and waits for it
820 The standard input for the process comes from file INFILE if
821 INFILE is not `nil' and from `/dev/null' otherwise. The argument
822 DESTINATION says where to put the process output. Here are the
826 Insert the output in that buffer, before point. This
827 includes both the standard output stream and the standard
828 error stream of the process.
831 Find or create a buffer with that name, then insert the
832 output in that buffer, before point.
835 Insert the output in the current buffer, before point.
841 Discard the output, and return immediately without waiting
842 for the subprocess to finish.
844 In this case, the process is not truly synchronous, since it
845 can run in parallel with Emacs; but you can think of it as
846 synchronous in that Emacs is essentially finished with the
847 subprocess as soon as this function returns.
849 (REAL-DESTINATION ERROR-DESTINATION)
850 Keep the standard output stream separate from the standard
851 error stream; deal with the ordinary output as specified by
852 REAL-DESTINATION, and dispose of the error output according
853 to ERROR-DESTINATION. The value `nil' means discard it, `t'
854 means mix it with the ordinary output, and a string specifies
855 a file name to redirect error output into.
857 You can't directly specify a buffer to put the error output
858 in; that is too difficult to implement. But you can achieve
859 this result by sending the error output to a temporary file
860 and then inserting the file into a buffer.
862 If DISPLAY is non-`nil', then `call-process' redisplays the buffer
863 as output is inserted. Otherwise the function does no redisplay,
864 and the results become visible on the screen only when XEmacs
865 redisplays that buffer in the normal course of events.
867 The remaining arguments, ARGS, are strings that specify command
868 line arguments for the program.
870 The value returned by `call-process' (unless you told it not to
871 wait) indicates the reason for process termination. A number
872 gives the exit status of the subprocess; 0 means success, and any
873 other value means failure. If the process terminated with a
874 signal, `call-process' returns a string describing the signal.
876 In the examples below, the buffer `foo' is current.
878 (call-process "pwd" nil t)
881 ---------- Buffer: foo ----------
882 /usr/user/lewis/manual
883 ---------- Buffer: foo ----------
885 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
888 ---------- Buffer: bar ----------
889 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
891 ---------- Buffer: bar ----------
893 The `insert-directory' function contains a good example of the use
896 (call-process insert-directory-program nil t nil switches
898 (concat (file-name-as-directory file) ".")
901 - Function: call-process-region start end program &optional deletep
902 destination displayp &rest args
903 This function sends the text between START to END as standard
904 input to a process running PROGRAM. It deletes the text sent if
905 DELETEP is non-`nil'; this is useful when BUFFER is `t', to insert
906 the output in the current buffer.
908 The arguments DESTINATION and DISPLAYP control what to do with the
909 output from the subprocess, and whether to update the display as
910 it comes in. For details, see the description of `call-process',
911 above. If DESTINATION is the integer 0, `call-process-region'
912 discards the output and returns `nil' immediately, without waiting
913 for the subprocess to finish.
915 The remaining arguments, ARGS, are strings that specify command
916 line arguments for the program.
918 The return value of `call-process-region' is just like that of
919 `call-process': `nil' if you told it to return without waiting;
920 otherwise, a number or string which indicates how the subprocess
923 In the following example, we use `call-process-region' to run the
924 `cat' utility, with standard input being the first five characters
925 in buffer `foo' (the word `input'). `cat' copies its standard
926 input into its standard output. Since the argument DESTINATION is
927 `t', this output is inserted in the current buffer.
929 ---------- Buffer: foo ----------
931 ---------- Buffer: foo ----------
933 (call-process-region 1 6 "cat" nil t)
936 ---------- Buffer: foo ----------
938 ---------- Buffer: foo ----------
940 The `shell-command-on-region' command uses `call-process-region'
945 shell-file-name ; Name of program.
946 nil ; Do not delete region.
947 buffer ; Send output to `buffer'.
948 nil ; No redisplay during output.
949 "-c" command) ; Arguments for the shell.
952 File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
957 On MS-DOS, you must indicate whether the data going to and from a
958 synchronous subprocess are text or binary. Text data requires
959 translation between the end-of-line convention used within Emacs (a
960 single newline character) and the convention used outside Emacs (the
961 two-character sequence, CRLF).
963 The variable `binary-process-input' applies to input sent to the
964 subprocess, and `binary-process-output' applies to output received from
965 it. A non-`nil' value means the data is non-text; `nil' means the data
966 is text, and calls for conversion.
968 - Variable: binary-process-input
969 If this variable is `nil', convert newlines to CRLF sequences in
970 the input to a synchronous subprocess.
972 - Variable: binary-process-output
973 If this variable is `nil', convert CRLF sequences to newlines in
974 the output from a synchronous subprocess.
976 *Note Files and MS-DOS::, for related information.
979 File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
981 Creating an Asynchronous Process
982 ================================
984 After an "asynchronous process" is created, Emacs and the Lisp
985 program both continue running immediately. The process may thereafter
986 run in parallel with Emacs, and the two may communicate with each other
987 using the functions described in following sections. Here we describe
988 how to create an asynchronous process with `start-process'.
990 - Function: start-process name buffer-or-name program &rest args
991 This function creates a new asynchronous subprocess and starts the
992 program PROGRAM running in it. It returns a process object that
993 stands for the new subprocess in Lisp. The argument NAME
994 specifies the name for the process object; if a process with this
995 name already exists, then NAME is modified (by adding `<1>', etc.)
996 to be unique. The buffer BUFFER-OR-NAME is the buffer to
997 associate with the process.
999 The remaining arguments, ARGS, are strings that specify command
1000 line arguments for the program.
1002 In the example below, the first process is started and runs
1003 (rather, sleeps) for 100 seconds. Meanwhile, the second process
1004 is started, and given the name `my-process<1>' for the sake of
1005 uniqueness. It inserts the directory listing at the end of the
1006 buffer `foo', before the first process finishes. Then it
1007 finishes, and a message to that effect is inserted in the buffer.
1008 Much later, the first process finishes, and another message is
1009 inserted in the buffer for it.
1011 (start-process "my-process" "foo" "sleep" "100")
1012 => #<process my-process>
1014 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
1015 => #<process my-process<1>>
1017 ---------- Buffer: foo ----------
1019 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
1020 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
1022 Process my-process<1> finished
1024 Process my-process finished
1025 ---------- Buffer: foo ----------
1027 - Function: start-process-shell-command name buffer-or-name command
1029 This function is like `start-process' except that it uses a shell
1030 to execute the specified command. The argument COMMAND is a shell
1031 command name, and COMMAND-ARGS are the arguments for the shell
1034 - Variable: process-connection-type
1035 This variable controls the type of device used to communicate with
1036 asynchronous subprocesses. If it is non-`nil', then PTYs are
1037 used, when available. Otherwise, pipes are used.
1039 PTYs are usually preferable for processes visible to the user, as
1040 in Shell mode, because they allow job control (`C-c', `C-z', etc.)
1041 to work between the process and its children whereas pipes do not.
1042 For subprocesses used for internal purposes by programs, it is
1043 often better to use a pipe, because they are more efficient. In
1044 addition, the total number of PTYs is limited on many systems and
1045 it is good not to waste them. A rule of thumb is to use ptys for
1046 processes the user interacts with directly, and pipes for
1047 processes that are hidden from the user.
1049 The value `process-connection-type' is used when `start-process'
1050 is called. So you can specify how to communicate with one
1051 subprocess by binding the variable around the call to
1054 (let ((process-connection-type nil)) ; Use a pipe.
1055 (start-process ...))
1057 To determine whether a given subprocess actually got a pipe or a
1058 PTY, use the function `process-tty-name' (*note Process
1061 Lisp functions that manipulate processes usually accept a PROCESS
1062 argument. Besides using an actual process object for this argument, you
1063 can use a process name, a buffer object, the name of a buffer, or
1064 `nil'. Specifying a buffer or buffer name for the PROCESS argument
1065 means use the process associated with the buffer (or the most recent
1066 one, if there is more than one). `nil' means use the process
1067 associated with the current buffer. *Note Process Information::.
1068 *Note Process Buffers::.
1071 File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
1076 "Deleting a process" disconnects XEmacs immediately from the
1077 subprocess, and removes it from the list of active processes. It sends
1078 a signal to the subprocess to make the subprocess terminate, but this is
1079 not guaranteed to happen immediately. The process object itself
1080 continues to exist as long as other Lisp objects point to it.
1082 You can delete a process explicitly at any time. Processes are
1083 deleted automatically after they terminate, but not necessarily right
1084 away. If you delete a terminated process explicitly before it is
1085 deleted automatically, no harm results.
1087 - Variable: delete-exited-processes
1088 This variable controls automatic deletion of processes that have
1089 terminated (due to calling `exit' or to a signal). If it is
1090 `nil', then they continue to exist until the user runs
1091 `list-processes'. Otherwise, they are deleted immediately after
1094 - Function: delete-process name
1095 This function deletes the process associated with NAME, killing it
1096 with a `SIGHUP' signal. The argument NAME may be a process, the
1097 name of a process, a buffer, or the name of a buffer.
1099 (delete-process "*shell*")
1102 - Function: process-kill-without-query process &optional
1104 This function declares that XEmacs need not query the user if
1105 PROCESS is still running when XEmacs is exited. The process will
1106 be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
1107 _will_ query the user (this is the default). The return value is
1108 `t' if a query was formerly required, and `nil' otherwise.
1110 (process-kill-without-query (get-process "shell"))
1114 File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
1119 Several functions return information about processes.
1120 `list-processes' is provided for interactive use.
1122 - Command: list-processes
1123 This command displays a listing of all living processes. In
1124 addition, it finally deletes any process whose status was `Exited'
1125 or `Signaled'. It returns `nil'.
1127 - Function: process-list
1128 This function returns a list of all processes that have not been
1132 => (#<process display-time> #<process shell>)
1134 - Function: get-process process-name
1135 This function returns the process named PROCESS-NAME. If
1136 PROCESS-NAME is a string and there is no process with that name,
1137 the value is `nil'. If PROCESS-NAME is actually a process, it is
1138 returned as given. (That is not very useful, so the argument is
1139 usually a name.) For example:
1141 (get-process "shell")
1144 - Function: process-command process
1145 This function returns the command that was executed to start
1146 PROCESS. This is a list of strings, the first string being the
1147 program executed and the rest of the strings being the arguments
1148 that were given to the program.
1150 (process-command (get-process "shell"))
1151 => ("/bin/csh" "-i")
1153 - Function: process-id process
1154 This function returns the PID of PROCESS. This is an integer that
1155 distinguishes the process PROCESS from all other processes running
1156 on the same computer at the current time. The PID of a process is
1157 chosen by the operating system kernel when the process is started
1158 and remains constant as long as the process exists.
1160 - Function: process-name process
1161 This function returns the name of PROCESS.
1163 - Function: process-status process
1164 This function returns the status of PROCESS as a symbol. The
1165 argument PROCESS must be a process, a buffer, a process name
1166 (string) or a buffer name (string).
1168 The possible values for an actual subprocess are:
1171 for a process that is running.
1174 for a process that is stopped but continuable.
1177 for a process that has exited.
1180 for a process that has received a fatal signal.
1183 for a network connection that is open.
1186 for a network connection that is closed. Once a connection
1187 is closed, you cannot reopen it, though you might be able to
1188 open a new connection to the same place.
1191 if PROCESS does not identify an existing process.
1193 (process-status "shell")
1195 (process-status (get-buffer "*shell*"))
1202 For a network connection, `process-status' returns one of the
1203 symbols `open' or `closed'. The latter means that the other side
1204 closed the connection, or XEmacs did `delete-process'.
1206 In earlier Emacs versions (prior to version 19), the status of a
1207 network connection was `run' if open, and `exit' if closed.
1209 - Function: process-kill-without-query-p process
1210 This function returns whether PROCESS will be killed without
1211 querying the user, if it is running when XEmacs is exited. The
1212 default value is `nil'.
1214 - Function: process-exit-status process
1215 This function returns the exit status of PROCESS or the signal
1216 number that killed it. (Use the result of `process-status' to
1217 determine which of those it is.) If PROCESS has not yet
1218 terminated, the value is 0.
1220 - Function: process-tty-name process
1221 This function returns the terminal name that PROCESS is using for
1222 its communication with Emacs--or `nil' if it is using pipes
1223 instead of a terminal (see `process-connection-type' in *Note
1224 Asynchronous Processes::).