1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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 Interface, Next: X-Windows, Prev: Processes, Up: Top
55 Operating System Interface
56 **************************
58 This chapter is about starting and getting out of Emacs, access to
59 values in the operating system environment, and terminal input, output,
62 *Note Building XEmacs::, for related information. See also *Note
63 Display::, for additional operating system status information
64 pertaining to the terminal and the screen.
68 * Starting Up:: Customizing XEmacs start-up processing.
69 * Getting Out:: How exiting works (permanent or temporary).
70 * System Environment:: Distinguish the name and kind of system.
71 * User Identification:: Finding the name and user id of the user.
72 * Time of Day:: Getting the current time.
73 * Time Conversion:: Converting a time from numeric form to a string, or
74 to calendrical data (or vice versa).
75 * Timers:: Setting a timer to call a function at a certain time.
76 * Terminal Input:: Recording terminal input for debugging.
77 * Terminal Output:: Recording terminal output for debugging.
78 * Flow Control:: How to turn output flow control on or off.
79 * Batch Mode:: Running XEmacs without terminal interaction.
82 File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
87 This section describes what XEmacs does when it is started, and how
88 you can customize these actions.
92 * Start-up Summary:: Sequence of actions XEmacs performs at start-up.
93 * Init File:: Details on reading the init file (`.emacs').
94 * Terminal-Specific:: How the terminal-specific Lisp file is read.
95 * Command Line Arguments:: How command line arguments are processed,
96 and how you can customize them.
99 File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
101 Summary: Sequence of Actions at Start Up
102 ----------------------------------------
104 The order of operations performed (in `startup.el') by XEmacs when
105 it is started up is as follows:
107 1. It loads the initialization library for the window system, if you
108 are using a window system. This library's name is
109 `term/WINDOWSYSTEM-win.el'.
111 2. It processes the initial options. (Some of them are handled even
114 3. It initializes the X window frame and faces, if appropriate.
116 4. It runs the normal hook `before-init-hook'.
118 5. It loads the library `site-start', unless the option
119 `-no-site-file' was specified. The library's file name is usually
122 6. It loads the file `~/.emacs' unless `-q' was specified on the
123 command line. (This is not done in `-batch' mode.) The `-u'
124 option can specify the user name whose home directory should be
127 7. It loads the library `default' unless `inhibit-default-init' is
128 non-`nil'. (This is not done in `-batch' mode or if `-q' was
129 specified on the command line.) The library's file name is
130 usually `default.el'.
132 8. It runs the normal hook `after-init-hook'.
134 9. It sets the major mode according to `initial-major-mode', provided
135 the buffer `*scratch*' is still current and still in Fundamental
138 10. It loads the terminal-specific Lisp file, if any, except when in
139 batch mode or using a window system.
141 11. It displays the initial echo area message, unless you have
142 suppressed that with `inhibit-startup-echo-area-message'.
144 12. It processes the action arguments from the command line.
146 13. It runs `term-setup-hook'.
148 14. It calls `frame-notice-user-settings', which modifies the
149 parameters of the selected frame according to whatever the init
152 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
154 16. It displays copyleft, nonwarranty, and basic use information,
155 provided there were no remaining command line arguments (a few
156 steps above) and the value of `inhibit-startup-message' is `nil'.
158 - User Option: inhibit-startup-message
159 This variable inhibits the initial startup messages (the
160 nonwarranty, etc.). If it is non-`nil', then the messages are not
163 This variable exists so you can set it in your personal init file,
164 once you are familiar with the contents of the startup message.
165 Do not set this variable in the init file of a new user, or in a
166 way that affects more than one user, because that would prevent
167 new users from receiving the information they are supposed to see.
169 - User Option: inhibit-startup-echo-area-message
170 This variable controls the display of the startup echo area
171 message. You can suppress the startup echo area message by adding
172 text with this form to your `.emacs' file:
174 (setq inhibit-startup-echo-area-message
177 Simply setting `inhibit-startup-echo-area-message' to your login
178 name is not sufficient to inhibit the message; Emacs explicitly
179 checks whether `.emacs' contains an expression as shown above.
180 Your login name must appear in the expression as a Lisp string
183 This way, you can easily inhibit the message for yourself if you
184 wish, but thoughtless copying of your `.emacs' file will not
185 inhibit the message for someone else.
188 File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
190 The Init File: `.emacs'
191 -----------------------
193 When you start XEmacs, it normally attempts to load the file
194 `.emacs' from your home directory. This file, if it exists, must
195 contain Lisp code. It is called your "init file". The command line
196 switches `-q' and `-u' affect the use of the init file; `-q' says not
197 to load an init file, and `-u' says to load a specified user's init
198 file instead of yours. *Note Entering XEmacs: (xemacs)Entering XEmacs.
200 A site may have a "default init file", which is the library named
201 `default.el'. XEmacs finds the `default.el' file through the standard
202 search path for libraries (*note How Programs Do Loading::.). The
203 XEmacs distribution does not come with this file; sites may provide one
204 for local customizations. If the default init file exists, it is
205 loaded whenever you start Emacs, except in batch mode or if `-q' is
206 specified. But your own personal init file, if any, is loaded first; if
207 it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
208 not subsequently load the `default.el' file.
210 Another file for site-customization is `site-start.el'. Emacs loads
211 this *before* the user's init file. You can inhibit the loading of
212 this file with the option `-no-site-file'.
214 - Variable: site-run-file
215 This variable specifies the site-customization file to load before
216 the user's init file. Its normal value is `"site-start"'.
218 If there is a great deal of code in your `.emacs' file, you should
219 move it into another file named `SOMETHING.el', byte-compile it (*note
220 Byte Compilation::.), and make your `.emacs' file load the other file
221 using `load' (*note Loading::.).
223 *Note Init File Examples: (xemacs)Init File Examples, for examples
224 of how to make various commonly desired customizations in your `.emacs'
227 - User Option: inhibit-default-init
228 This variable prevents XEmacs from loading the default
229 initialization library file for your session of XEmacs. If its
230 value is non-`nil', then the default library is not loaded. The
231 default value is `nil'.
233 - Variable: before-init-hook
234 - Variable: after-init-hook
235 These two normal hooks are run just before, and just after,
236 loading of the user's init file, `default.el', and/or
240 File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
242 Terminal-Specific Initialization
243 --------------------------------
245 Each terminal type can have its own Lisp library that XEmacs loads
246 when run on that type of terminal. For a terminal type named TERMTYPE,
247 the library is called `term/TERMTYPE'. XEmacs finds the file by
248 searching the `load-path' directories as it does for other files, and
249 trying the `.elc' and `.el' suffixes. Normally, terminal-specific Lisp
250 library is located in `emacs/lisp/term', a subdirectory of the
251 `emacs/lisp' directory in which most XEmacs Lisp libraries are kept.
253 The library's name is constructed by concatenating the value of the
254 variable `term-file-prefix' and the terminal type. Normally,
255 `term-file-prefix' has the value `"term/"'; changing this is not
258 The usual function of a terminal-specific library is to enable
259 special keys to send sequences that XEmacs can recognize. It may also
260 need to set or add to `function-key-map' if the Termcap entry does not
261 specify all the terminal's function keys. *Note Terminal Input::.
263 When the name of the terminal type contains a hyphen, only the part
264 of the name before the first hyphen is significant in choosing the
265 library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
266 the `term/aaa' library. If necessary, the library can evaluate
267 `(getenv "TERM")' to find the full name of the terminal type.
269 Your `.emacs' file can prevent the loading of the terminal-specific
270 library by setting the variable `term-file-prefix' to `nil'. This
271 feature is useful when experimenting with your own peculiar
274 You can also arrange to override some of the actions of the
275 terminal-specific library by setting the variable `term-setup-hook'.
276 This is a normal hook which XEmacs runs using `run-hooks' at the end of
277 XEmacs initialization, after loading both your `.emacs' file and any
278 terminal-specific libraries. You can use this variable to define
279 initializations for terminals that do not have their own libraries.
282 - Variable: term-file-prefix
283 If the `term-file-prefix' variable is non-`nil', XEmacs loads a
284 terminal-specific initialization file as follows:
286 (load (concat term-file-prefix (getenv "TERM")))
288 You may set the `term-file-prefix' variable to `nil' in your
289 `.emacs' file if you do not wish to load the
290 terminal-initialization file. To do this, put the following in
291 your `.emacs' file: `(setq term-file-prefix nil)'.
293 - Variable: term-setup-hook
294 This variable is a normal hook that XEmacs runs after loading your
295 `.emacs' file, the default initialization file (if any) and the
296 terminal-specific Lisp file.
298 You can use `term-setup-hook' to override the definitions made by a
299 terminal-specific file.
301 - Variable: window-setup-hook
302 This variable is a normal hook which XEmacs runs after loading your
303 `.emacs' file and the default initialization file (if any), after
304 loading terminal-specific Lisp code, and after running the hook
308 File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
310 Command Line Arguments
311 ----------------------
313 You can use command line arguments to request various actions when
314 you start XEmacs. Since you do not need to start XEmacs more than once
315 per day, and will often leave your XEmacs session running longer than
316 that, command line arguments are hardly ever used. As a practical
317 matter, it is best to avoid making the habit of using them, since this
318 habit would encourage you to kill and restart XEmacs unnecessarily
319 often. These options exist for two reasons: to be compatible with
320 other editors (for invocation by other programs) and to enable shell
321 scripts to run specific Lisp programs.
323 This section describes how Emacs processes command line arguments,
324 and how you can customize them.
326 - Function: command-line
327 This function parses the command line that XEmacs was called with,
328 processes it, loads the user's `.emacs' file and displays the
331 - Variable: command-line-processed
332 The value of this variable is `t' once the command line has been
335 If you redump XEmacs by calling `dump-emacs', you may wish to set
336 this variable to `nil' first in order to cause the new dumped
337 XEmacs to process its new command line arguments.
339 - Variable: command-switch-alist
340 The value of this variable is an alist of user-defined command-line
341 options and associated handler functions. This variable exists so
342 you can add elements to it.
344 A "command line option" is an argument on the command line of the
349 The elements of the `command-switch-alist' look like this:
351 (OPTION . HANDLER-FUNCTION)
353 The HANDLER-FUNCTION is called to handle OPTION and receives the
354 option name as its sole argument.
356 In some cases, the option is followed in the command line by an
357 argument. In these cases, the HANDLER-FUNCTION can find all the
358 remaining command-line arguments in the variable
359 `command-line-args-left'. (The entire list of command-line
360 arguments is in `command-line-args'.)
362 The command line arguments are parsed by the `command-line-1'
363 function in the `startup.el' file. See also *Note Command Line
364 Switches and Arguments: (xemacs)Command Switches.
366 - Variable: command-line-args
367 The value of this variable is the list of command line arguments
370 - Variable: command-line-functions
371 This variable's value is a list of functions for handling an
372 unrecognized command-line argument. Each time the next argument
373 to be processed has no special meaning, the functions in this list
374 are called, in order of appearance, until one of them returns a
377 These functions are called with no arguments. They can access the
378 command-line argument under consideration through the variable
379 `argi'. The remaining arguments (not including the current one)
380 are in the variable `command-line-args-left'.
382 When a function recognizes and processes the argument in `argi', it
383 should return a non-`nil' value to say it has dealt with that
384 argument. If it has also dealt with some of the following
385 arguments, it can indicate that by deleting them from
386 `command-line-args-left'.
388 If all of these functions return `nil', then the argument is used
389 as a file name to visit.
392 File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
394 Getting out of XEmacs
395 =====================
397 There are two ways to get out of XEmacs: you can kill the XEmacs job,
398 which exits permanently, or you can suspend it, which permits you to
399 reenter the XEmacs process later. As a practical matter, you seldom
400 kill XEmacs--only when you are about to log out. Suspending is much
405 * Killing XEmacs:: Exiting XEmacs irreversibly.
406 * Suspending XEmacs:: Exiting XEmacs reversibly.
409 File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
414 Killing XEmacs means ending the execution of the XEmacs process. The
415 parent process normally resumes control. The low-level primitive for
416 killing XEmacs is `kill-emacs'.
418 - Function: kill-emacs &optional EXIT-DATA
419 This function exits the XEmacs process and kills it.
421 If EXIT-DATA is an integer, then it is used as the exit status of
422 the XEmacs process. (This is useful primarily in batch operation;
423 see *Note Batch Mode::.)
425 If EXIT-DATA is a string, its contents are stuffed into the
426 terminal input buffer so that the shell (or whatever program next
427 reads input) can read them.
429 All the information in the XEmacs process, aside from files that have
430 been saved, is lost when the XEmacs is killed. Because killing XEmacs
431 inadvertently can lose a lot of work, XEmacs queries for confirmation
432 before actually terminating if you have buffers that need saving or
433 subprocesses that are running. This is done in the function
434 `save-buffers-kill-emacs'.
436 - Variable: kill-emacs-query-functions
437 After asking the standard questions, `save-buffers-kill-emacs'
438 calls the functions in the list `kill-buffer-query-functions', in
439 order of appearance, with no arguments. These functions can ask
440 for additional confirmation from the user. If any of them returns
441 non-`nil', XEmacs is not killed.
443 - Variable: kill-emacs-hook
444 This variable is a normal hook; once `save-buffers-kill-emacs' is
445 finished with all file saving and confirmation, it runs the
446 functions in this hook.
449 File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out
454 "Suspending XEmacs" means stopping XEmacs temporarily and returning
455 control to its superior process, which is usually the shell. This
456 allows you to resume editing later in the same XEmacs process, with the
457 same buffers, the same kill ring, the same undo history, and so on. To
458 resume XEmacs, use the appropriate command in the parent shell--most
461 Some operating systems do not support suspension of jobs; on these
462 systems, "suspension" actually creates a new shell temporarily as a
463 subprocess of XEmacs. Then you would exit the shell to return to
466 Suspension is not useful with window systems such as X, because the
467 XEmacs job may not have a parent that can resume it again, and in any
468 case you can give input to some other job such as a shell merely by
469 moving to a different window. Therefore, suspending is not allowed
470 when XEmacs is an X client.
472 - Function: suspend-emacs STRING
473 This function stops XEmacs and returns control to the superior
474 process. If and when the superior process resumes XEmacs,
475 `suspend-emacs' returns `nil' to its caller in Lisp.
477 If STRING is non-`nil', its characters are sent to be read as
478 terminal input by XEmacs's superior shell. The characters in
479 STRING are not echoed by the superior shell; only the results
482 Before suspending, `suspend-emacs' runs the normal hook
483 `suspend-hook'. In Emacs version 18, `suspend-hook' was not a
484 normal hook; its value was a single function, and if its value was
485 non-`nil', then `suspend-emacs' returned immediately without
486 actually suspending anything.
488 After the user resumes XEmacs, `suspend-emacs' runs the normal hook
489 `suspend-resume-hook'. *Note Hooks::.
491 The next redisplay after resumption will redraw the entire screen,
492 unless the variable `no-redraw-on-reenter' is non-`nil' (*note
495 In the following example, note that `pwd' is not echoed after
496 XEmacs is suspended. But it is read and executed by the shell.
501 (add-hook 'suspend-hook
505 (error "Suspend cancelled")))))
507 (or (y-or-n-p "Really suspend? ")
508 (error "Suspend cancelled")))
510 (add-hook 'suspend-resume-hook
511 (function (lambda () (message "Resumed!"))))
512 => (lambda nil (message "Resumed!"))
514 (suspend-emacs "pwd")
517 ---------- Buffer: Minibuffer ----------
519 ---------- Buffer: Minibuffer ----------
521 ---------- Parent Shell ----------
522 lewis@slug[23] % /user/lewis/manual
525 ---------- Echo Area ----------
528 - Variable: suspend-hook
529 This variable is a normal hook run before suspending.
531 - Variable: suspend-resume-hook
532 This variable is a normal hook run after suspending.
535 File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
537 Operating System Environment
538 ============================
540 XEmacs provides access to variables in the operating system
541 environment through various functions. These variables include the
542 name of the system, the user's UID, and so on.
544 - Variable: system-type
545 The value of this variable is a symbol indicating the type of
546 operating system XEmacs is operating on. Here is a table of the
556 Data General DGUX operating system.
559 A GNU system using the GNU HURD and Mach.
562 Hewlett-Packard HPUX operating system.
565 Silicon Graphics Irix system.
568 A GNU system using the Linux kernel.
571 Microsoft MS-DOS "operating system."
574 NeXT Mach-based system.
577 Masscomp RTU, UCB universe.
589 Microsoft windows NT.
594 We do not wish to add new symbols to make finer distinctions
595 unless it is absolutely necessary! In fact, we hope to eliminate
596 some of these alternatives in the future. We recommend using
597 `system-configuration' to distinguish between different operating
600 - Variable: system-configuration
601 This variable holds the three-part configuration name for the
602 hardware/software configuration of your system, as a string. The
603 convenient way to test parts of this string is with `string-match'.
605 - Function: system-name
606 This function returns the name of the machine you are running on.
610 The symbol `system-name' is a variable as well as a function. In
611 fact, the function returns whatever value the variable `system-name'
612 currently holds. Thus, you can set the variable `system-name' in case
613 Emacs is confused about the name of your system. The variable is also
614 useful for constructing frame titles (*note Frame Titles::.).
616 - Variable: mail-host-address
617 If this variable is non-`nil', it is used instead of `system-name'
618 for purposes of generating email addresses. For example, it is
619 used when constructing the default value of `user-mail-address'.
620 *Note User Identification::. (Since this is done when XEmacs
621 starts up, the value actually used is the one saved when XEmacs
622 was dumped. *Note Building XEmacs::.)
624 - Function: getenv VAR
625 This function returns the value of the environment variable VAR,
626 as a string. Within XEmacs, the environment variable values are
627 kept in the Lisp variable `process-environment'.
632 lewis@slug[10] % printenv
633 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
639 - Command: setenv VARIABLE VALUE
640 This command sets the value of the environment variable named
641 VARIABLE to VALUE. Both arguments should be strings. This
642 function works by modifying `process-environment'; binding that
643 variable with `let' is also reasonable practice.
645 - Variable: process-environment
646 This variable is a list of strings, each describing one environment
647 variable. The functions `getenv' and `setenv' work by means of
651 => ("l=/usr/stanford/lib/gnuemacs/lisp"
652 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
659 - Variable: path-separator
660 This variable holds a string which says which character separates
661 directories in a search path (as found in an environment
662 variable). Its value is `":"' for Unix and GNU systems, and `";"'
663 for MS-DOS and Windows NT.
665 - Variable: invocation-name
666 This variable holds the program name under which Emacs was
667 invoked. The value is a string, and does not include a directory
670 - Variable: invocation-directory
671 This variable holds the directory from which the Emacs executable
672 was invoked, or perhaps `nil' if that directory cannot be
675 - Variable: installation-directory
676 If non-`nil', this is a directory within which to look for the
677 `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
678 can't find those directories in their standard installed
679 locations, but can find them in a directory related somehow to the
680 one containing the Emacs executable.
682 - Function: load-average &optional USE-FLOATS
683 This function returns a list of the current 1-minute, 5-minute and
684 15-minute load averages. The values are integers that are 100
685 times the system load averages. (The load averages indicate the
686 number of processes trying to run.)
688 When USE-FLOATS is non-`nil', floats will be returned instead of
689 integers. These floats are not multiplied by 100.
694 => (1.69921875 1.58984375 1.640625)
696 lewis@rocky[5] % uptime
697 8:06pm up 16 day(s), 21:57, 40 users,
698 load average: 1.68, 1.59, 1.64
700 If the 5-minute or 15-minute load averages are not available,
701 return a shortened list, containing only those averages which are
704 On some systems, this function may require special privileges to
705 run, or it may be unimplemented for the particular system type.
706 In that case, the function will signal an error.
708 - Function: emacs-pid
709 This function returns the process ID of the Emacs process.
711 - Function: setprv PRIVILEGE-NAME &optional SETP GETPRV
712 This function sets or resets a VMS privilege. (It does not exist
713 on Unix.) The first arg is the privilege name, as a string. The
714 second argument, SETP, is `t' or `nil', indicating whether the
715 privilege is to be turned on or off. Its default is `nil'. The
716 function returns `t' if successful, `nil' otherwise.
718 If the third argument, GETPRV, is non-`nil', `setprv' does not
719 change the privilege, but returns `t' or `nil' indicating whether
720 the privilege is currently enabled.
723 File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
728 - Variable: user-mail-address
729 This holds the nominal email address of the user who is using
730 Emacs. When Emacs starts up, it computes a default value that is
731 usually right, but users often set this themselves when the
732 default value is not right.
734 - Function: user-login-name &optional UID
735 If you don't specify UID, this function returns the name under
736 which the user is logged in. If the environment variable `LOGNAME'
737 is set, that value is used. Otherwise, if the environment variable
738 `USER' is set, that value is used. Otherwise, the value is based
739 on the effective UID, not the real UID.
741 If you specify UID, the value is the user name that corresponds to
742 UID (which should be an integer).
747 - Function: user-real-login-name
748 This function returns the user name corresponding to Emacs's real
749 UID. This ignores the effective UID and ignores the environment
750 variables `LOGNAME' and `USER'.
752 - Variable: user-full-name
753 This variable holds the name of the user running this Emacs. It is
754 initialized at startup time from the value of `NAME' environment
755 variable. You can change the value of this variable to alter the
756 result of the `user-full-name' function.
758 - Function: user-full-name &optional USER
759 This function returns the full name of USER. If USER is `nil', it
760 defaults to the user running this Emacs. In that case, the value
761 of `user-full-name' variable, if non-`nil', will be used.
763 If USER is specified explicitly, `user-full-name' variable is
768 (setq user-full-name "Hrvoje \"Niksa\" Niksic")
770 => "Hrvoje \"Niksa\" Niksic"
771 (user-full-name "hniksic")
774 The symbols `user-login-name', `user-real-login-name' and
775 `user-full-name' are variables as well as functions. The functions
776 return the same values that the variables hold. These variables allow
777 you to "fake out" Emacs by telling the functions what to return. The
778 variables are also useful for constructing frame titles (*note Frame
781 - Function: user-real-uid
782 This function returns the real UID of the user.
788 This function returns the effective UID of the user.
790 - Function: user-home-directory
791 This function returns the "`HOME'" directory of the user, and is
792 intended to replace occurrences of "`(getenv "HOME")'". Under
793 Unix systems, the following is done:
795 1. Return the value of "`(getenv "HOME")'", if set.
797 2. Return "/", as a fallback, but issue a warning. (Future
798 versions of XEmacs will also attempt to lookup the `HOME'
799 directory via `getpwent()', but this has not yet been
802 Under MS Windows, this is done:
804 1. Return the value of "`(getenv "HOME")'", if set.
806 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
807 both set, return the concatenation (the following description
808 uses MS Windows environment variable substitution syntax):
809 `%HOMEDRIVE%%HOMEDIR%'.
811 3. Return "C:\", as a fallback, but issue a warning.
814 File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
819 This section explains how to determine the current time and the time
822 - Function: current-time-string &optional TIME-VALUE
823 This function returns the current time and date as a
824 humanly-readable string. The format of the string is unvarying;
825 the number of characters used for each part is always the same, so
826 you can reliably use `substring' to extract pieces of it. It is
827 wise to count the characters from the beginning of the string
828 rather than from the end, as additional information may be added
831 The argument TIME-VALUE, if given, specifies a time to format
832 instead of the current time. The argument should be a list whose
833 first two elements are integers. Thus, you can use times obtained
834 from `current-time' (see below) and from `file-attributes' (*note
837 (current-time-string)
838 => "Wed Oct 14 22:21:05 1987"
840 - Function: current-time
841 This function returns the system's time value as a list of three
842 integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
843 combine to give the number of seconds since 0:00 January 1, 1970,
844 which is HIGH * 2**16 + LOW.
846 The third element, MICROSEC, gives the microseconds since the
847 start of the current second (or 0 for systems that return time
848 only on the resolution of a second).
850 The first two elements can be compared with file time values such
851 as you get with the function `file-attributes'. *Note File
854 - Function: current-time-zone &optional TIME-VALUE
855 This function returns a list describing the time zone that the
858 The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
859 giving the number of seconds ahead of UTC (east of Greenwich). A
860 negative value means west of Greenwich. The second element, NAME
861 is a string giving the name of the time zone. Both elements
862 change when daylight savings time begins or ends; if the user has
863 specified a time zone that does not use a seasonal time
864 adjustment, then the value is constant through time.
866 If the operating system doesn't supply all the information
867 necessary to compute the value, both elements of the list are
870 The argument TIME-VALUE, if given, specifies a time to analyze
871 instead of the current time. The argument should be a cons cell
872 containing two integers, or a list whose first two elements are
873 integers. Thus, you can use times obtained from `current-time'
874 (see above) and from `file-attributes' (*note File Attributes::.).
877 File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
882 These functions convert time values (lists of two or three integers)
883 to strings or to calendrical information. There is also a function to
884 convert calendrical information to a time value. You can get time
885 values from the functions `current-time' (*note Time of Day::.) and
886 `file-attributes' (*note File Attributes::.).
888 - Function: format-time-string FORMAT-STRING &optional TIME
889 This function converts TIME to a string according to
890 FORMAT-STRING. If TIME is omitted, it defaults to the current
891 time. The argument FORMAT-STRING may contain `%'-sequences which
892 say to substitute parts of the time. Here is a table of what the
896 This stands for the abbreviated name of the day of week.
899 This stands for the full name of the day of week.
902 This stands for the abbreviated name of the month.
905 This stands for the full name of the month.
908 This is a synonym for `%x %X'.
911 This has a locale-specific meaning. In the default locale
912 (named C), it is equivalent to `%A, %B %e, %Y'.
915 This stands for the day of month, zero-padded.
918 This is a synonym for `%m/%d/%y'.
921 This stands for the day of month, blank-padded.
924 This is a synonym for `%b'.
927 This stands for the hour (00-23).
930 This stands for the hour (00-12).
933 This stands for the day of the year (001-366).
936 This stands for the hour (0-23), blank padded.
939 This stands for the hour (1-12), blank padded.
942 This stands for the month (01-12).
945 This stands for the minute (00-59).
948 This stands for a newline.
951 This stands for `AM' or `PM', as appropriate.
954 This is a synonym for `%I:%M:%S %p'.
957 This is a synonym for `%H:%M'.
960 This stands for the seconds (00-60).
963 This stands for a tab character.
966 This is a synonym for `%H:%M:%S'.
969 This stands for the week of the year (01-52), assuming that
970 weeks start on Sunday.
973 This stands for the numeric day of week (0-6). Sunday is day
977 This stands for the week of the year (01-52), assuming that
978 weeks start on Monday.
981 This has a locale-specific meaning. In the default locale
982 (named C), it is equivalent to `%D'.
985 This has a locale-specific meaning. In the default locale
986 (named C), it is equivalent to `%T'.
989 This stands for the year without century (00-99).
992 This stands for the year with century.
995 This stands for the time zone abbreviation.
997 - Function: decode-time TIME
998 This function converts a time value into calendrical information.
999 The return value is a list of nine elements, as follows:
1001 (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
1003 Here is what the elements mean:
1006 The number of seconds past the minute, as an integer between
1010 The number of minutes past the hour, as an integer between 0
1014 The hour of the day, as an integer between 0 and 23.
1017 The day of the month, as an integer between 1 and 31.
1020 The month of the year, as an integer between 1 and 12.
1023 The year, an integer typically greater than 1900.
1026 The day of week, as an integer between 0 and 6, where 0
1030 `t' if daylight savings time is effect, otherwise `nil'.
1033 An integer indicating the time zone, as the number of seconds
1036 Note that Common Lisp has different meanings for DOW and ZONE.
1038 - Function: encode-time SECONDS MINUTES HOUR DAY MONTH YEAR &optional
1040 This function is the inverse of `decode-time'. It converts seven
1041 items of calendrical data into a time value. For the meanings of
1042 the arguments, see the table above under `decode-time'.
1044 Year numbers less than 100 are treated just like other year
1045 numbers. If you want them to stand for years above 1900, you must
1046 alter them yourself before you call `encode-time'.
1048 The optional argument ZONE defaults to the current time zone and
1049 its daylight savings time rules. If specified, it can be either a
1050 list (as you would get from `current-time-zone') or an integer (as
1051 you would get from `decode-time'). The specified zone is used
1052 without any further alteration for daylight savings time.
1055 File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
1057 Timers for Delayed Execution
1058 ============================
1060 You can set up a timer to call a function at a specified future time.
1062 - Function: add-timeout SECS FUNCTION OBJECT &optional RESIGNAL
1063 This function adds a timeout, to be signaled after the timeout
1064 period has elapsed. SECS is a number of seconds, expressed as an
1065 integer or a float. FUNCTION will be called after that many
1066 seconds have elapsed, with one argument, the given OBJECT. If the
1067 optional RESIGNAL argument is provided, then after this timeout
1068 expires, `add-timeout' will automatically be called again with
1069 RESIGNAL as the first argument.
1071 This function returns an object which is the "id" of this
1072 particular timeout. You can pass that object to `disable-timeout'
1073 to turn off the timeout before it has been signalled.
1075 The number of seconds may be expressed as a floating-point number,
1076 in which case some fractional part of a second will be used.
1077 Caveat: the usable timeout granularity will vary from system to
1080 Adding a timeout causes a timeout event to be returned by
1081 `next-event', and the function will be invoked by
1082 `dispatch-event', so if XEmacs is in a tight loop, the function
1083 will not be invoked until the next call to sit-for or until the
1084 return to top-level (the same is true of process filters).
1086 WARNING: if you are thinking of calling add-timeout from inside of
1087 a callback function as a way of resignalling a timeout, think
1088 again. There is a race condition. That's why the RESIGNAL
1091 (NOTE: In FSF Emacs, this function is called `run-at-time' and has
1092 different semantics.)
1094 - Function: disable-timeout ID
1095 Cancel the requested action for ID, which should be a value
1096 previously returned by `add-timeout'. This cancels the effect of
1097 that call to `add-timeout'; the arrival of the specified time will
1098 not cause anything special to happen. (NOTE: In FSF Emacs, this
1099 function is called `cancel-timer'.)
1102 File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
1107 This section describes functions and variables for recording or
1108 manipulating terminal input. See *Note Display::, for related
1113 * Input Modes:: Options for how input is processed.
1114 * Translating Input:: Low level conversion of some characters or events
1116 * Recording Input:: Saving histories of recent or all input events.
1119 File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
1124 - Function: set-input-mode INTERRUPT FLOW META QUIT-CHAR
1125 This function sets the mode for reading keyboard input. If
1126 INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
1127 `nil', then it uses CBREAK mode. When XEmacs communicates
1128 directly with X, it ignores this argument and uses interrupts if
1129 that is the way it knows how to communicate.
1131 If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
1132 flow control for output to the terminal. This has no effect except
1133 in CBREAK mode. *Note Flow Control::.
1135 The default setting is system dependent. Some systems always use
1136 CBREAK mode regardless of what is specified.
1138 The argument META controls support for input character codes above
1139 127. If META is `t', XEmacs converts characters with the 8th bit
1140 set into Meta characters. If META is `nil', XEmacs disregards the
1141 8th bit; this is necessary when the terminal uses it as a parity
1142 bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
1143 input unchanged. This is good for terminals using European 8-bit
1146 If QUIT-CHAR is non-`nil', it specifies the character to use for
1147 quitting. Normally this character is `C-g'. *Note Quitting::.
1149 The `current-input-mode' function returns the input mode settings
1150 XEmacs is currently using.
1152 - Function: current-input-mode
1153 This function returns current mode for reading keyboard input. It
1154 returns a list, corresponding to the arguments of `set-input-mode',
1155 of the form `(INTERRUPT FLOW META QUIT)' in which:
1157 is non-`nil' when XEmacs is using interrupt-driven input. If
1158 `nil', Emacs is using CBREAK mode.
1161 is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
1162 control for output to the terminal. This value has no effect
1163 unless INTERRUPT is non-`nil'.
1166 is `t' if XEmacs treats the eighth bit of input characters as
1167 the meta bit; `nil' means XEmacs clears the eighth bit of
1168 every input character; any other value means XEmacs uses all
1169 eight bits as the basic character code.
1172 is the character XEmacs currently uses for quitting, usually
1176 File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
1178 Translating Input Events
1179 ------------------------
1181 This section describes features for translating input events into
1182 other input events before they become part of key sequences.
1184 - Variable: function-key-map
1185 This variable holds a keymap that describes the character sequences
1186 sent by function keys on an ordinary character terminal. This
1187 keymap uses the same data structure as other keymaps, but is used
1188 differently: it specifies translations to make while reading
1191 If `function-key-map' "binds" a key sequence K to a vector V, then
1192 when K appears as a subsequence *anywhere* in a key sequence, it
1193 is replaced with the events in V.
1195 For example, VT100 terminals send `<ESC> O P' when the keypad PF1
1196 key is pressed. Therefore, we want XEmacs to translate that
1197 sequence of events into the single event `pf1'. We accomplish
1198 this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
1201 Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
1202 P'; later the function `read-key-sequence' translates this back
1203 into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
1205 Entries in `function-key-map' are ignored if they conflict with
1206 bindings made in the minor mode, local, or global keymaps. The
1207 intent is that the character sequences that function keys send
1208 should not have command bindings in their own right.
1210 The value of `function-key-map' is usually set up automatically
1211 according to the terminal's Terminfo or Termcap entry, but
1212 sometimes those need help from terminal-specific Lisp files.
1213 XEmacs comes with terminal-specific files for many common
1214 terminals; their main purpose is to make entries in
1215 `function-key-map' beyond those that can be deduced from Termcap
1216 and Terminfo. *Note Terminal-Specific::.
1218 Emacs versions 18 and earlier used totally different means of
1219 detecting the character sequences that represent function keys.
1221 - Variable: key-translation-map
1222 This variable is another keymap used just like `function-key-map'
1223 to translate input events into other events. It differs from
1224 `function-key-map' in two ways:
1226 * `key-translation-map' goes to work after `function-key-map' is
1227 finished; it receives the results of translation by
1230 * `key-translation-map' overrides actual key bindings.
1232 The intent of `key-translation-map' is for users to map one
1233 character set to another, including ordinary characters normally
1234 bound to `self-insert-command'.
1236 You can use `function-key-map' or `key-translation-map' for more
1237 than simple aliases, by using a function, instead of a key sequence, as
1238 the "translation" of a key. Then this function is called to compute
1239 the translation of that key.
1241 The key translation function receives one argument, which is the
1242 prompt that was specified in `read-key-sequence'--or `nil' if the key
1243 sequence is being read by the editor command loop. In most cases you
1244 can ignore the prompt value.
1246 If the function reads input itself, it can have the effect of
1247 altering the event that follows. For example, here's how to define
1248 `C-c h' to turn the character that follows into a Hyper character:
1250 (defun hyperify (prompt)
1251 (let ((e (read-event)))
1252 (vector (if (numberp e)
1253 (logior (lsh 1 20) e)
1254 (if (memq 'hyper (event-modifiers e))
1256 (add-event-modifier "H-" e))))))
1258 (defun add-event-modifier (string e)
1259 (let ((symbol (if (symbolp e) e (car e))))
1260 (setq symbol (intern (concat string
1261 (symbol-name symbol))))
1264 (cons symbol (cdr e)))))
1266 (define-key function-key-map "\C-ch" 'hyperify)
1268 The `iso-transl' library uses this feature to provide a way of
1269 inputting non-ASCII Latin-1 characters.
1272 File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
1277 - Function: recent-keys &optional NUMBER
1278 This function returns a vector containing recent input events from
1279 the keyboard or mouse. By default, 100 events are recorded, which
1280 is how many `recent-keys' returns.
1282 All input events are included, whether or not they were used as
1283 parts of key sequences. Thus, you always get the last 100 inputs,
1284 not counting keyboard macros. (Events from keyboard macros are
1285 excluded because they are less interesting for debugging; it
1286 should be enough to see the events that invoked the macros.)
1288 If NUMBER is specified, not more than NUMBER events will be
1289 returned. You may change the number of stored events using
1290 `set-recent-keys-ring-size'.
1292 - Function: recent-keys-ring-size
1293 This function returns the number of recent events stored
1294 internally. This is also the maximum number of events
1295 `recent-keys' can return. By default, 100 events are stored.
1297 - Function: set-recent-keys-ring-size SIZE
1298 This function changes the number of events stored by XEmacs and
1299 returned by `recent-keys'.
1301 For example, `(set-recent-keys-ring-size 250)' will make XEmacs
1302 remember last 250 events and will make `recent-keys' return last
1303 250 events by default.
1305 - Command: open-dribble-file FILENAME
1306 This function opens a "dribble file" named FILENAME. When a
1307 dribble file is open, each input event from the keyboard or mouse
1308 (but not those from keyboard macros) is written in that file. A
1309 non-character event is expressed using its printed representation
1310 surrounded by `<...>'.
1312 You close the dribble file by calling this function with an
1315 This function is normally used to record the input necessary to
1316 trigger an XEmacs bug, for the sake of a bug report.
1318 (open-dribble-file "~/dribble")
1321 See also the `open-termscript' function (*note Terminal Output::.).
projects / chise / xemacs-chise.git.1 / blob