-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
-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.
-
-\1f
-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::.
\1f
-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.
-
- 11. It displays the initial echo area message, unless you have
- suppressed that with `inhibit-startup-echo-area-message'.
-
- 12. It processes the action arguments from the command line.
+\1f
+File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
- 13. It runs `term-setup-hook'.
+Beeping
+=======
- 14. It calls `frame-notice-user-settings', which modifies the
- parameters of the selected frame according to whatever the init
- files specify.
+ 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::.)
- 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
+ - 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.
- 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'.
+ - Function: beep &optional dont-terminate sound device
+ This is a synonym for `ding'.
- - 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.
+ - 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.
- 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.
+ - 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-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:
+ 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:
- (setq inhibit-startup-echo-area-message
- "YOUR-LOGIN-NAME")
+ `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.
- 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.
+ `volume'
+ An integer from 0-100, defaulting to `bell-volume'.
- 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.
+ `pitch'
+ If using the default X beep, the pitch (Hz) to generate.
-\1f
-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'.
+ `duration'
+ If using the default X beep, the duration (milliseconds).
- - 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'.
+ For compatibility, elements of `sound-alist' may also be:
-\1f
-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'.
+ * `( sound-name . <sound> )'
-\1f
-File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
+ * `( sound-name <volume> <sound> )'
-Command Line Arguments
-----------------------
+ You should probably add things to this list by calling the function
+ `load-sound-file'.
- 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.
+ Caveats:
- This section describes how Emacs processes command line arguments,
-and how you can customize them.
+ - You can only play audio data if running on the console screen
+ of a Sun SparcStation, SGI, or HP9000s700.
- - 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.
+ - The pitch, duration, and volume options are available
+ everywhere, but many X servers ignore the `pitch' option.
- - Variable: command-line-processed
- The value of this variable is `t' once the command line has been
- processed.
+ The following beep-types are used by XEmacs itself:
- 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.
+ `auto-save-error'
+ when an auto-save does not succeed
- - 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.
+ `command-error'
+ when the XEmacs command loop catches an error
- A "command line option" is an argument on the command line of the
- form:
+ `undefined-key'
+ when you type a key that is undefined
- -OPTION
+ `undefined-click'
+ when you use an undefined mouse-click combination
- The elements of the `command-switch-alist' look like this:
+ `no-completion'
+ during completing-read
- (OPTION . HANDLER-FUNCTION)
+ `y-or-n-p'
+ when you type something other than 'y' or 'n'
- The HANDLER-FUNCTION is called to handle OPTION and receives the
- option name as its sole argument.
+ `yes-or-no-p'
+ when you type something other than 'yes' or 'no'
- 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'.)
+ `default'
+ used when nothing else is appropriate.
- 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.
+ Other lisp packages may use other beep types, but these are the
+ ones that the C kernel of XEmacs uses.
- - Variable: command-line-args
- The value of this variable is the list of command line arguments
- passed to XEmacs.
+ - User Option: bell-volume
+ This variable specifies the default volume for sounds, from 0 to
+ 100.
- - 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.
+ - Command: load-default-sounds
+ This function loads and installs some sound files as beep-types.
- 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'.
+ - 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.
- 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'.
+ - 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.
- 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.
\1f
-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.
\1f
-File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
-
-Killing XEmacs
---------------
-
- 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'.
-
- - Function: kill-emacs &optional EXIT-DATA
- This function exits the XEmacs process and kills it.
-
- 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::.)
-
- 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.
-
- 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'.
-
- - 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.
-
- - 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.
+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'.
\1f
-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")))
+File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
- (add-hook 'suspend-resume-hook
- (function (lambda () (message "Resumed!"))))
- => (lambda nil (message "Resumed!"))
+Working With Hash Tables
+========================
- (suspend-emacs "pwd")
- => nil
+ - Function: puthash key value hash-table
+ This function hashes KEY to VALUE in HASH-TABLE.
- ---------- Buffer: Minibuffer ----------
- Really suspend? y
- ---------- Buffer: Minibuffer ----------
+ - 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').
- ---------- Parent Shell ----------
- lewis@slug[23] % /user/lewis/manual
- lewis@slug[24] % fg
+ - 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.
- ---------- Echo Area ----------
- Resumed!
+ - Function: clrhash hash-table
+ This function removes all entries from HASH-TABLE, leaving it
+ empty.
- - Variable: suspend-hook
- This variable is a normal hook run before suspending.
+ - 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: suspend-resume-hook
- This variable is a normal hook run after suspending.
+ FUNCTION may not modify HASH-TABLE, with the one exception that
+ FUNCTION may remhash or puthash the entry currently being
+ processed by FUNCTION.
\1f
-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.
+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'.
- `ms-dos'
- Microsoft MS-DOS "operating system."
-
- `next-mach'
- NeXT Mach-based system.
-
- `rtu'
- Masscomp RTU, UCB universe.
-
- `unisoft-unix'
- UniSoft UniPlus.
-
- `usg-unix-v'
- AT&T System V.
-
- `vax-vms'
- VAX VMS.
-
- `windows-nt'
- Microsoft windows NT.
-
- `xenix'
- SCO Xenix 386.
-
- 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.
+\1f
+File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
- - 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'.
+Range Tables
+************
- - Function: system-name
- This function returns the name of the machine you are running on.
- (system-name)
- => "prep.ai.mit.edu"
+ A range table is a table that efficiently associated values with
+ranges of integers.
- 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::.).
+ Note that range tables have a read syntax, like this:
- - 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::.)
+ #s(range-table data ((-3 2) foo (5 20) bar))
- - 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'.
+ This maps integers in the range (-3, 2) to `foo' and integers in the
+range (5, 20) to `bar'.
- (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.
+ - Function: range-table-p object
+ Return non-`nil' if OBJECT is a range table.
- - 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.
+\1f
+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.
\1f
-File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
+File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
-User Identification
-===================
-
- - 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.
-
- - 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.
-
- If you specify UID, the value is the user name that corresponds to
- UID (which should be an integer).
+Working With Range Tables
+=========================
- (user-login-name)
- => "lewis"
+ - 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').
- - 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: put-range-table start end value range-table
+ This function sets the value for range (START, END) to be VALUE in
+ 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: remove-range-table start end range-table
+ This function removes the value for range (START, END) in
+ RANGE-TABLE.
- - 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.
+ - Function: clear-range-table range-table
+ This function flushes RANGE-TABLE.
- If USER is specified explicitly, `user-full-name' variable is
- ignored.
+ - 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.
- (user-full-name)
- => "Hrvoje Niksic"
- (setq user-full-name "Hrvoje \"Niksa\" Niksic")
- (user-full-name)
- => "Hrvoje \"Niksa\" Niksic"
- (user-full-name "hniksic")
- => "Hrvoje Niksic"
+\1f
+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:
+\1f
+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.
-\1f
-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::.).
-
\1f
-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.
+File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
- `%B'
- This stands for the full name of the month.
+Working With a Database
+=======================
- `%c'
- This is a synonym for `%x %X'.
+ - 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).
- `%C'
- This has a locale-specific meaning. In the default locale
- (named C), it is equivalent to `%A, %B %e, %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.
- `%d'
- This stands for the day of month, zero-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.
- `%D'
- This is a synonym for `%m/%d/%y'.
+ - Function: remove-database key database
+ This function removes KEY from DATABASE.
- `%e'
- This stands for the day of month, blank-padded.
-
- `%h'
- This is a synonym for `%b'.
-
- `%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'.
+\1f
+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.
+\1f
+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'.
+\1f
+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).
+\1f
+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:
+\1f
+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.
+\1f
+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")
+ => #<process my-process>
+
+ (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
+ => #<process my-process<1>>
+
+ ---------- 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.
+\1f
+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'.
+\1f
+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.
-\1f
-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)
+ => (#<process display-time> #<process shell>)
-\1f
-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")
+ => #<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.
-\1f
-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.
-\1f
-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 `<ESC> 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" `<ESC> O P' to `[pf1]' in `function-key-map',
- when using a VT100.
-
- Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
- P'; later the function `read-key-sequence' translates this back
- into `C-c <PF1>', 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).
-\1f
-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 xx<1>>
+ (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::).
projects / chise / xemacs-chise.git / blobdiff