1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
55 Operating System Environment
56 ============================
58 XEmacs provides access to variables in the operating system
59 environment through various functions. These variables include the
60 name of the system, the user's UID, and so on.
62 - Variable: system-type
63 The value of this variable is a symbol indicating the type of
64 operating system XEmacs is operating on. Here is a table of the
74 Data General DGUX operating system.
77 A GNU system using the GNU HURD and Mach.
80 Hewlett-Packard HPUX operating system.
83 Silicon Graphics Irix system.
86 A GNU system using the Linux kernel.
89 Microsoft MS-DOS "operating system."
92 NeXT Mach-based system.
95 Masscomp RTU, UCB universe.
104 Microsoft windows NT.
109 We do not wish to add new symbols to make finer distinctions
110 unless it is absolutely necessary! In fact, we hope to eliminate
111 some of these alternatives in the future. We recommend using
112 `system-configuration' to distinguish between different operating
115 - Variable: system-configuration
116 This variable holds the three-part configuration name for the
117 hardware/software configuration of your system, as a string. The
118 convenient way to test parts of this string is with `string-match'.
120 - Function: system-name
121 This function returns the name of the machine you are running on.
125 The symbol `system-name' is a variable as well as a function. In
126 fact, the function returns whatever value the variable `system-name'
127 currently holds. Thus, you can set the variable `system-name' in case
128 Emacs is confused about the name of your system. The variable is also
129 useful for constructing frame titles (*note Frame Titles::).
131 - Variable: mail-host-address
132 If this variable is non-`nil', it is used instead of `system-name'
133 for purposes of generating email addresses. For example, it is
134 used when constructing the default value of `user-mail-address'.
135 *Note User Identification::. (Since this is done when XEmacs
136 starts up, the value actually used is the one saved when XEmacs
137 was dumped. *Note Building XEmacs::.)
139 - Command: getenv var &optional interactivep
140 This function returns the value of the environment variable VAR,
141 as a string. Within XEmacs, the environment variable values are
142 kept in the Lisp variable `process-environment'.
144 When invoked interactively, `getenv' prints the value in the echo
150 lewis@slug[10] % printenv
151 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
157 - Command: setenv variable &optional value unset
158 This command sets the value of the environment variable named
159 VARIABLE to VALUE. Both arguments should be strings. This
160 function works by modifying `process-environment'; binding that
161 variable with `let' is also reasonable practice.
163 - Variable: process-environment
164 This variable is a list of strings, each describing one environment
165 variable. The functions `getenv' and `setenv' work by
166 manipulating this variable.
169 => ("l=/usr/stanford/lib/gnuemacs/lisp"
170 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
176 - Variable: path-separator
177 This variable holds a string which says which character separates
178 directories in a search path (as found in an environment
179 variable). Its value is `":"' for Unix and GNU systems, and `";"'
180 for MS-DOS and Windows NT.
182 - Variable: invocation-name
183 This variable holds the program name under which Emacs was
184 invoked. The value is a string, and does not include a directory
187 - Variable: invocation-directory
188 This variable holds the directory from which the Emacs executable
189 was invoked, or perhaps `nil' if that directory cannot be
192 - Variable: installation-directory
193 If non-`nil', this is a directory within which to look for the
194 `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
195 can't find those directories in their standard installed
196 locations, but can find them in a directory related somehow to the
197 one containing the Emacs executable.
199 - Function: load-average &optional use-floats
200 This function returns a list of the current 1-minute, 5-minute and
201 15-minute load averages. The values are integers that are 100
202 times the system load averages. (The load averages indicate the
203 number of processes trying to run.)
205 When USE-FLOATS is non-`nil', floats will be returned instead of
206 integers. These floats are not multiplied by 100.
211 => (1.69921875 1.58984375 1.640625)
213 lewis@rocky[5] % uptime
214 8:06pm up 16 day(s), 21:57, 40 users,
215 load average: 1.68, 1.59, 1.64
217 If the 5-minute or 15-minute load averages are not available,
218 return a shortened list, containing only those averages which are
221 On some systems, this function may require special privileges to
222 run, or it may be unimplemented for the particular system type.
223 In that case, the function will signal an error.
225 - Function: emacs-pid
226 This function returns the process ID of the Emacs process.
229 File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
234 - Variable: user-mail-address
235 This holds the nominal email address of the user who is using
236 Emacs. When Emacs starts up, it computes a default value that is
237 usually right, but users often set this themselves when the
238 default value is not right.
240 - Function: user-login-name &optional uid
241 If you don't specify UID, this function returns the name under
242 which the user is logged in. If the environment variable `LOGNAME'
243 is set, that value is used. Otherwise, if the environment variable
244 `USER' is set, that value is used. Otherwise, the value is based
245 on the effective UID, not the real UID.
247 If you specify UID, the value is the user name that corresponds to
248 UID (which should be an integer).
253 - Function: user-real-login-name
254 This function returns the user name corresponding to Emacs's real
255 UID. This ignores the effective UID and ignores the environment
256 variables `LOGNAME' and `USER'.
258 - Variable: user-full-name
259 This variable holds the name of the user running this Emacs. It is
260 initialized at startup time from the value of `NAME' environment
261 variable. You can change the value of this variable to alter the
262 result of the `user-full-name' function.
264 - Function: user-full-name &optional user
265 This function returns the full name of USER. If USER is `nil', it
266 defaults to the user running this Emacs. In that case, the value
267 of `user-full-name' variable, if non-`nil', will be used.
269 If USER is specified explicitly, `user-full-name' variable is
274 (setq user-full-name "Hrvoje \"Niksa\" Niksic")
276 => "Hrvoje \"Niksa\" Niksic"
277 (user-full-name "hniksic")
280 The symbols `user-login-name', `user-real-login-name' and
281 `user-full-name' are variables as well as functions. The functions
282 return the same values that the variables hold. These variables allow
283 you to "fake out" Emacs by telling the functions what to return. The
284 variables are also useful for constructing frame titles (*note Frame
287 - Function: user-real-uid
288 This function returns the real UID of the user.
294 This function returns the effective UID of the user.
296 - Function: user-home-directory
297 This function returns the "`HOME'" directory of the user, and is
298 intended to replace occurrences of "`(getenv "HOME")'". Under
299 Unix systems, the following is done:
301 1. Return the value of "`(getenv "HOME")'", if set.
303 2. Return "/", as a fallback, but issue a warning. (Future
304 versions of XEmacs will also attempt to lookup the `HOME'
305 directory via `getpwent()', but this has not yet been
308 Under MS Windows, this is done:
310 1. Return the value of "`(getenv "HOME")'", if set.
312 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
313 both set, return the concatenation (the following description
314 uses MS Windows environment variable substitution syntax):
315 `%HOMEDRIVE%%HOMEDIR%'.
317 3. Return "C:\", as a fallback, but issue a warning.
320 File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
325 This section explains how to determine the current time and the time
328 - Function: current-time-string &optional time-value
329 This function returns the current time and date as a
330 humanly-readable string. The format of the string is unvarying;
331 the number of characters used for each part is always the same, so
332 you can reliably use `substring' to extract pieces of it. It is
333 wise to count the characters from the beginning of the string
334 rather than from the end, as additional information may be added
337 The argument TIME-VALUE, if given, specifies a time to format
338 instead of the current time. The argument should be a list whose
339 first two elements are integers. Thus, you can use times obtained
340 from `current-time' (see below) and from `file-attributes' (*note
343 (current-time-string)
344 => "Wed Oct 14 22:21:05 1987"
346 - Function: current-time
347 This function returns the system's time value as a list of three
348 integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
349 combine to give the number of seconds since 0:00 January 1, 1970,
350 which is HIGH * 2**16 + LOW.
352 The third element, MICROSEC, gives the microseconds since the
353 start of the current second (or 0 for systems that return time
354 only on the resolution of a second).
356 The first two elements can be compared with file time values such
357 as you get with the function `file-attributes'. *Note File
360 - Function: current-time-zone &optional time-value
361 This function returns a list describing the time zone that the
364 The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
365 giving the number of seconds ahead of UTC (east of Greenwich). A
366 negative value means west of Greenwich. The second element, NAME
367 is a string giving the name of the time zone. Both elements
368 change when daylight savings time begins or ends; if the user has
369 specified a time zone that does not use a seasonal time
370 adjustment, then the value is constant through time.
372 If the operating system doesn't supply all the information
373 necessary to compute the value, both elements of the list are
376 The argument TIME-VALUE, if given, specifies a time to analyze
377 instead of the current time. The argument should be a cons cell
378 containing two integers, or a list whose first two elements are
379 integers. Thus, you can use times obtained from `current-time'
380 (see above) and from `file-attributes' (*note File Attributes::).
383 File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
388 These functions convert time values (lists of two or three integers)
389 to strings or to calendrical information. There is also a function to
390 convert calendrical information to a time value. You can get time
391 values from the functions `current-time' (*note Time of Day::) and
392 `file-attributes' (*note File Attributes::).
394 - Function: format-time-string format-string &optional time
395 This function converts TIME to a string according to
396 FORMAT-STRING. If TIME is omitted, it defaults to the current
397 time. The argument FORMAT-STRING may contain `%'-sequences which
398 say to substitute parts of the time. Here is a table of what the
402 This stands for the abbreviated name of the day of week.
405 This stands for the full name of the day of week.
408 This stands for the abbreviated name of the month.
411 This stands for the full name of the month.
414 This is a synonym for `%x %X'.
417 This has a locale-specific meaning. In the default locale
418 (named C), it is equivalent to `%A, %B %e, %Y'.
421 This stands for the day of month, zero-padded.
424 This is a synonym for `%m/%d/%y'.
427 This stands for the day of month, blank-padded.
430 This is a synonym for `%b'.
433 This stands for the hour (00-23).
436 This stands for the hour (00-12).
439 This stands for the day of the year (001-366).
442 This stands for the hour (0-23), blank padded.
445 This stands for the hour (1-12), blank padded.
448 This stands for the month (01-12).
451 This stands for the minute (00-59).
454 This stands for a newline.
457 This stands for `AM' or `PM', as appropriate.
460 This is a synonym for `%I:%M:%S %p'.
463 This is a synonym for `%H:%M'.
466 This stands for the seconds (00-60).
469 This stands for a tab character.
472 This is a synonym for `%H:%M:%S'.
475 This stands for the week of the year (01-52), assuming that
476 weeks start on Sunday.
479 This stands for the numeric day of week (0-6). Sunday is day
483 This stands for the week of the year (01-52), assuming that
484 weeks start on Monday.
487 This has a locale-specific meaning. In the default locale
488 (named C), it is equivalent to `%D'.
491 This has a locale-specific meaning. In the default locale
492 (named C), it is equivalent to `%T'.
495 This stands for the year without century (00-99).
498 This stands for the year with century.
501 This stands for the time zone abbreviation.
503 - Function: decode-time &optional specified-time
504 This function converts a time value into calendrical information.
505 The optional SPECIFIED-TIME should be a list of (HIGH LOW .
506 IGNORED) or (HIGH . LOW), as from `current-time' and
507 `file-attributes', or `nil' to use the current time.
509 The return value is a list of nine elements, as follows:
511 (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
513 Here is what the elements mean:
516 The number of seconds past the minute, as an integer between
520 The number of minutes past the hour, as an integer between 0
524 The hour of the day, as an integer between 0 and 23.
527 The day of the month, as an integer between 1 and 31.
530 The month of the year, as an integer between 1 and 12.
533 The year, an integer typically greater than 1900.
536 The day of week, as an integer between 0 and 6, where 0
540 `t' if daylight savings time is effect, otherwise `nil'.
543 An integer indicating the time zone, as the number of seconds
546 Note that Common Lisp has different meanings for DOW and ZONE.
548 - Function: encode-time seconds minutes hour day month year &optional
550 This function is the inverse of `decode-time'. It converts seven
551 items of calendrical data into a time value. For the meanings of
552 the arguments, see the table above under `decode-time'.
554 Year numbers less than 100 are treated just like other year
555 numbers. If you want them to stand for years above 1900, you must
556 alter them yourself before you call `encode-time'.
558 The optional argument ZONE defaults to the current time zone and
559 its daylight savings time rules. If specified, it can be either a
560 list (as you would get from `current-time-zone') or an integer (as
561 you would get from `decode-time'). The specified zone is used
562 without any further alteration for daylight savings time.
565 File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
567 Timers for Delayed Execution
568 ============================
570 You can set up a timer to call a function at a specified future time.
572 - Function: add-timeout secs function object &optional resignal
573 This function adds a timeout, to be signaled after the timeout
574 period has elapsed. SECS is a number of seconds, expressed as an
575 integer or a float. FUNCTION will be called after that many
576 seconds have elapsed, with one argument, the given OBJECT. If the
577 optional RESIGNAL argument is provided, then after this timeout
578 expires, `add-timeout' will automatically be called again with
579 RESIGNAL as the first argument.
581 This function returns an object which is the "id" of this
582 particular timeout. You can pass that object to `disable-timeout'
583 to turn off the timeout before it has been signalled.
585 The number of seconds may be expressed as a floating-point number,
586 in which case some fractional part of a second will be used.
587 Caveat: the usable timeout granularity will vary from system to
590 Adding a timeout causes a timeout event to be returned by
591 `next-event', and the function will be invoked by
592 `dispatch-event', so if XEmacs is in a tight loop, the function
593 will not be invoked until the next call to sit-for or until the
594 return to top-level (the same is true of process filters).
596 WARNING: if you are thinking of calling add-timeout from inside of
597 a callback function as a way of resignalling a timeout, think
598 again. There is a race condition. That's why the RESIGNAL
601 (NOTE: In FSF Emacs, this function is called `run-at-time' and has
602 different semantics.)
604 - Function: disable-timeout id
605 Cancel the requested action for ID, which should be a value
606 previously returned by `add-timeout'. This cancels the effect of
607 that call to `add-timeout'; the arrival of the specified time will
608 not cause anything special to happen. (NOTE: In FSF Emacs, this
609 function is called `cancel-timer'.)
612 File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
617 This section describes functions and variables for recording or
618 manipulating terminal input. See *Note Display::, for related
623 * Input Modes:: Options for how input is processed.
624 * Translating Input:: Low level conversion of some characters or events
626 * Recording Input:: Saving histories of recent or all input events.
629 File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
634 - Function: set-input-mode interrupt flow meta &optional quit-char
636 This function sets the mode for reading keyboard input. If
637 INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
638 `nil', then it uses CBREAK mode. When XEmacs communicates
639 directly with X, it ignores this argument and uses interrupts if
640 that is the way it knows how to communicate.
642 If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
643 flow control for output to the terminal. This has no effect except
644 in CBREAK mode. *Note Flow Control::.
646 The default setting is system dependent. Some systems always use
647 CBREAK mode regardless of what is specified.
649 The argument META controls support for input character codes above
650 127. If META is `t', XEmacs converts characters with the 8th bit
651 set into Meta characters. If META is `nil', XEmacs disregards the
652 8th bit; this is necessary when the terminal uses it as a parity
653 bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
654 input unchanged. This is good for terminals using European 8-bit
657 If QUIT-CHAR is non-`nil', it specifies the character to use for
658 quitting. Normally this character is `C-g'. *Note Quitting::.
660 The `current-input-mode' function returns the input mode settings
661 XEmacs is currently using.
663 - Function: current-input-mode &optional console
664 This function returns current mode for reading keyboard input. It
665 returns a list, corresponding to the arguments of `set-input-mode',
666 of the form `(INTERRUPT FLOW META QUIT)' in which:
668 is non-`nil' when XEmacs is using interrupt-driven input. If
669 `nil', Emacs is using CBREAK mode.
672 is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
673 control for output to the terminal. This value has no effect
674 unless INTERRUPT is non-`nil'.
677 is `t' if XEmacs treats the eighth bit of input characters as
678 the meta bit; `nil' means XEmacs clears the eighth bit of
679 every input character; any other value means XEmacs uses all
680 eight bits as the basic character code.
683 is the character XEmacs currently uses for quitting, usually
687 File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
689 Translating Input Events
690 ------------------------
692 This section describes features for translating input events into
693 other input events before they become part of key sequences.
695 - Variable: function-key-map
696 This variable holds a keymap that describes the character sequences
697 sent by function keys on an ordinary character terminal. This
698 keymap uses the same data structure as other keymaps, but is used
699 differently: it specifies translations to make while reading
702 If `function-key-map' "binds" a key sequence K to a vector V, then
703 when K appears as a subsequence _anywhere_ in a key sequence, it
704 is replaced with the events in V.
706 For example, VT100 terminals send `<ESC> O P' when the keypad PF1
707 key is pressed. Therefore, we want XEmacs to translate that
708 sequence of events into the single event `pf1'. We accomplish
709 this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
712 Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
713 P'; later the function `read-key-sequence' translates this back
714 into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
716 Entries in `function-key-map' are ignored if they conflict with
717 bindings made in the minor mode, local, or global keymaps. The
718 intent is that the character sequences that function keys send
719 should not have command bindings in their own right.
721 The value of `function-key-map' is usually set up automatically
722 according to the terminal's Terminfo or Termcap entry, but
723 sometimes those need help from terminal-specific Lisp files.
724 XEmacs comes with terminal-specific files for many common
725 terminals; their main purpose is to make entries in
726 `function-key-map' beyond those that can be deduced from Termcap
727 and Terminfo. *Note Terminal-Specific::.
729 Emacs versions 18 and earlier used totally different means of
730 detecting the character sequences that represent function keys.
732 - Variable: key-translation-map
733 This variable is another keymap used just like `function-key-map'
734 to translate input events into other events. It differs from
735 `function-key-map' in two ways:
737 * `key-translation-map' goes to work after `function-key-map' is
738 finished; it receives the results of translation by
741 * `key-translation-map' overrides actual key bindings.
743 The intent of `key-translation-map' is for users to map one
744 character set to another, including ordinary characters normally
745 bound to `self-insert-command'.
747 You can use `function-key-map' or `key-translation-map' for more
748 than simple aliases, by using a function, instead of a key sequence, as
749 the "translation" of a key. Then this function is called to compute
750 the translation of that key.
752 The key translation function receives one argument, which is the
753 prompt that was specified in `read-key-sequence'--or `nil' if the key
754 sequence is being read by the editor command loop. In most cases you
755 can ignore the prompt value.
757 If the function reads input itself, it can have the effect of
758 altering the event that follows. For example, here's how to define
759 `C-c h' to turn the character that follows into a Hyper character:
761 (defun hyperify (prompt)
762 (let ((e (read-event)))
763 (vector (if (numberp e)
764 (logior (lsh 1 20) e)
765 (if (memq 'hyper (event-modifiers e))
767 (add-event-modifier "H-" e))))))
769 (defun add-event-modifier (string e)
770 (let ((symbol (if (symbolp e) e (car e))))
771 (setq symbol (intern (concat string
772 (symbol-name symbol))))
775 (cons symbol (cdr e)))))
777 (define-key function-key-map "\C-ch" 'hyperify)
779 The `iso-transl' library uses this feature to provide a way of
780 inputting non-ASCII Latin-1 characters.
783 File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
788 - Function: recent-keys &optional number
789 This function returns a vector containing recent input events from
790 the keyboard or mouse. By default, 100 events are recorded, which
791 is how many `recent-keys' returns.
793 All input events are included, whether or not they were used as
794 parts of key sequences. Thus, you always get the last 100 inputs,
795 not counting keyboard macros. (Events from keyboard macros are
796 excluded because they are less interesting for debugging; it
797 should be enough to see the events that invoked the macros.)
799 If NUMBER is specified, not more than NUMBER events will be
800 returned. You may change the number of stored events using
801 `set-recent-keys-ring-size'.
803 - Function: recent-keys-ring-size
804 This function returns the number of recent events stored
805 internally. This is also the maximum number of events
806 `recent-keys' can return. By default, 100 events are stored.
808 - Function: set-recent-keys-ring-size size
809 This function changes the number of events stored by XEmacs and
810 returned by `recent-keys'.
812 For example, `(set-recent-keys-ring-size 250)' will make XEmacs
813 remember last 250 events and will make `recent-keys' return last
814 250 events by default.
816 - Command: open-dribble-file filename
817 This function opens a "dribble file" named FILENAME. When a
818 dribble file is open, each input event from the keyboard or mouse
819 (but not those from keyboard macros) is written in that file. A
820 non-character event is expressed using its printed representation
821 surrounded by `<...>'.
823 You close the dribble file by calling this function with an
826 This function is normally used to record the input necessary to
827 trigger an XEmacs bug, for the sake of a bug report.
829 (open-dribble-file "~/dribble")
832 See also the `open-termscript' function (*note Terminal Output::).
835 File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
840 The terminal output functions send output to the terminal or keep
841 track of output sent to the terminal. The function `device-baud-rate'
842 tells you what XEmacs thinks is the output speed of the terminal.
844 - Function: device-baud-rate &optional device
845 This function's value is the output speed of the terminal
846 associated with DEVICE, as far as XEmacs knows. DEVICE defaults
847 to the selected device (usually the only device) if omitted.
848 Changing this value does not change the speed of actual data
849 transmission, but the value is used for calculations such as
850 padding. This value has no effect for window-system devices.
851 (This is different in FSF Emacs, where the baud rate also affects
852 decisions about whether to scroll part of the screen or repaint,
853 even when using a window system.)
855 The value is measured in bits per second.
857 XEmacs attempts to automatically initialize the baud rate by querying
858 the terminal. If you are running across a network, however, and
859 different parts of the network work are at different baud rates, the
860 value returned by XEmacs may be different from the value used by your
861 local terminal. Some network protocols communicate the local terminal
862 speed to the remote machine, so that XEmacs and other programs can get
863 the proper value, but others do not. If XEmacs has the wrong value, it
864 makes decisions that are less than optimal. To fix the problem, use
865 `set-device-baud-rate'.
867 - Function: set-device-baud-rate device baud-rate
868 This function sets the output speed of DEVICE. See
869 `device-baud-rate'. DEVICE defaults to the selected device
870 (usually the only device) if `nil'.
872 - Function: send-string-to-terminal char-or-string &optional stdout-p
874 This function sends CHAR-OR-STRING to the terminal without
875 alteration. Control characters in CHAR-OR-STRING have
876 terminal-dependent effects.
878 If DEVICE is `nil', this function writes to XEmacs's stderr, or to
879 stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
880 tty or stream device, and the function writes to the device's
881 normal or error output, according to STDOUT-P.
883 One use of this function is to define function keys on terminals
884 that have downloadable function key definitions. For example,
885 this is how on certain terminals to define function key 4 to move
886 forward four characters (by transmitting the characters `C-u C-f'
889 (send-string-to-terminal "\eF4\^U\^F")
892 - Command: open-termscript filename
893 This function is used to open a "termscript file" that will record
894 all the characters sent by XEmacs to the terminal. (If there are
895 multiple tty or stream devices, all characters sent to all such
896 devices are recorded.) The function returns `nil'. Termscript
897 files are useful for investigating problems where XEmacs garbles
898 the screen, problems that are due to incorrect Termcap entries or
899 to undesirable settings of terminal options more often than to
900 actual XEmacs bugs. Once you are certain which characters were
901 actually output, you can determine reliably whether they
902 correspond to the Termcap specifications in use.
904 A `nil' value for FILENAME stops recording terminal output.
906 See also `open-dribble-file' in *Note Terminal Input::.
908 (open-termscript "../junk/termscript")
912 File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
917 This section attempts to answer the question "Why does XEmacs choose
918 to use flow-control characters in its command character set?" For a
919 second view on this issue, read the comments on flow control in the
920 `emacs/INSTALL' file from the distribution; for help with Termcap
921 entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
923 At one time, most terminals did not need flow control, and none used
924 `C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
925 `C-q' as command characters was uncontroversial. XEmacs, for economy
926 of keystrokes and portability, used nearly all the ASCII control
927 characters, with mnemonic meanings when possible; thus, `C-s' for
928 search and `C-q' for quote.
930 Later, some terminals were introduced which required these characters
931 for flow control. They were not very good terminals for full-screen
932 editing, so XEmacs maintainers did not pay attention. In later years,
933 flow control with `C-s' and `C-q' became widespread among terminals,
934 but by this time it was usually an option. And the majority of users,
935 who can turn flow control off, were unwilling to switch to less
936 mnemonic key bindings for the sake of flow control.
938 So which usage is "right", XEmacs's or that of some terminal and
939 concentrator manufacturers? This question has no simple answer.
941 One reason why we are reluctant to cater to the problems caused by
942 `C-s' and `C-q' is that they are gratuitous. There are other
943 techniques (albeit less common in practice) for flow control that
944 preserve transparency of the character stream. Note also that their use
945 for flow control is not an official standard. Interestingly, on the
946 model 33 teletype with a paper tape punch (which is very old), `C-s'
947 and `C-q' were sent by the computer to turn the punch on and off!
949 As X servers and other window systems replace character-only
950 terminals, this problem is gradually being cured. For the mean time,
951 XEmacs provides a convenient way of enabling flow control if you want
952 it: call the function `enable-flow-control'.
954 - Command: enable-flow-control &optional argument
955 This function enables use of `C-s' and `C-q' for output flow
956 control, and provides the characters `C-\' and `C-^' as aliases
957 for them using `keyboard-translate-table' (*note Translating
960 With optional argument ARGUMENT (interactively the prefix
961 argument), enable flow control mode if ARGUMENT is positive; else
964 You can use the function `enable-flow-control-on' in your `.emacs'
965 file to enable flow control automatically on certain terminal types.
967 - Function: enable-flow-control-on &rest termtypes
968 This function enables flow control, and the aliases `C-\' and
969 `C-^', if the terminal type is one of TERMTYPES. For example:
971 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
973 Here is how `enable-flow-control' does its job:
975 1. It sets CBREAK mode for terminal input, and tells the operating
976 system to handle flow control, with `(set-input-mode nil t)'.
978 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
979 into `C-s' and `C-q'. Except at its very lowest level, XEmacs
980 never knows that the characters typed were anything but `C-s' and
981 `C-q', so you can in effect type them as `C-\' and `C-^' even when
982 they are input for other commands. *Note Translating Input::.
984 If the terminal is the source of the flow control characters, then
985 once you enable kernel flow control handling, you probably can make do
986 with less padding than normal for that terminal. You can reduce the
987 amount of padding by customizing the Termcap entry. You can also
988 reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
989 a smaller speed when calculating the padding needed. *Note Terminal
993 File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
998 The command line option `-batch' causes XEmacs to run
999 noninteractively. In this mode, XEmacs does not read commands from the
1000 terminal, it does not alter the terminal modes, and it does not expect
1001 to be outputting to an erasable screen. The idea is that you specify
1002 Lisp programs to run; when they are finished, XEmacs should exit. The
1003 way to specify the programs to run is with `-l FILE', which loads the
1004 library named FILE, and `-f FUNCTION', which calls FUNCTION with no
1007 Any Lisp program output that would normally go to the echo area,
1008 either using `message' or using `prin1', etc., with `t' as the stream,
1009 goes instead to XEmacs's standard error descriptor when in batch mode.
1010 Thus, XEmacs behaves much like a noninteractive application program.
1011 (The echo area output that XEmacs itself normally generates, such as
1012 command echoing, is suppressed entirely.)
1014 - Function: noninteractive
1015 This function returns non-`nil' when XEmacs is running in batch
1018 - Variable: noninteractive
1019 This variable is non-`nil' when XEmacs is running in batch mode.
1020 Setting this variable to `nil', however, will not change whether
1021 XEmacs is running in batch mode, and will not change the return
1022 value of the `noninteractive' function.
1025 File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
1027 Functions Specific to the X Window System
1028 *****************************************
1030 XEmacs provides the concept of "devices", which generalizes
1031 connections to an X server, a TTY device, etc. Most information about
1032 an X server that XEmacs is connected to can be determined through
1033 general console and device functions. *Note Consoles and Devices::.
1034 However, there are some features of the X Window System that do not
1035 generalize well, and they are covered specially here.
1039 * X Selections:: Transferring text to and from other X clients.
1040 * X Server:: Information about the X server connected to
1041 a particular device.
1042 * X Miscellaneous:: Other X-specific functions and variables.
1045 File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
1050 The X server records a set of "selections" which permit transfer of
1051 data between application programs. The various selections are
1052 distinguished by "selection types", represented in XEmacs by symbols.
1053 X clients including XEmacs can read or set the selection for any given
1056 - Function: x-own-selection data &optional type
1057 This function sets a "selection" in the X server. It takes two
1058 arguments: a value, DATA, and the selection type TYPE to assign it
1059 to. DATA may be a string, a cons of two markers, or an extent.
1060 In the latter cases, the selection is considered to be the text
1061 between the markers, or between the extent's endpoints.
1063 Each possible TYPE has its own selection value, which changes
1064 independently. The usual values of TYPE are `PRIMARY' and
1065 `SECONDARY'; these are symbols with upper-case names, in accord
1066 with X Windows conventions. The default is `PRIMARY'.
1068 (In FSF Emacs, this function is called `x-set-selection' and takes
1069 different arguments.)
1071 - Function: x-get-selection
1072 This function accesses selections set up by XEmacs or by other X
1073 clients. It returns the value of the current primary selection.
1075 - Function: x-disown-selection &optional secondary-p
1076 Assuming we own the selection, this function disowns it. If
1077 SECONDARY-P is non-`nil', the secondary selection instead of the
1078 primary selection is discarded.
1080 The X server also has a set of numbered "cut buffers" which can
1081 store text or other data being moved between applications. Cut buffers
1082 are considered obsolete, but XEmacs supports them for the sake of X
1083 clients that still use them.
1085 - Function: x-get-cutbuffer &optional n
1086 This function returns the contents of cut buffer number N. (This
1087 function is called `x-get-cut-buffer' in FSF Emacs.)
1089 - Function: x-store-cutbuffer string &optional push
1090 This function stores STRING into the first cut buffer (cut buffer
1093 Normally, the contents of the first cut buffer are simply replaced
1094 by STRING. However, if optional argument PUSH is non-`nil', the
1095 cut buffers are rotated. This means that the previous value of
1096 the first cut buffer moves to the second cut buffer, and the
1097 second to the third, and so on, moving the other values down
1098 through the series of cut buffers, kill-ring-style. There are 8
1099 cut buffers altogether.
1101 Cut buffers are considered obsolete; you should use selections
1104 This function has no effect if support for cut buffers was not
1107 This function is called `x-set-cut-buffer' in FSF Emacs.
1110 File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
1115 This section describes how to access and change the overall status of
1116 the X server XEmacs is using.
1120 * Resources:: Getting resource values from the server.
1121 * Server Data:: Getting info about the X server.
1122 * Grabs:: Restricting access to the server by other apps.
1125 File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
1130 - Function: default-x-device
1131 This function return the default X device for resourcing. This is
1132 the first-created X device that still exists.
1134 - Function: x-get-resource name class type &optional locale device
1136 This function retrieves a resource value from the X resource
1139 * The first arg is the name of the resource to retrieve, such as
1142 * The second arg is the class of the resource to retrieve, like
1145 * The third arg should be one of the symbols `string',
1146 `integer', `natnum', or `boolean', specifying the type of
1147 object that the database is searched for.
1149 * The fourth arg is the locale to search for the resources on,
1150 and can currently be a a buffer, a frame, a device, or the
1151 symbol `global'. If omitted, it defaults to `global'.
1153 * The fifth arg is the device to search for the resources on.
1154 (The resource database for a particular device is constructed
1155 by combining non-device- specific resources such any
1156 command-line resources specified and any app-defaults files
1157 found [or the fallback resources supplied by XEmacs, if no
1158 app-defaults file is found] with device-specific resources
1159 such as those supplied using `xrdb'.) If omitted, it defaults
1160 to the device of LOCALE, if a device can be derived (i.e. if
1161 LOCALE is a frame or device), and otherwise defaults to the
1162 value of `default-x-device'.
1164 * The sixth arg NOERROR, if non-`nil', means do not signal an
1165 error if a bogus resource specification was retrieved (e.g.
1166 if a non-integer was given when an integer was requested).
1167 In this case, a warning is issued instead.
1169 The resource names passed to this function are looked up relative
1172 If you want to search for a subresource, you just need to specify
1173 the resource levels in NAME and CLASS. For example, NAME could be
1174 `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
1178 1. If LOCALE is a buffer, a call
1180 `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
1182 is an interface to a C call something like
1184 `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
1185 "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
1188 2. If LOCALE is a frame, a call
1190 `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
1192 is an interface to a C call something like
1194 `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
1195 "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
1198 3. If LOCALE is a device, a call
1200 `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
1202 is an interface to a C call something like
1204 `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
1205 "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
1208 4. If LOCALE is the symbol `global', a call
1210 `(x-get-resource "foreground" "Foreground" 'string 'global)'
1212 is an interface to a C call something like
1214 `XrmGetResource (db, "xemacs.foreground",
1218 Note that for `global', no prefix is added other than that of the
1219 application itself; thus, you can use this locale to retrieve
1220 arbitrary application resources, if you really want to.
1222 The returned value of this function is `nil' if the queried
1223 resource is not found. If TYPE is `string', a string is returned,
1224 and if it is `integer', an integer is returned. If TYPE is
1225 `boolean', then the returned value is the list `(t)' for true,
1226 `(nil)' for false, and is `nil' to mean "unspecified".
1228 - Function: x-put-resource resource-line &optional device
1229 This function adds a resource to the resource database for DEVICE.
1230 RESOURCE-LINE specifies the resource to add and should be a
1231 standard resource specification.
1233 - Variable: x-emacs-application-class
1234 This variable holds The X application class of the XEmacs process.
1235 This controls, among other things, the name of the "app-defaults"
1236 file that XEmacs will use. For changes to this variable to take
1237 effect, they must be made before the connection to the X server is
1238 initialized, that is, this variable may only be changed before
1239 XEmacs is dumped, or by setting it in the file
1240 `lisp/term/x-win.el'.
1242 By default, this variable is `nil' at startup. When the connection
1243 to the X server is first initialized, the X resource database will
1244 be consulted and the value will be set according to whether any
1245 resources are found for the application class "XEmacs".
1248 File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
1250 Data about the X Server
1251 -----------------------
1253 This section describes functions and a variable that you can use to
1254 get information about the capabilities and origin of the X server
1255 corresponding to a particular device. The device argument is generally
1256 optional and defaults to the selected device.
1258 - Function: x-server-version &optional device
1259 This function returns the list of version numbers of the X server
1260 DEVICE is on. The returned value is a list of three integers: the
1261 major and minor version numbers of the X protocol in use, and the
1262 vendor-specific release number.
1264 - Function: x-server-vendor &optional device
1265 This function returns the vendor supporting the X server DEVICE is
1268 - Function: x-display-visual-class &optional device
1269 This function returns the visual class of the display DEVICE is
1270 on. The value is one of the symbols `static-gray', `gray-scale',
1271 `static-color', `pseudo-color', `true-color', and `direct-color'.
1272 (Note that this is different from previous versions of XEmacs,
1273 which returned `StaticGray', `GrayScale', etc.)
projects / chise / xemacs-chise.git- / blob