X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-39;h=892739dad38de01a9103669ab1f004b20b4a24cd;hb=cde762e8ef3de99f205189eb40df327d59ba05e5;hp=b4f7bd5f35ec41ecd172302dbec60656f5dfd9bf;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-39 b/info/lispref.info-39 index b4f7bd5..892739d 100644 --- a/info/lispref.info-39 +++ b/info/lispref.info-39 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 3.12s from +This is ../info/lispref.info, produced by makeinfo version 4.0 from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,1269 +50,1176 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top - -Operating System Interface -************************** - - This chapter is about starting and getting out of Emacs, access to -values in the operating system environment, and terminal input, output, -and flow control. - - *Note Building XEmacs::, for related information. See also *Note -Display::, for additional operating system status information -pertaining to the terminal and the screen. - -* Menu: - -* Starting Up:: Customizing XEmacs start-up processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to a string, or - to calendrical data (or vice versa). -* Timers:: Setting a timer to call a function at a certain time. -* Terminal Input:: Recording terminal input for debugging. -* Terminal Output:: Recording terminal output for debugging. -* Flow Control:: How to turn output flow control on or off. -* Batch Mode:: Running XEmacs without terminal interaction. - - -File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface - -Starting Up XEmacs -================== - - This section describes what XEmacs does when it is started, and how -you can customize these actions. - -* Menu: - -* Start-up Summary:: Sequence of actions XEmacs performs at start-up. -* Init File:: Details on reading the init file (`.emacs'). -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command Line Arguments:: How command line arguments are processed, - and how you can customize them. +File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables + +Active Display Table +-------------------- + + The active display table is controlled by the variable +`current-display-table'. This is a specifier, which means that you can +specify separate values for it in individual buffers, windows, frames, +and devices, as well as a global value. It also means that you cannot +set this variable using `setq'; use `set-specifier' instead. *Note +Specifiers::. (FSF Emacs uses `window-display-table', +`buffer-display-table', `standard-display-table', etc. to control the +display table. However, specifiers are a cleaner and more powerful way +of doing the same thing. FSF Emacs also uses a different format for +the contents of a display table, using additional indirection to a +"glyph table" and such. Note that "glyph" has a different meaning in +XEmacs.) + + - Variable: current-display-table + The display table currently in use. This is a specifier. + + Display tables are used to control how characters are displayed. + Each time that redisplay processes a character, it is looked up in + all the display tables that apply (obtained by calling + `specifier-instance' on `current-display-table' and any overriding + display tables specified in currently active faces). The first + entry found that matches the character determines how the + character is displayed. If there is no matching entry, the + default display method is used. (Non-control characters are + displayed as themselves and control characters are displayed + according to the buffer-local variable `ctl-arrow'. Control + characters are further affected by `control-arrow-glyph' and + `octal-escape-glyph'.) + + Each instantiator in this specifier and the display-table + specifiers in faces is a display table or a list of such tables. + If a list, each table will be searched in turn for an entry + matching a particular character. Each display table is one of + + * A vector, specifying values for characters starting at 0. + + * A char table, either of type `char' or `generic'. + + * A range table. + + Each entry in a display table should be one of + + * nil (this entry is ignored and the search continues). + + * A character (use this character; if it happens to be the same + as the original character, default processing happens, + otherwise redisplay attempts to display this character + directly; #### At some point recursive display-table lookup + will be implemented). + + * A string (display each character in the string directly; #### + At some point recursive display-table lookup will be + implemented). + + * A glyph (display the glyph; #### At some point recursive + display-table lookup will be implemented when a string glyph + is being processed). + + * A cons of the form (format "STRING") where STRING is a + printf-like spec used to process the character. #### + Unfortunately no formatting directives other than %% are + implemented. + + * A vector (each element of the vector is processed recursively; + in such a case, nil elements in the vector are simply + ignored). + + #### At some point in the near future, display tables are + likely to be expanded to include other features, such as + referencing characters in particular fonts and allowing the + character search to continue all the way up the chain of + specifier instantiators. These features are necessary to + properly display Unicode characters. + + Individual faces can also specify an overriding display table; this +is set using `set-face-display-table'. *Note Faces::. + + If no display table can be determined for a particular window, then +XEmacs uses the usual display conventions. *Note Usual Display::.  -File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up - -Summary: Sequence of Actions at Start Up ----------------------------------------- - - The order of operations performed (in `startup.el') by XEmacs when -it is started up is as follows: +File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables - 1. It loads the initialization library for the window system, if you - are using a window system. This library's name is - `term/WINDOWSYSTEM-win.el'. +Character Descriptors +--------------------- - 2. It processes the initial options. (Some of them are handled even - earlier than this.) + Each element of the display-table vector describes how to display a +particular character and is called a "character descriptor". A +character descriptor can be: - 3. It initializes the X window frame and faces, if appropriate. +a string + Display this particular string wherever the character is to be + displayed. - 4. It runs the normal hook `before-init-hook'. +a glyph + Display this particular glyph wherever the character is to be + displayed. - 5. It loads the library `site-start', unless the option - `-no-site-file' was specified. The library's file name is usually - `site-start.el'. +a vector + The vector may contain strings and/or glyphs. Display the + elements of the vector one after another wherever the character is + to be displayed. - 6. It loads the file `~/.emacs' unless `-q' was specified on the - command line. (This is not done in `-batch' mode.) The `-u' - option can specify the user name whose home directory should be - used instead of `~'. +`nil' + Display according to the standard interpretation (*note Usual + Display::). - 7. It loads the library `default' unless `inhibit-default-init' is - non-`nil'. (This is not done in `-batch' mode or if `-q' was - specified on the command line.) The library's file name is - usually `default.el'. - - 8. It runs the normal hook `after-init-hook'. - - 9. It sets the major mode according to `initial-major-mode', provided - the buffer `*scratch*' is still current and still in Fundamental - mode. - - 10. It loads the terminal-specific Lisp file, if any, except when in - batch mode or using a window system. + +File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display - 11. It displays the initial echo area message, unless you have - suppressed that with `inhibit-startup-echo-area-message'. +Beeping +======= - 12. It processes the action arguments from the command line. + You can make XEmacs ring a bell, play a sound, or blink the screen to +attract the user's attention. Be conservative about how often you do +this; frequent bells can become irritating. Also be careful not to use +beeping alone when signaling an error is appropriate. (*Note Errors::.) - 13. It runs `term-setup-hook'. + - Function: ding &optional dont-terminate sound device + This function beeps, or flashes the screen (see `visible-bell' + below). It also terminates any keyboard macro currently executing + unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it + should be a symbol specifying which sound to make. This sound + will be played if `visible-bell' is `nil'. (This only works if + sound support was compiled into the executable and you are running + on the console of a Sun SparcStation, SGI, HP9000s700, or Linux + PC. Otherwise you just get a beep.) The optional third argument + specifies what device to make the sound on, and defaults to the + selected device. - 14. It calls `frame-notice-user-settings', which modifies the - parameters of the selected frame according to whatever the init - files specify. + - Function: beep &optional dont-terminate sound device + This is a synonym for `ding'. - 15. It runs `window-setup-hook'. *Note Terminal-Specific::. + - User Option: visible-bell + This variable determines whether XEmacs should flash the screen to + represent a bell. Non-`nil' means yes, `nil' means no. On TTY + devices, this is effective only if the Termcap entry for the + terminal type has the visible bell flag (`vb') set. - 16. It displays copyleft, nonwarranty, and basic use information, - provided there were no remaining command line arguments (a few - steps above) and the value of `inhibit-startup-message' is `nil'. + - Variable: sound-alist + This variable holds an alist associating names with sounds. When + `beep' or `ding' is called with one of the name symbols, the + associated sound will be generated instead of the standard beep. - - User Option: inhibit-startup-message - This variable inhibits the initial startup messages (the - nonwarranty, etc.). If it is non-`nil', then the messages are not - printed. + Each element of `sound-alist' is a list describing a sound. The + first element of the list is the name of the sound being defined. + Subsequent elements of the list are alternating keyword/value + pairs: - This variable exists so you can set it in your personal init file, - once you are familiar with the contents of the startup message. - Do not set this variable in the init file of a new user, or in a - way that affects more than one user, because that would prevent - new users from receiving the information they are supposed to see. + `sound' + A string of raw sound data, or the name of another sound to + play. The symbol `t' here means use the default X beep. - - User Option: inhibit-startup-echo-area-message - This variable controls the display of the startup echo area - message. You can suppress the startup echo area message by adding - text with this form to your `.emacs' file: + `volume' + An integer from 0-100, defaulting to `bell-volume'. - (setq inhibit-startup-echo-area-message - "YOUR-LOGIN-NAME") + `pitch' + If using the default X beep, the pitch (Hz) to generate. - Simply setting `inhibit-startup-echo-area-message' to your login - name is not sufficient to inhibit the message; Emacs explicitly - checks whether `.emacs' contains an expression as shown above. - Your login name must appear in the expression as a Lisp string - constant. + `duration' + If using the default X beep, the duration (milliseconds). - This way, you can easily inhibit the message for yourself if you - wish, but thoughtless copying of your `.emacs' file will not - inhibit the message for someone else. + For compatibility, elements of `sound-alist' may also be: - -File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up - -The Init File: `.emacs' ------------------------ - - When you start XEmacs, it normally attempts to load the file -`.emacs' from your home directory. This file, if it exists, must -contain Lisp code. It is called your "init file". The command line -switches `-q' and `-u' affect the use of the init file; `-q' says not -to load an init file, and `-u' says to load a specified user's init -file instead of yours. *Note Entering XEmacs: (xemacs)Entering XEmacs. - - A site may have a "default init file", which is the library named -`default.el'. XEmacs finds the `default.el' file through the standard -search path for libraries (*note How Programs Do Loading::). The -XEmacs distribution does not come with this file; sites may provide one -for local customizations. If the default init file exists, it is -loaded whenever you start Emacs, except in batch mode or if `-q' is -specified. But your own personal init file, if any, is loaded first; if -it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does -not subsequently load the `default.el' file. - - Another file for site-customization is `site-start.el'. Emacs loads -this _before_ the user's init file. You can inhibit the loading of -this file with the option `-no-site-file'. - - - Variable: site-run-file - This variable specifies the site-customization file to load before - the user's init file. Its normal value is `"site-start"'. - - If there is a great deal of code in your `.emacs' file, you should -move it into another file named `SOMETHING.el', byte-compile it (*note -Byte Compilation::), and make your `.emacs' file load the other file -using `load' (*note Loading::). - - *Note Init File Examples: (xemacs)Init File Examples, for examples -of how to make various commonly desired customizations in your `.emacs' -file. - - - User Option: inhibit-default-init - This variable prevents XEmacs from loading the default - initialization library file for your session of XEmacs. If its - value is non-`nil', then the default library is not loaded. The - default value is `nil'. + * `( sound-name . )' - - Variable: before-init-hook - - Variable: after-init-hook - These two normal hooks are run just before, and just after, - loading of the user's init file, `default.el', and/or - `site-start.el'. + * `( sound-name )' - -File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up - -Terminal-Specific Initialization --------------------------------- - - Each terminal type can have its own Lisp library that XEmacs loads -when run on that type of terminal. For a terminal type named TERMTYPE, -the library is called `term/TERMTYPE'. XEmacs finds the file by -searching the `load-path' directories as it does for other files, and -trying the `.elc' and `.el' suffixes. Normally, terminal-specific Lisp -library is located in `emacs/lisp/term', a subdirectory of the -`emacs/lisp' directory in which most XEmacs Lisp libraries are kept. - - The library's name is constructed by concatenating the value of the -variable `term-file-prefix' and the terminal type. Normally, -`term-file-prefix' has the value `"term/"'; changing this is not -recommended. - - The usual function of a terminal-specific library is to enable -special keys to send sequences that XEmacs can recognize. It may also -need to set or add to `function-key-map' if the Termcap entry does not -specify all the terminal's function keys. *Note Terminal Input::. - - When the name of the terminal type contains a hyphen, only the part -of the name before the first hyphen is significant in choosing the -library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use -the `term/aaa' library. If necessary, the library can evaluate -`(getenv "TERM")' to find the full name of the terminal type. - - Your `.emacs' file can prevent the loading of the terminal-specific -library by setting the variable `term-file-prefix' to `nil'. This -feature is useful when experimenting with your own peculiar -customizations. - - You can also arrange to override some of the actions of the -terminal-specific library by setting the variable `term-setup-hook'. -This is a normal hook which XEmacs runs using `run-hooks' at the end of -XEmacs initialization, after loading both your `.emacs' file and any -terminal-specific libraries. You can use this variable to define -initializations for terminals that do not have their own libraries. -*Note Hooks::. - - - Variable: term-file-prefix - If the `term-file-prefix' variable is non-`nil', XEmacs loads a - terminal-specific initialization file as follows: - - (load (concat term-file-prefix (getenv "TERM"))) - - You may set the `term-file-prefix' variable to `nil' in your - `.emacs' file if you do not wish to load the - terminal-initialization file. To do this, put the following in - your `.emacs' file: `(setq term-file-prefix nil)'. - - - Variable: term-setup-hook - This variable is a normal hook that XEmacs runs after loading your - `.emacs' file, the default initialization file (if any) and the - terminal-specific Lisp file. - - You can use `term-setup-hook' to override the definitions made by a - terminal-specific file. - - - Variable: window-setup-hook - This variable is a normal hook which XEmacs runs after loading your - `.emacs' file and the default initialization file (if any), after - loading terminal-specific Lisp code, and after running the hook - `term-setup-hook'. + You should probably add things to this list by calling the function + `load-sound-file'. - -File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up + Caveats: -Command Line Arguments ----------------------- + - You can only play audio data if running on the console screen + of a Sun SparcStation, SGI, or HP9000s700. - You can use command line arguments to request various actions when -you start XEmacs. Since you do not need to start XEmacs more than once -per day, and will often leave your XEmacs session running longer than -that, command line arguments are hardly ever used. As a practical -matter, it is best to avoid making the habit of using them, since this -habit would encourage you to kill and restart XEmacs unnecessarily -often. These options exist for two reasons: to be compatible with -other editors (for invocation by other programs) and to enable shell -scripts to run specific Lisp programs. + - The pitch, duration, and volume options are available + everywhere, but many X servers ignore the `pitch' option. - This section describes how Emacs processes command line arguments, -and how you can customize them. + The following beep-types are used by XEmacs itself: - - Function: command-line - This function parses the command line that XEmacs was called with, - processes it, loads the user's `.emacs' file and displays the - startup messages. + `auto-save-error' + when an auto-save does not succeed - - Variable: command-line-processed - The value of this variable is `t' once the command line has been - processed. + `command-error' + when the XEmacs command loop catches an error - If you redump XEmacs by calling `dump-emacs', you may wish to set - this variable to `nil' first in order to cause the new dumped - XEmacs to process its new command line arguments. + `undefined-key' + when you type a key that is undefined - - Variable: command-switch-alist - The value of this variable is an alist of user-defined command-line - options and associated handler functions. This variable exists so - you can add elements to it. + `undefined-click' + when you use an undefined mouse-click combination - A "command line option" is an argument on the command line of the - form: + `no-completion' + during completing-read - -OPTION + `y-or-n-p' + when you type something other than 'y' or 'n' - The elements of the `command-switch-alist' look like this: + `yes-or-no-p' + when you type something other than 'yes' or 'no' - (OPTION . HANDLER-FUNCTION) + `default' + used when nothing else is appropriate. - The HANDLER-FUNCTION is called to handle OPTION and receives the - option name as its sole argument. + Other lisp packages may use other beep types, but these are the + ones that the C kernel of XEmacs uses. - In some cases, the option is followed in the command line by an - argument. In these cases, the HANDLER-FUNCTION can find all the - remaining command-line arguments in the variable - `command-line-args-left'. (The entire list of command-line - arguments is in `command-line-args'.) + - User Option: bell-volume + This variable specifies the default volume for sounds, from 0 to + 100. - The command line arguments are parsed by the `command-line-1' - function in the `startup.el' file. See also *Note Command Line - Switches and Arguments: (xemacs)Command Switches. + - Command: load-default-sounds + This function loads and installs some sound files as beep-types. - - Variable: command-line-args - The value of this variable is the list of command line arguments - passed to XEmacs. + - Command: load-sound-file filename sound-name &optional volume + This function reads in an audio file and adds it to `sound-alist'. + The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME + should be a symbol, specifying the name of the sound. If VOLUME + is specified, the sound will be played at that volume; otherwise, + the value of BELL-VOLUME will be used. - - Variable: command-line-functions - This variable's value is a list of functions for handling an - unrecognized command-line argument. Each time the next argument - to be processed has no special meaning, the functions in this list - are called, in order of appearance, until one of them returns a - non-`nil' value. + - Function: play-sound sound &optional volume device + This function plays sound SOUND, which should be a symbol + mentioned in `sound-alist'. If VOLUME is specified, it overrides + the value (if any) specified in `sound-alist'. DEVICE specifies + the device to play the sound on, and defaults to the selected + device. - These functions are called with no arguments. They can access the - command-line argument under consideration through the variable - `argi'. The remaining arguments (not including the current one) - are in the variable `command-line-args-left'. - - When a function recognizes and processes the argument in `argi', it - should return a non-`nil' value to say it has dealt with that - argument. If it has also dealt with some of the following - arguments, it can indicate that by deleting them from - `command-line-args-left'. - - If all of these functions return `nil', then the argument is used - as a file name to visit. + - Command: play-sound-file file &optional volume device + This function plays the named sound file at volume VOLUME, which + defaults to `bell-volume'. DEVICE specifies the device to play + the sound on, and defaults to the selected device.  -File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface +File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top -Getting out of XEmacs -===================== +Hash Tables +*********** - There are two ways to get out of XEmacs: you can kill the XEmacs job, -which exits permanently, or you can suspend it, which permits you to -reenter the XEmacs process later. As a practical matter, you seldom -kill XEmacs--only when you are about to log out. Suspending is much -more common. + - Function: hash-table-p object + This function returns `t' if OBJECT is a hash table, else `nil'. * Menu: -* Killing XEmacs:: Exiting XEmacs irreversibly. -* Suspending XEmacs:: Exiting XEmacs reversibly. +* Introduction to Hash Tables:: Hash tables are fast data structures for + implementing simple tables (i.e. finite + mappings from keys to values). +* Working With Hash Tables:: Hash table functions. +* Weak Hash Tables:: Hash tables with special garbage-collection + behavior.  -File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out +File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables + +Introduction to Hash Tables +=========================== + + A "hash table" is a data structure that provides mappings from +arbitrary Lisp objects called "keys" to other arbitrary Lisp objects +called "values". A key/value pair is sometimes called an "entry" in +the hash table. There are many ways other than hash tables of +implementing the same sort of mapping, e.g. association lists (*note +Association Lists::) and property lists (*note Property Lists::), but +hash tables provide much faster lookup when there are many entries in +the mapping. Hash tables are an implementation of the abstract data +type "dictionary", also known as "associative array". + + Internally, hash tables are hashed using the "linear probing" hash +table implementation method. This method hashes each key to a +particular spot in the hash table, and then scans forward sequentially +until a blank entry is found. To look up a key, hash to the appropriate +spot, then search forward for the key until either a key is found or a +blank entry stops the search. This method is used in preference to +double hashing because of changes in recent hardware. The penalty for +non-sequential access to memory has been increasing, and this +compensates for the problem of clustering that linear probing entails. + + When hash tables are created, the user may (but is not required to) +specify initial properties that influence performance. + + Use the `:size' parameter to specify the number of entries that are +likely to be stored in the hash table, to avoid the overhead of resizing +the table. But if the pre-allocated space for the entries is never +used, it is simply wasted and makes XEmacs slower. Excess unused hash +table entries exact a small continuous performance penalty, since they +must be scanned at every garbage collection. If the number of entries +in the hash table is unknown, simply avoid using the `:size' keyword. + + Use the `:rehash-size' and `:rehash-threshold' keywords to adjust +the algorithm for deciding when to rehash the hash table. For +temporary hash tables that are going to be very heavily used, use a +small rehash threshold, for example, 0.4 and a large rehash size, for +example 2.0. For permanent hash tables that will be infrequently used, +specify a large rehash threshold, for example 0.8. + + Hash tables can also be created by the lisp reader using structure +syntax, for example: + #s(hash-table size 20 data (foo 1 bar 2)) + + The structure syntax accepts the same keywords as `make-hash-table' +(without the `:' character), as well as the additional keyword `data', +which specifies the initial hash table contents. + + - Function: make-hash-table &key `test' `size' `rehash-size' + `rehash-threshold' `weakness' + This function returns a new empty hash table object. + + Keyword `:test' can be `eq', `eql' (default) or `equal'. + Comparison between keys is done using this function. If speed is + important, consider using `eq'. When storing strings in the hash + table, you will likely need to use `equal'. + + Keyword `:size' specifies the number of keys likely to be inserted. + This number of entries can be inserted without enlarging the hash + table. + + Keyword `:rehash-size' must be a float greater than 1.0, and + specifies the factor by which to increase the size of the hash + table when enlarging. + + Keyword `:rehash-threshold' must be a float between 0.0 and 1.0, + and specifies the load factor of the hash table which triggers + enlarging. + + Non-standard keyword `:weakness' can be `nil' (default), `t', + `key-and-value', `key', `value' or `key-or-value'. `t' is an + alias for `key-and-value'. + + A key-and-value-weak hash table, also known as a fully-weak or + simply as a weak hash table, is one whose pointers do not count as + GC referents: for any key-value pair in the hash table, if the only + remaining pointer to either the key or the value is in a weak hash + table, then the pair will be removed from the hash table, and the + key and value collected. A non-weak hash table (or any other + pointer) would prevent the object from being collected. + + A key-weak hash table is similar to a fully-weak hash table except + that a key-value pair will be removed only if the key remains + unmarked outside of weak hash tables. The pair will remain in the + hash table if the key is pointed to by something other than a weak + hash table, even if the value is not. + + A value-weak hash table is similar to a fully-weak hash table + except that a key-value pair will be removed only if the value + remains unmarked outside of weak hash tables. The pair will + remain in the hash table if the value is pointed to by something + other than a weak hash table, even if the key is not. + + A key-or-value-weak hash table is similar to a fully-weak hash + table except that a key-value pair will be removed only if the + value and the key remain unmarked outside of weak hash tables. + The pair will remain in the hash table if the value or key are + pointed to by something other than a weak hash table, even if the + other is not. + + - Function: copy-hash-table hash-table + This function returns a new hash table which contains the same + keys and values as HASH-TABLE. The keys and values will not + themselves be copied. + + - Function: hash-table-count hash-table + This function returns the number of entries in HASH-TABLE. + + - Function: hash-table-test hash-table + This function returns the test function of HASH-TABLE. This can + be one of `eq', `eql' or `equal'. + + - Function: hash-table-size hash-table + This function returns the current number of slots in HASH-TABLE, + whether occupied or not. + + - Function: hash-table-rehash-size hash-table + This function returns the current rehash size of HASH-TABLE. This + is a float greater than 1.0; the factor by which HASH-TABLE is + enlarged when the rehash threshold is exceeded. + + - Function: hash-table-rehash-threshold hash-table + This function returns the current rehash threshold of HASH-TABLE. + This is a float between 0.0 and 1.0; the maximum "load factor" of + HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing. + + - Function: hash-table-weakness hash-table + This function returns the weakness of HASH-TABLE. This can be one + of `nil', `t', `key' or `value'. -Killing XEmacs --------------- + +File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables - Killing XEmacs means ending the execution of the XEmacs process. The -parent process normally resumes control. The low-level primitive for -killing XEmacs is `kill-emacs'. +Working With Hash Tables +======================== - - Function: kill-emacs &optional exit-data - This function exits the XEmacs process and kills it. + - Function: puthash key value hash-table + This function hashes KEY to VALUE in HASH-TABLE. - If EXIT-DATA is an integer, then it is used as the exit status of - the XEmacs process. (This is useful primarily in batch operation; - see *Note Batch Mode::.) + - Function: gethash key hash-table &optional default + This function finds the hash value for KEY in HASH-TABLE. If + there is no entry for KEY in HASH-TABLE, DEFAULT is returned + (which in turn defaults to `nil'). - If EXIT-DATA is a string, its contents are stuffed into the - terminal input buffer so that the shell (or whatever program next - reads input) can read them. + - Function: remhash key hash-table + This function removes the entry for KEY from HASH-TABLE. Does + nothing if there is no entry for KEY in HASH-TABLE. - All the information in the XEmacs process, aside from files that have -been saved, is lost when the XEmacs is killed. Because killing XEmacs -inadvertently can lose a lot of work, XEmacs queries for confirmation -before actually terminating if you have buffers that need saving or -subprocesses that are running. This is done in the function -`save-buffers-kill-emacs'. + - Function: clrhash hash-table + This function removes all entries from HASH-TABLE, leaving it + empty. - - Variable: kill-emacs-query-functions - After asking the standard questions, `save-buffers-kill-emacs' - calls the functions in the list `kill-buffer-query-functions', in - order of appearance, with no arguments. These functions can ask - for additional confirmation from the user. If any of them returns - non-`nil', XEmacs is not killed. + - Function: maphash function hash-table + This function maps FUNCTION over entries in HASH-TABLE, calling it + with two args, each key and value in the hash table. - - Variable: kill-emacs-hook - This variable is a normal hook; once `save-buffers-kill-emacs' is - finished with all file saving and confirmation, it runs the - functions in this hook. + FUNCTION may not modify HASH-TABLE, with the one exception that + FUNCTION may remhash or puthash the entry currently being + processed by FUNCTION.  -File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out - -Suspending XEmacs ------------------ - - "Suspending XEmacs" means stopping XEmacs temporarily and returning -control to its superior process, which is usually the shell. This -allows you to resume editing later in the same XEmacs process, with the -same buffers, the same kill ring, the same undo history, and so on. To -resume XEmacs, use the appropriate command in the parent shell--most -likely `fg'. - - Some operating systems do not support suspension of jobs; on these -systems, "suspension" actually creates a new shell temporarily as a -subprocess of XEmacs. Then you would exit the shell to return to -XEmacs. - - Suspension is not useful with window systems such as X, because the -XEmacs job may not have a parent that can resume it again, and in any -case you can give input to some other job such as a shell merely by -moving to a different window. Therefore, suspending is not allowed -when XEmacs is an X client. - - - Function: suspend-emacs string - This function stops XEmacs and returns control to the superior - process. If and when the superior process resumes XEmacs, - `suspend-emacs' returns `nil' to its caller in Lisp. - - If STRING is non-`nil', its characters are sent to be read as - terminal input by XEmacs's superior shell. The characters in - STRING are not echoed by the superior shell; only the results - appear. - - Before suspending, `suspend-emacs' runs the normal hook - `suspend-hook'. In Emacs version 18, `suspend-hook' was not a - normal hook; its value was a single function, and if its value was - non-`nil', then `suspend-emacs' returned immediately without - actually suspending anything. - - After the user resumes XEmacs, `suspend-emacs' runs the normal hook - `suspend-resume-hook'. *Note Hooks::. - - The next redisplay after resumption will redraw the entire screen, - unless the variable `no-redraw-on-reenter' is non-`nil' (*note - Refresh Screen::). - - In the following example, note that `pwd' is not echoed after - XEmacs is suspended. But it is read and executed by the shell. - - (suspend-emacs) - => nil - - (add-hook 'suspend-hook - (function (lambda () - (or (y-or-n-p - "Really suspend? ") - (error "Suspend cancelled"))))) - => (lambda nil - (or (y-or-n-p "Really suspend? ") - (error "Suspend cancelled"))) - (add-hook 'suspend-resume-hook - (function (lambda () (message "Resumed!")))) - => (lambda nil (message "Resumed!")) - (suspend-emacs "pwd") - => nil - ---------- Buffer: Minibuffer ---------- - Really suspend? y - ---------- Buffer: Minibuffer ---------- - - ---------- Parent Shell ---------- - lewis@slug[23] % /user/lewis/manual - lewis@slug[24] % fg - - ---------- Echo Area ---------- - Resumed! - - - Variable: suspend-hook - This variable is a normal hook run before suspending. - - - Variable: suspend-resume-hook - This variable is a normal hook run after suspending. +File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables + +Weak Hash Tables +================ + + A "weak hash table" is a special variety of hash table whose +elements do not count as GC referents. For any key-value pair in such a +hash table, if either the key or value (or in some cases, if one +particular one of the two) has no references to it outside of weak hash +tables (and similar structures such as weak lists), the pair will be +removed from the table, and the key and value collected. A non-weak +hash table (or any other pointer) would prevent the objects from being +collected. + + Weak hash tables are useful for keeping track of information in a +non-obtrusive way, for example to implement caching. If the cache +contains objects such as buffers, markers, image instances, etc. that +will eventually disappear and get garbage-collected, using a weak hash +table ensures that these objects are collected normally rather than +remaining around forever, long past their actual period of use. +(Otherwise, you'd have to explicitly map over the hash table every so +often and remove unnecessary elements.) + + There are four types of weak hash tables: + +key-and-value-weak hash tables + In these hash tables, also known as fully weak or simply as weak + hash tables, a pair disappears if either the key or the value is + unreferenced outside of the table. + +key-weak hash tables + In these hash tables, a pair disappears if the key is unreferenced + outside of the table, regardless of how the value is referenced. + +value-weak hash tables + In these hash tables, a pair disappears if the value is + unreferenced outside of the table, regardless of how the key is + referenced. + +key-or-value-weak hash tables + In these hash tables, a pair disappears if both the key and the + value are unreferenced outside of the table. + + Also see *Note Weak Lists::. + + Weak hash tables are created by specifying the `:weakness' keyword to +`make-hash-table'.  -File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface - -Operating System Environment -============================ - - XEmacs provides access to variables in the operating system -environment through various functions. These variables include the -name of the system, the user's UID, and so on. - - - Variable: system-type - The value of this variable is a symbol indicating the type of - operating system XEmacs is operating on. Here is a table of the - possible values: - - `aix-v3' - AIX. - - `berkeley-unix' - Berkeley BSD. - - `dgux' - Data General DGUX operating system. - - `gnu' - A GNU system using the GNU HURD and Mach. - - `hpux' - Hewlett-Packard HPUX operating system. - - `irix' - Silicon Graphics Irix system. - - `linux' - A GNU system using the Linux kernel. - - `ms-dos' - Microsoft MS-DOS "operating system." - - `next-mach' - NeXT Mach-based system. +File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top - `rtu' - Masscomp RTU, UCB universe. +Range Tables +************ - `unisoft-unix' - UniSoft UniPlus. + A range table is a table that efficiently associated values with +ranges of integers. - `usg-unix-v' - AT&T System V. + Note that range tables have a read syntax, like this: - `vax-vms' - VAX VMS. + #s(range-table data ((-3 2) foo (5 20) bar)) - `windows-nt' - Microsoft windows NT. + This maps integers in the range (-3, 2) to `foo' and integers in the +range (5, 20) to `bar'. - `xenix' - SCO Xenix 386. + - Function: range-table-p object + Return non-`nil' if OBJECT is a range table. - We do not wish to add new symbols to make finer distinctions - unless it is absolutely necessary! In fact, we hope to eliminate - some of these alternatives in the future. We recommend using - `system-configuration' to distinguish between different operating - systems. - - - Variable: system-configuration - This variable holds the three-part configuration name for the - hardware/software configuration of your system, as a string. The - convenient way to test parts of this string is with `string-match'. - - - Function: system-name - This function returns the name of the machine you are running on. - (system-name) - => "prep.ai.mit.edu" - - The symbol `system-name' is a variable as well as a function. In -fact, the function returns whatever value the variable `system-name' -currently holds. Thus, you can set the variable `system-name' in case -Emacs is confused about the name of your system. The variable is also -useful for constructing frame titles (*note Frame Titles::). - - - Variable: mail-host-address - If this variable is non-`nil', it is used instead of `system-name' - for purposes of generating email addresses. For example, it is - used when constructing the default value of `user-mail-address'. - *Note User Identification::. (Since this is done when XEmacs - starts up, the value actually used is the one saved when XEmacs - was dumped. *Note Building XEmacs::.) - - - Function: getenv var - This function returns the value of the environment variable VAR, - as a string. Within XEmacs, the environment variable values are - kept in the Lisp variable `process-environment'. - - (getenv "USER") - => "lewis" - - lewis@slug[10] % printenv - PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin - USER=lewis - TERM=ibmapa16 - SHELL=/bin/csh - HOME=/user/lewis - - - Command: setenv variable value - This command sets the value of the environment variable named - VARIABLE to VALUE. Both arguments should be strings. This - function works by modifying `process-environment'; binding that - variable with `let' is also reasonable practice. - - - Variable: process-environment - This variable is a list of strings, each describing one environment - variable. The functions `getenv' and `setenv' work by means of - this variable. - - process-environment - => ("l=/usr/stanford/lib/gnuemacs/lisp" - "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" - "USER=lewis" - "TERM=ibmapa16" - "SHELL=/bin/csh" - "HOME=/user/lewis") - - - Variable: path-separator - This variable holds a string which says which character separates - directories in a search path (as found in an environment - variable). Its value is `":"' for Unix and GNU systems, and `";"' - for MS-DOS and Windows NT. - - - Variable: invocation-name - This variable holds the program name under which Emacs was - invoked. The value is a string, and does not include a directory - name. - - - Variable: invocation-directory - This variable holds the directory from which the Emacs executable - was invoked, or perhaps `nil' if that directory cannot be - determined. - - - Variable: installation-directory - If non-`nil', this is a directory within which to look for the - `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs - can't find those directories in their standard installed - locations, but can find them in a directory related somehow to the - one containing the Emacs executable. - - - Function: load-average &optional use-floats - This function returns a list of the current 1-minute, 5-minute and - 15-minute load averages. The values are integers that are 100 - times the system load averages. (The load averages indicate the - number of processes trying to run.) - - When USE-FLOATS is non-`nil', floats will be returned instead of - integers. These floats are not multiplied by 100. - - (load-average) - => (169 158 164) - (load-average t) - => (1.69921875 1.58984375 1.640625) - - lewis@rocky[5] % uptime - 8:06pm up 16 day(s), 21:57, 40 users, - load average: 1.68, 1.59, 1.64 +* Menu: - If the 5-minute or 15-minute load averages are not available, - return a shortened list, containing only those averages which are - available. +* Introduction to Range Tables:: Range tables efficiently map ranges of + integers to values. +* Working With Range Tables:: Range table functions. - On some systems, this function may require special privileges to - run, or it may be unimplemented for the particular system type. - In that case, the function will signal an error. + +File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables - - Function: emacs-pid - This function returns the process ID of the Emacs process. +Introduction to Range Tables +============================ - - Function: setprv privilege-name &optional setp getprv - This function sets or resets a VMS privilege. (It does not exist - on Unix.) The first arg is the privilege name, as a string. The - second argument, SETP, is `t' or `nil', indicating whether the - privilege is to be turned on or off. Its default is `nil'. The - function returns `t' if successful, `nil' otherwise. + - Function: make-range-table + Make a new, empty range table. - If the third argument, GETPRV, is non-`nil', `setprv' does not - change the privilege, but returns `t' or `nil' indicating whether - the privilege is currently enabled. + - Function: copy-range-table range-table + This function returns a new range table which contains the same + values for the same ranges as RANGE-TABLE. The values will not + themselves be copied.  -File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface - -User Identification -=================== +File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables - - Variable: user-mail-address - This holds the nominal email address of the user who is using - Emacs. When Emacs starts up, it computes a default value that is - usually right, but users often set this themselves when the - default value is not right. +Working With Range Tables +========================= - - Function: user-login-name &optional uid - If you don't specify UID, this function returns the name under - which the user is logged in. If the environment variable `LOGNAME' - is set, that value is used. Otherwise, if the environment variable - `USER' is set, that value is used. Otherwise, the value is based - on the effective UID, not the real UID. + - Function: get-range-table pos range-table &optional default + This function finds value for position POS in RANGE-TABLE. If + there is no corresponding value, return DEFAULT (defaults to + `nil'). - If you specify UID, the value is the user name that corresponds to - UID (which should be an integer). + - Function: put-range-table start end value range-table + This function sets the value for range (START, END) to be VALUE in + RANGE-TABLE. - (user-login-name) - => "lewis" + - Function: remove-range-table start end range-table + This function removes the value for range (START, END) in + RANGE-TABLE. - - Function: user-real-login-name - This function returns the user name corresponding to Emacs's real - UID. This ignores the effective UID and ignores the environment - variables `LOGNAME' and `USER'. + - Function: clear-range-table range-table + This function flushes RANGE-TABLE. - - Variable: user-full-name - This variable holds the name of the user running this Emacs. It is - initialized at startup time from the value of `NAME' environment - variable. You can change the value of this variable to alter the - result of the `user-full-name' function. + - Function: map-range-table function range-table + This function maps FUNCTION over entries in RANGE-TABLE, calling + it with three args, the beginning and end of the range and the + corresponding value. - - Function: user-full-name &optional user - This function returns the full name of USER. If USER is `nil', it - defaults to the user running this Emacs. In that case, the value - of `user-full-name' variable, if non-`nil', will be used. - - If USER is specified explicitly, `user-full-name' variable is - ignored. - - (user-full-name) - => "Hrvoje Niksic" - (setq user-full-name "Hrvoje \"Niksa\" Niksic") - (user-full-name) - => "Hrvoje \"Niksa\" Niksic" - (user-full-name "hniksic") - => "Hrvoje Niksic" + +File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top - The symbols `user-login-name', `user-real-login-name' and -`user-full-name' are variables as well as functions. The functions -return the same values that the variables hold. These variables allow -you to "fake out" Emacs by telling the functions what to return. The -variables are also useful for constructing frame titles (*note Frame -Titles::). +Databases +********* - - Function: user-real-uid - This function returns the real UID of the user. + - Function: databasep object + This function returns non-`nil' if OBJECT is a database. - (user-real-uid) - => 19 +* Menu: - - Function: user-uid - This function returns the effective UID of the user. +* Connecting to a Database:: +* Working With a Database:: +* Other Database Functions:: - - Function: user-home-directory - This function returns the "`HOME'" directory of the user, and is - intended to replace occurrences of "`(getenv "HOME")'". Under - Unix systems, the following is done: + +File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases - 1. Return the value of "`(getenv "HOME")'", if set. +Connecting to a Database +======================== - 2. Return "/", as a fallback, but issue a warning. (Future - versions of XEmacs will also attempt to lookup the `HOME' - directory via `getpwent()', but this has not yet been - implemented.) + - Function: open-database file &optional type subtype access mode + This function opens database FILE, using database method TYPE and + SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS + can be any combination of `r' `w' and `+', for read, write, and + creation flags. - Under MS Windows, this is done: + TYPE can have the value `'dbm' or `'berkeley-db' to select the + type of database file to use. (Note: XEmacs may not support both + of these types.) - 1. Return the value of "`(getenv "HOME")'", if set. + For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be + `nil'. - 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are - both set, return the concatenation (the following description - uses MS Windows environment variable substitution syntax): - `%HOMEDRIVE%%HOMEDIR%'. + For a TYPE of `'berkeley-db', the following subtypes are + available: `'hash', `'btree', and `'recno'. See the manpages for + the Berkeley DB functions for more information about these types. - 3. Return "C:\", as a fallback, but issue a warning. + - Function: close-database database + This function closes database DATABASE. - -File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface - -Time of Day -=========== - - This section explains how to determine the current time and the time -zone. - - - Function: current-time-string &optional time-value - This function returns the current time and date as a - humanly-readable string. The format of the string is unvarying; - the number of characters used for each part is always the same, so - you can reliably use `substring' to extract pieces of it. It is - wise to count the characters from the beginning of the string - rather than from the end, as additional information may be added - at the end. - - The argument TIME-VALUE, if given, specifies a time to format - instead of the current time. The argument should be a list whose - first two elements are integers. Thus, you can use times obtained - from `current-time' (see below) and from `file-attributes' (*note - File Attributes::). - - (current-time-string) - => "Wed Oct 14 22:21:05 1987" - - - Function: current-time - This function returns the system's time value as a list of three - integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW - combine to give the number of seconds since 0:00 January 1, 1970, - which is HIGH * 2**16 + LOW. - - The third element, MICROSEC, gives the microseconds since the - start of the current second (or 0 for systems that return time - only on the resolution of a second). - - The first two elements can be compared with file time values such - as you get with the function `file-attributes'. *Note File - Attributes::. - - - Function: current-time-zone &optional time-value - This function returns a list describing the time zone that the - user is in. - - The value has the form `(OFFSET NAME)'. Here OFFSET is an integer - giving the number of seconds ahead of UTC (east of Greenwich). A - negative value means west of Greenwich. The second element, NAME - is a string giving the name of the time zone. Both elements - change when daylight savings time begins or ends; if the user has - specified a time zone that does not use a seasonal time - adjustment, then the value is constant through time. - - If the operating system doesn't supply all the information - necessary to compute the value, both elements of the list are + - Function: database-live-p object + This function returns `t' if OBJECT is an active database, else `nil'. - The argument TIME-VALUE, if given, specifies a time to analyze - instead of the current time. The argument should be a cons cell - containing two integers, or a list whose first two elements are - integers. Thus, you can use times obtained from `current-time' - (see above) and from `file-attributes' (*note File Attributes::). -  -File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface - -Time Conversion -=============== - - These functions convert time values (lists of two or three integers) -to strings or to calendrical information. There is also a function to -convert calendrical information to a time value. You can get time -values from the functions `current-time' (*note Time of Day::) and -`file-attributes' (*note File Attributes::). - - - Function: format-time-string format-string &optional time - This function converts TIME to a string according to - FORMAT-STRING. If TIME is omitted, it defaults to the current - time. The argument FORMAT-STRING may contain `%'-sequences which - say to substitute parts of the time. Here is a table of what the - `%'-sequences mean: - - `%a' - This stands for the abbreviated name of the day of week. - - `%A' - This stands for the full name of the day of week. - - `%b' - This stands for the abbreviated name of the month. - - `%B' - This stands for the full name of the month. - - `%c' - This is a synonym for `%x %X'. +File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases - `%C' - This has a locale-specific meaning. In the default locale - (named C), it is equivalent to `%A, %B %e, %Y'. +Working With a Database +======================= - `%d' - This stands for the day of month, zero-padded. + - Function: get-database key database &optional default + This function finds the value for KEY in DATABASE. If there is no + corresponding value, DEFAULT is returned (`nil' if DEFAULT is + omitted). - `%D' - This is a synonym for `%m/%d/%y'. + - Function: map-database function database + This function maps FUNCTION over entries in DATABASE, calling it + with two args, each key and value in the database. - `%e' - This stands for the day of month, blank-padded. + - Function: put-database key value database &optional replace + This function stores KEY and VALUE in DATABASE. If optional + fourth arg REPLACE is non-`nil', replace any existing entry in the + database. - `%h' - This is a synonym for `%b'. + - Function: remove-database key database + This function removes KEY from DATABASE. - `%H' - This stands for the hour (00-23). - - `%I' - This stands for the hour (00-12). - - `%j' - This stands for the day of the year (001-366). - - `%k' - This stands for the hour (0-23), blank padded. - - `%l' - This stands for the hour (1-12), blank padded. - - `%m' - This stands for the month (01-12). - - `%M' - This stands for the minute (00-59). - - `%n' - This stands for a newline. - - `%p' - This stands for `AM' or `PM', as appropriate. - - `%r' - This is a synonym for `%I:%M:%S %p'. + +File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases - `%R' - This is a synonym for `%H:%M'. +Other Database Functions +======================== - `%S' - This stands for the seconds (00-60). + - Function: database-file-name database + This function returns the filename associated with DATABASE. - `%t' - This stands for a tab character. + - Function: database-last-error &optional database + This function returns the last error associated with DATABASE. - `%T' - This is a synonym for `%H:%M:%S'. + - Function: database-subtype database + This function returns the subtype of DATABASE, if any. - `%U' - This stands for the week of the year (01-52), assuming that - weeks start on Sunday. + - Function: database-type database + This function returns the type of DATABASE. - `%w' - This stands for the numeric day of week (0-6). Sunday is day - 0. + +File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top + +Processes +********* + + In the terminology of operating systems, a "process" is a space in +which a program can execute. XEmacs runs in a process. XEmacs Lisp +programs can invoke other programs in processes of their own. These are +called "subprocesses" or "child processes" of the XEmacs process, which +is their "parent process". + + A subprocess of XEmacs may be "synchronous" or "asynchronous", +depending on how it is created. When you create a synchronous +subprocess, the Lisp program waits for the subprocess to terminate +before continuing execution. When you create an asynchronous +subprocess, it can run in parallel with the Lisp program. This kind of +subprocess is represented within XEmacs by a Lisp object which is also +called a "process". Lisp programs can use this object to communicate +with the subprocess or to control it. For example, you can send +signals, obtain status information, receive output from the process, or +send input to it. + + - Function: processp object + This function returns `t' if OBJECT is a process, `nil' otherwise. - `%W' - This stands for the week of the year (01-52), assuming that - weeks start on Monday. +* Menu: - `%x' - This has a locale-specific meaning. In the default locale - (named C), it is equivalent to `%D'. +* Subprocess Creation:: Functions that start subprocesses. +* Synchronous Processes:: Details of using synchronous subprocesses. +* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary + for data sent to and from a subprocess. +* Asynchronous Processes:: Starting up an asynchronous subprocess. +* Deleting Processes:: Eliminating an asynchronous subprocess. +* Process Information:: Accessing run-status and other attributes. +* Input to Processes:: Sending input to an asynchronous subprocess. +* Signals to Processes:: Stopping, continuing or interrupting + an asynchronous subprocess. +* Output from Processes:: Collecting output from an asynchronous subprocess. +* Sentinels:: Sentinels run when process run-status changes. +* Process Window Size:: Changing the logical window size of a process. +* Transaction Queues:: Transaction-based communication with subprocesses. +* Network:: Opening network connections. - `%X' - This has a locale-specific meaning. In the default locale - (named C), it is equivalent to `%T'. + +File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes + +Functions that Create Subprocesses +================================== + + There are three functions that create a new subprocess in which to +run a program. One of them, `start-process', creates an asynchronous +process and returns a process object (*note Asynchronous Processes::). +The other two, `call-process' and `call-process-region', create a +synchronous process and do not return a process object (*note +Synchronous Processes::). + + Synchronous and asynchronous processes are explained in the following +sections. Since the three functions are all called in a similar +fashion, their common arguments are described here. + + In all cases, the function's PROGRAM argument specifies the program +to be run. An error is signaled if the file is not found or cannot be +executed. If the file name is relative, the variable `exec-path' +contains a list of directories to search. Emacs initializes +`exec-path' when it starts up, based on the value of the environment +variable `PATH'. The standard file name constructs, `~', `.', and +`..', are interpreted as usual in `exec-path', but environment variable +substitutions (`$HOME', etc.) are not recognized; use +`substitute-in-file-name' to perform them (*note File Name Expansion::). + + Each of the subprocess-creating functions has a BUFFER-OR-NAME +argument which specifies where the standard output from the program will +go. If BUFFER-OR-NAME is `nil', that says to discard the output unless +a filter function handles it. (*Note Filter Functions::, and *Note +Read and Print::.) Normally, you should avoid having multiple +processes send output to the same buffer because their output would be +intermixed randomly. + + All three of the subprocess-creating functions have a `&rest' +argument, ARGS. The ARGS must all be strings, and they are supplied to +PROGRAM as separate command line arguments. Wildcard characters and +other shell constructs are not allowed in these strings, since they are +passed directly to the specified program. + + *Please note:* The argument PROGRAM contains only the name of the +program; it may not contain any command-line arguments. You must use +ARGS to provide those. + + If you want to use features of the shell, then invoke the shell +directly using, for example, PROGRAM of `"sh"', and ARGS of `"-c"' and +"COMMAND LINE...". + + The subprocess gets its current directory from the value of +`default-directory' (*note File Name Expansion::). + + The subprocess inherits its environment from XEmacs; but you can +specify overrides for it with `process-environment'. *Note System +Environment::. + + - Variable: exec-directory + The value of this variable is the name of a directory (a string) + that contains programs that come with XEmacs, that are intended + for XEmacs to invoke. The program `wakeup' is an example of such + a program; the `display-time' command uses it to get a reminder + once per minute. + + - User Option: exec-path + The value of this variable is a list of directories to search for + programs to run in subprocesses. Each element is either the name + of a directory (i.e., a string), or `nil', which stands for the + default directory (which is the value of `default-directory'). + + The value of `exec-path' is used by `call-process' and + `start-process' when the PROGRAM argument is not an absolute file + name. - `%y' - This stands for the year without century (00-99). + +File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes + +Creating a Synchronous Process +============================== + + After a "synchronous process" is created, XEmacs waits for the +process to terminate before continuing. Starting Dired is an example of +this: it runs `ls' in a synchronous process, then modifies the output +slightly. Because the process is synchronous, the entire directory +listing arrives in the buffer before XEmacs tries to do anything with +it. + + While Emacs waits for the synchronous subprocess to terminate, the +user can quit by typing `C-g'. The first `C-g' tries to kill the +subprocess with a `SIGINT' signal; but it waits until the subprocess +actually terminates before quitting. If during that time the user +types another `C-g', that kills the subprocess instantly with `SIGKILL' +and quits immediately. *Note Quitting::. + + The synchronous subprocess functions returned `nil' in version 18. +In version 19, they return an indication of how the process terminated. + + - Function: call-process program &optional infile destination display + &rest args + This function calls PROGRAM in a separate process and waits for it + to finish. + + The standard input for the process comes from file INFILE if + INFILE is not `nil' and from `/dev/null' otherwise. The argument + DESTINATION says where to put the process output. Here are the + possibilities: + + a buffer + Insert the output in that buffer, before point. This + includes both the standard output stream and the standard + error stream of the process. + + a string + Find or create a buffer with that name, then insert the + output in that buffer, before point. + + `t' + Insert the output in the current buffer, before point. + + `nil' + Discard the output. + + 0 + Discard the output, and return immediately without waiting + for the subprocess to finish. + + In this case, the process is not truly synchronous, since it + can run in parallel with Emacs; but you can think of it as + synchronous in that Emacs is essentially finished with the + subprocess as soon as this function returns. + + (REAL-DESTINATION ERROR-DESTINATION) + Keep the standard output stream separate from the standard + error stream; deal with the ordinary output as specified by + REAL-DESTINATION, and dispose of the error output according + to ERROR-DESTINATION. The value `nil' means discard it, `t' + means mix it with the ordinary output, and a string specifies + a file name to redirect error output into. + + You can't directly specify a buffer to put the error output + in; that is too difficult to implement. But you can achieve + this result by sending the error output to a temporary file + and then inserting the file into a buffer. + + If DISPLAY is non-`nil', then `call-process' redisplays the buffer + as output is inserted. Otherwise the function does no redisplay, + and the results become visible on the screen only when XEmacs + redisplays that buffer in the normal course of events. + + The remaining arguments, ARGS, are strings that specify command + line arguments for the program. + + The value returned by `call-process' (unless you told it not to + wait) indicates the reason for process termination. A number + gives the exit status of the subprocess; 0 means success, and any + other value means failure. If the process terminated with a + signal, `call-process' returns a string describing the signal. + + In the examples below, the buffer `foo' is current. + + (call-process "pwd" nil t) + => nil + + ---------- Buffer: foo ---------- + /usr/user/lewis/manual + ---------- Buffer: foo ---------- + + (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") + => nil + + ---------- Buffer: bar ---------- + lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh + + ---------- Buffer: bar ---------- + + The `insert-directory' function contains a good example of the use + of `call-process': + + (call-process insert-directory-program nil t nil switches + (if full-directory-p + (concat (file-name-as-directory file) ".") + file)) + + - Function: call-process-region start end program &optional deletep + destination displayp &rest args + This function sends the text between START to END as standard + input to a process running PROGRAM. It deletes the text sent if + DELETEP is non-`nil'; this is useful when BUFFER is `t', to insert + the output in the current buffer. + + The arguments DESTINATION and DISPLAYP control what to do with the + output from the subprocess, and whether to update the display as + it comes in. For details, see the description of `call-process', + above. If DESTINATION is the integer 0, `call-process-region' + discards the output and returns `nil' immediately, without waiting + for the subprocess to finish. + + The remaining arguments, ARGS, are strings that specify command + line arguments for the program. + + The return value of `call-process-region' is just like that of + `call-process': `nil' if you told it to return without waiting; + otherwise, a number or string which indicates how the subprocess + terminated. + + In the following example, we use `call-process-region' to run the + `cat' utility, with standard input being the first five characters + in buffer `foo' (the word `input'). `cat' copies its standard + input into its standard output. Since the argument DESTINATION is + `t', this output is inserted in the current buffer. + + ---------- Buffer: foo ---------- + input-!- + ---------- Buffer: foo ---------- + + (call-process-region 1 6 "cat" nil t) + => nil + + ---------- Buffer: foo ---------- + inputinput-!- + ---------- Buffer: foo ---------- - `%Y' - This stands for the year with century. + The `shell-command-on-region' command uses `call-process-region' + like this: - `%Z' - This stands for the time zone abbreviation. + (call-process-region + start end + shell-file-name ; Name of program. + nil ; Do not delete region. + buffer ; Send output to `buffer'. + nil ; No redisplay during output. + "-c" command) ; Arguments for the shell. - - Function: decode-time time - This function converts a time value into calendrical information. - The return value is a list of nine elements, as follows: + +File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes - (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE) +MS-DOS Subprocesses +=================== - Here is what the elements mean: + On MS-DOS, you must indicate whether the data going to and from a +synchronous subprocess are text or binary. Text data requires +translation between the end-of-line convention used within Emacs (a +single newline character) and the convention used outside Emacs (the +two-character sequence, CRLF). - SEC - The number of seconds past the minute, as an integer between - 0 and 59. + The variable `binary-process-input' applies to input sent to the +subprocess, and `binary-process-output' applies to output received from +it. A non-`nil' value means the data is non-text; `nil' means the data +is text, and calls for conversion. - MINUTE - The number of minutes past the hour, as an integer between 0 - and 59. + - Variable: binary-process-input + If this variable is `nil', convert newlines to CRLF sequences in + the input to a synchronous subprocess. - HOUR - The hour of the day, as an integer between 0 and 23. + - Variable: binary-process-output + If this variable is `nil', convert CRLF sequences to newlines in + the output from a synchronous subprocess. - DAY - The day of the month, as an integer between 1 and 31. + *Note Files and MS-DOS::, for related information. - MONTH - The month of the year, as an integer between 1 and 12. + +File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes + +Creating an Asynchronous Process +================================ + + After an "asynchronous process" is created, Emacs and the Lisp +program both continue running immediately. The process may thereafter +run in parallel with Emacs, and the two may communicate with each other +using the functions described in following sections. Here we describe +how to create an asynchronous process with `start-process'. + + - Function: start-process name buffer-or-name program &rest args + This function creates a new asynchronous subprocess and starts the + program PROGRAM running in it. It returns a process object that + stands for the new subprocess in Lisp. The argument NAME + specifies the name for the process object; if a process with this + name already exists, then NAME is modified (by adding `<1>', etc.) + to be unique. The buffer BUFFER-OR-NAME is the buffer to + associate with the process. + + The remaining arguments, ARGS, are strings that specify command + line arguments for the program. + + In the example below, the first process is started and runs + (rather, sleeps) for 100 seconds. Meanwhile, the second process + is started, and given the name `my-process<1>' for the sake of + uniqueness. It inserts the directory listing at the end of the + buffer `foo', before the first process finishes. Then it + finishes, and a message to that effect is inserted in the buffer. + Much later, the first process finishes, and another message is + inserted in the buffer for it. + + (start-process "my-process" "foo" "sleep" "100") + => # + + (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") + => #> + + ---------- Buffer: foo ---------- + total 2 + lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs + -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon + + Process my-process<1> finished + + Process my-process finished + ---------- Buffer: foo ---------- + + - Function: start-process-shell-command name buffer-or-name command + &rest command-args + This function is like `start-process' except that it uses a shell + to execute the specified command. The argument COMMAND is a shell + command name, and COMMAND-ARGS are the arguments for the shell + command. + + - Variable: process-connection-type + This variable controls the type of device used to communicate with + asynchronous subprocesses. If it is non-`nil', then PTYs are + used, when available. Otherwise, pipes are used. + + PTYs are usually preferable for processes visible to the user, as + in Shell mode, because they allow job control (`C-c', `C-z', etc.) + to work between the process and its children whereas pipes do not. + For subprocesses used for internal purposes by programs, it is + often better to use a pipe, because they are more efficient. In + addition, the total number of PTYs is limited on many systems and + it is good not to waste them. A rule of thumb is to use ptys for + processes the user interacts with directly, and pipes for + processes that are hidden from the user. + + The value `process-connection-type' is used when `start-process' + is called. So you can specify how to communicate with one + subprocess by binding the variable around the call to + `start-process'. + + (let ((process-connection-type nil)) ; Use a pipe. + (start-process ...)) + + To determine whether a given subprocess actually got a pipe or a + PTY, use the function `process-tty-name' (*note Process + Information::). + + Lisp functions that manipulate processes usually accept a PROCESS +argument. Besides using an actual process object for this argument, you +can use a process name, a buffer object, the name of a buffer, or +`nil'. Specifying a buffer or buffer name for the PROCESS argument +means use the process associated with the buffer (or the most recent +one, if there is more than one). `nil' means use the process +associated with the current buffer. *Note Process Information::. +*Note Process Buffers::. - YEAR - The year, an integer typically greater than 1900. + +File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes - DOW - The day of week, as an integer between 0 and 6, where 0 - stands for Sunday. +Deleting Processes +================== - DST - `t' if daylight savings time is effect, otherwise `nil'. + "Deleting a process" disconnects XEmacs immediately from the +subprocess, and removes it from the list of active processes. It sends +a signal to the subprocess to make the subprocess terminate, but this is +not guaranteed to happen immediately. The process object itself +continues to exist as long as other Lisp objects point to it. + + You can delete a process explicitly at any time. Processes are +deleted automatically after they terminate, but not necessarily right +away. If you delete a terminated process explicitly before it is +deleted automatically, no harm results. + + - Variable: delete-exited-processes + This variable controls automatic deletion of processes that have + terminated (due to calling `exit' or to a signal). If it is + `nil', then they continue to exist until the user runs + `list-processes'. Otherwise, they are deleted immediately after + they exit. + + - Function: delete-process name + This function deletes the process associated with NAME, killing it + with a `SIGHUP' signal. The argument NAME may be a process, the + name of a process, a buffer, or the name of a buffer. + + (delete-process "*shell*") + => nil - ZONE - An integer indicating the time zone, as the number of seconds - east of Greenwich. + - Function: process-kill-without-query process &optional + require-query-p + This function declares that XEmacs need not query the user if + PROCESS is still running when XEmacs is exited. The process will + be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs + _will_ query the user (this is the default). The return value is + `t' if a query was formerly required, and `nil' otherwise. - Note that Common Lisp has different meanings for DOW and ZONE. + (process-kill-without-query (get-process "shell")) + => t - - Function: encode-time seconds minutes hour day month year &optional - zone - This function is the inverse of `decode-time'. It converts seven - items of calendrical data into a time value. For the meanings of - the arguments, see the table above under `decode-time'. + +File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes - Year numbers less than 100 are treated just like other year - numbers. If you want them to stand for years above 1900, you must - alter them yourself before you call `encode-time'. +Process Information +=================== - The optional argument ZONE defaults to the current time zone and - its daylight savings time rules. If specified, it can be either a - list (as you would get from `current-time-zone') or an integer (as - you would get from `decode-time'). The specified zone is used - without any further alteration for daylight savings time. + Several functions return information about processes. +`list-processes' is provided for interactive use. - -File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface + - Command: list-processes + This command displays a listing of all living processes. In + addition, it finally deletes any process whose status was `Exited' + or `Signaled'. It returns `nil'. -Timers for Delayed Execution -============================ + - Function: process-list + This function returns a list of all processes that have not been + deleted. - You can set up a timer to call a function at a specified future time. - - - Function: add-timeout secs function object &optional resignal - This function adds a timeout, to be signaled after the timeout - period has elapsed. SECS is a number of seconds, expressed as an - integer or a float. FUNCTION will be called after that many - seconds have elapsed, with one argument, the given OBJECT. If the - optional RESIGNAL argument is provided, then after this timeout - expires, `add-timeout' will automatically be called again with - RESIGNAL as the first argument. - - This function returns an object which is the "id" of this - particular timeout. You can pass that object to `disable-timeout' - to turn off the timeout before it has been signalled. - - The number of seconds may be expressed as a floating-point number, - in which case some fractional part of a second will be used. - Caveat: the usable timeout granularity will vary from system to - system. - - Adding a timeout causes a timeout event to be returned by - `next-event', and the function will be invoked by - `dispatch-event', so if XEmacs is in a tight loop, the function - will not be invoked until the next call to sit-for or until the - return to top-level (the same is true of process filters). - - WARNING: if you are thinking of calling add-timeout from inside of - a callback function as a way of resignalling a timeout, think - again. There is a race condition. That's why the RESIGNAL - argument exists. - - (NOTE: In FSF Emacs, this function is called `run-at-time' and has - different semantics.) - - - Function: disable-timeout id - Cancel the requested action for ID, which should be a value - previously returned by `add-timeout'. This cancels the effect of - that call to `add-timeout'; the arrival of the specified time will - not cause anything special to happen. (NOTE: In FSF Emacs, this - function is called `cancel-timer'.) + (process-list) + => (# #) - -File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface + - Function: get-process process-name + This function returns the process named PROCESS-NAME. If + PROCESS-NAME is a string and there is no process with that name, + the value is `nil'. If PROCESS-NAME is actually a process, it is + returned as given. (That is not very useful, so the argument is + usually a name.) For example: -Terminal Input -============== + (get-process "shell") + => # - This section describes functions and variables for recording or -manipulating terminal input. See *Note Display::, for related -functions. + - Function: process-command process + This function returns the command that was executed to start + PROCESS. This is a list of strings, the first string being the + program executed and the rest of the strings being the arguments + that were given to the program. -* Menu: + (process-command (get-process "shell")) + => ("/bin/csh" "-i") -* Input Modes:: Options for how input is processed. -* Translating Input:: Low level conversion of some characters or events - into others. -* Recording Input:: Saving histories of recent or all input events. + - Function: process-id process + This function returns the PID of PROCESS. This is an integer that + distinguishes the process PROCESS from all other processes running + on the same computer at the current time. The PID of a process is + chosen by the operating system kernel when the process is started + and remains constant as long as the process exists. - -File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input - -Input Modes ------------ - - - Function: set-input-mode interrupt flow meta quit-char - This function sets the mode for reading keyboard input. If - INTERRUPT is non-null, then XEmacs uses input interrupts. If it is - `nil', then it uses CBREAK mode. When XEmacs communicates - directly with X, it ignores this argument and uses interrupts if - that is the way it knows how to communicate. - - If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s') - flow control for output to the terminal. This has no effect except - in CBREAK mode. *Note Flow Control::. - - The default setting is system dependent. Some systems always use - CBREAK mode regardless of what is specified. - - The argument META controls support for input character codes above - 127. If META is `t', XEmacs converts characters with the 8th bit - set into Meta characters. If META is `nil', XEmacs disregards the - 8th bit; this is necessary when the terminal uses it as a parity - bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of - input unchanged. This is good for terminals using European 8-bit - character sets. - - If QUIT-CHAR is non-`nil', it specifies the character to use for - quitting. Normally this character is `C-g'. *Note Quitting::. - - The `current-input-mode' function returns the input mode settings -XEmacs is currently using. - - - Function: current-input-mode - This function returns current mode for reading keyboard input. It - returns a list, corresponding to the arguments of `set-input-mode', - of the form `(INTERRUPT FLOW META QUIT)' in which: - INTERRUPT - is non-`nil' when XEmacs is using interrupt-driven input. If - `nil', Emacs is using CBREAK mode. - - FLOW - is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow - control for output to the terminal. This value has no effect - unless INTERRUPT is non-`nil'. - - META - is `t' if XEmacs treats the eighth bit of input characters as - the meta bit; `nil' means XEmacs clears the eighth bit of - every input character; any other value means XEmacs uses all - eight bits as the basic character code. - - QUIT - is the character XEmacs currently uses for quitting, usually - `C-g'. + - Function: process-name process + This function returns the name of PROCESS. - -File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input - -Translating Input Events ------------------------- - - This section describes features for translating input events into -other input events before they become part of key sequences. - - - Variable: function-key-map - This variable holds a keymap that describes the character sequences - sent by function keys on an ordinary character terminal. This - keymap uses the same data structure as other keymaps, but is used - differently: it specifies translations to make while reading - events. - - If `function-key-map' "binds" a key sequence K to a vector V, then - when K appears as a subsequence _anywhere_ in a key sequence, it - is replaced with the events in V. - - For example, VT100 terminals send ` O P' when the keypad PF1 - key is pressed. Therefore, we want XEmacs to translate that - sequence of events into the single event `pf1'. We accomplish - this by "binding" ` O P' to `[pf1]' in `function-key-map', - when using a VT100. - - Thus, typing `C-c ' sends the character sequence `C-c O - P'; later the function `read-key-sequence' translates this back - into `C-c ', which it returns as the vector `[?\C-c pf1]'. - - Entries in `function-key-map' are ignored if they conflict with - bindings made in the minor mode, local, or global keymaps. The - intent is that the character sequences that function keys send - should not have command bindings in their own right. - - The value of `function-key-map' is usually set up automatically - according to the terminal's Terminfo or Termcap entry, but - sometimes those need help from terminal-specific Lisp files. - XEmacs comes with terminal-specific files for many common - terminals; their main purpose is to make entries in - `function-key-map' beyond those that can be deduced from Termcap - and Terminfo. *Note Terminal-Specific::. - - Emacs versions 18 and earlier used totally different means of - detecting the character sequences that represent function keys. - - - Variable: key-translation-map - This variable is another keymap used just like `function-key-map' - to translate input events into other events. It differs from - `function-key-map' in two ways: - - * `key-translation-map' goes to work after `function-key-map' is - finished; it receives the results of translation by - `function-key-map'. - - * `key-translation-map' overrides actual key bindings. - - The intent of `key-translation-map' is for users to map one - character set to another, including ordinary characters normally - bound to `self-insert-command'. - - You can use `function-key-map' or `key-translation-map' for more -than simple aliases, by using a function, instead of a key sequence, as -the "translation" of a key. Then this function is called to compute -the translation of that key. - - The key translation function receives one argument, which is the -prompt that was specified in `read-key-sequence'--or `nil' if the key -sequence is being read by the editor command loop. In most cases you -can ignore the prompt value. - - If the function reads input itself, it can have the effect of -altering the event that follows. For example, here's how to define -`C-c h' to turn the character that follows into a Hyper character: - - (defun hyperify (prompt) - (let ((e (read-event))) - (vector (if (numberp e) - (logior (lsh 1 20) e) - (if (memq 'hyper (event-modifiers e)) - e - (add-event-modifier "H-" e)))))) - - (defun add-event-modifier (string e) - (let ((symbol (if (symbolp e) e (car e)))) - (setq symbol (intern (concat string - (symbol-name symbol)))) - (if (symbolp e) - symbol - (cons symbol (cdr e))))) - - (define-key function-key-map "\C-ch" 'hyperify) - - The `iso-transl' library uses this feature to provide a way of -inputting non-ASCII Latin-1 characters. + - Function: process-status process + This function returns the status of PROCESS as a symbol. The + argument PROCESS must be a process, a buffer, a process name + (string) or a buffer name (string). - -File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input + The possible values for an actual subprocess are: -Recording Input ---------------- + `run' + for a process that is running. - - Function: recent-keys &optional number - This function returns a vector containing recent input events from - the keyboard or mouse. By default, 100 events are recorded, which - is how many `recent-keys' returns. + `stop' + for a process that is stopped but continuable. - All input events are included, whether or not they were used as - parts of key sequences. Thus, you always get the last 100 inputs, - not counting keyboard macros. (Events from keyboard macros are - excluded because they are less interesting for debugging; it - should be enough to see the events that invoked the macros.) + `exit' + for a process that has exited. - If NUMBER is specified, not more than NUMBER events will be - returned. You may change the number of stored events using - `set-recent-keys-ring-size'. + `signal' + for a process that has received a fatal signal. - - Function: recent-keys-ring-size - This function returns the number of recent events stored - internally. This is also the maximum number of events - `recent-keys' can return. By default, 100 events are stored. + `open' + for a network connection that is open. - - Function: set-recent-keys-ring-size size - This function changes the number of events stored by XEmacs and - returned by `recent-keys'. + `closed' + for a network connection that is closed. Once a connection + is closed, you cannot reopen it, though you might be able to + open a new connection to the same place. - For example, `(set-recent-keys-ring-size 250)' will make XEmacs - remember last 250 events and will make `recent-keys' return last - 250 events by default. + `nil' + if PROCESS does not identify an existing process. - - Command: open-dribble-file filename - This function opens a "dribble file" named FILENAME. When a - dribble file is open, each input event from the keyboard or mouse - (but not those from keyboard macros) is written in that file. A - non-character event is expressed using its printed representation - surrounded by `<...>'. + (process-status "shell") + => run + (process-status (get-buffer "*shell*")) + => run + x + => #> + (process-status x) + => exit - You close the dribble file by calling this function with an - argument of `nil'. + For a network connection, `process-status' returns one of the + symbols `open' or `closed'. The latter means that the other side + closed the connection, or XEmacs did `delete-process'. - This function is normally used to record the input necessary to - trigger an XEmacs bug, for the sake of a bug report. + In earlier Emacs versions (prior to version 19), the status of a + network connection was `run' if open, and `exit' if closed. - (open-dribble-file "~/dribble") - => nil + - Function: process-kill-without-query-p process + This function returns whether PROCESS will be killed without + querying the user, if it is running when XEmacs is exited. The + default value is `nil'. - See also the `open-termscript' function (*note Terminal Output::). + - Function: process-exit-status process + This function returns the exit status of PROCESS or the signal + number that killed it. (Use the result of `process-status' to + determine which of those it is.) If PROCESS has not yet + terminated, the value is 0. + + - Function: process-tty-name process + This function returns the terminal name that PROCESS is using for + its communication with Emacs--or `nil' if it is using pipes + instead of a terminal (see `process-connection-type' in *Note + Asynchronous Processes::).