1 This is ../info/lispref.info, produced by makeinfo version 4.0 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 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")))
509 (add-hook 'suspend-resume-hook
510 (function (lambda () (message "Resumed!"))))
511 => (lambda nil (message "Resumed!"))
512 (suspend-emacs "pwd")
514 ---------- Buffer: Minibuffer ----------
516 ---------- Buffer: Minibuffer ----------
518 ---------- Parent Shell ----------
519 lewis@slug[23] % /user/lewis/manual
522 ---------- Echo Area ----------
525 - Variable: suspend-hook
526 This variable is a normal hook run before suspending.
528 - Variable: suspend-resume-hook
529 This variable is a normal hook run after suspending.
532 File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
534 Operating System Environment
535 ============================
537 XEmacs provides access to variables in the operating system
538 environment through various functions. These variables include the
539 name of the system, the user's UID, and so on.
541 - Variable: system-type
542 The value of this variable is a symbol indicating the type of
543 operating system XEmacs is operating on. Here is a table of the
553 Data General DGUX operating system.
556 A GNU system using the GNU HURD and Mach.
559 Hewlett-Packard HPUX operating system.
562 Silicon Graphics Irix system.
565 A GNU system using the Linux kernel.
568 Microsoft MS-DOS "operating system."
571 NeXT Mach-based system.
574 Masscomp RTU, UCB universe.
586 Microsoft windows NT.
591 We do not wish to add new symbols to make finer distinctions
592 unless it is absolutely necessary! In fact, we hope to eliminate
593 some of these alternatives in the future. We recommend using
594 `system-configuration' to distinguish between different operating
597 - Variable: system-configuration
598 This variable holds the three-part configuration name for the
599 hardware/software configuration of your system, as a string. The
600 convenient way to test parts of this string is with `string-match'.
602 - Function: system-name
603 This function returns the name of the machine you are running on.
607 The symbol `system-name' is a variable as well as a function. In
608 fact, the function returns whatever value the variable `system-name'
609 currently holds. Thus, you can set the variable `system-name' in case
610 Emacs is confused about the name of your system. The variable is also
611 useful for constructing frame titles (*note Frame Titles::).
613 - Variable: mail-host-address
614 If this variable is non-`nil', it is used instead of `system-name'
615 for purposes of generating email addresses. For example, it is
616 used when constructing the default value of `user-mail-address'.
617 *Note User Identification::. (Since this is done when XEmacs
618 starts up, the value actually used is the one saved when XEmacs
619 was dumped. *Note Building XEmacs::.)
621 - Function: getenv var
622 This function returns the value of the environment variable VAR,
623 as a string. Within XEmacs, the environment variable values are
624 kept in the Lisp variable `process-environment'.
629 lewis@slug[10] % printenv
630 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
636 - Command: setenv variable value
637 This command sets the value of the environment variable named
638 VARIABLE to VALUE. Both arguments should be strings. This
639 function works by modifying `process-environment'; binding that
640 variable with `let' is also reasonable practice.
642 - Variable: process-environment
643 This variable is a list of strings, each describing one environment
644 variable. The functions `getenv' and `setenv' work by means of
648 => ("l=/usr/stanford/lib/gnuemacs/lisp"
649 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
655 - Variable: path-separator
656 This variable holds a string which says which character separates
657 directories in a search path (as found in an environment
658 variable). Its value is `":"' for Unix and GNU systems, and `";"'
659 for MS-DOS and Windows NT.
661 - Variable: invocation-name
662 This variable holds the program name under which Emacs was
663 invoked. The value is a string, and does not include a directory
666 - Variable: invocation-directory
667 This variable holds the directory from which the Emacs executable
668 was invoked, or perhaps `nil' if that directory cannot be
671 - Variable: installation-directory
672 If non-`nil', this is a directory within which to look for the
673 `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
674 can't find those directories in their standard installed
675 locations, but can find them in a directory related somehow to the
676 one containing the Emacs executable.
678 - Function: load-average &optional use-floats
679 This function returns a list of the current 1-minute, 5-minute and
680 15-minute load averages. The values are integers that are 100
681 times the system load averages. (The load averages indicate the
682 number of processes trying to run.)
684 When USE-FLOATS is non-`nil', floats will be returned instead of
685 integers. These floats are not multiplied by 100.
690 => (1.69921875 1.58984375 1.640625)
692 lewis@rocky[5] % uptime
693 8:06pm up 16 day(s), 21:57, 40 users,
694 load average: 1.68, 1.59, 1.64
696 If the 5-minute or 15-minute load averages are not available,
697 return a shortened list, containing only those averages which are
700 On some systems, this function may require special privileges to
701 run, or it may be unimplemented for the particular system type.
702 In that case, the function will signal an error.
704 - Function: emacs-pid
705 This function returns the process ID of the Emacs process.
707 - Function: setprv privilege-name &optional setp getprv
708 This function sets or resets a VMS privilege. (It does not exist
709 on Unix.) The first arg is the privilege name, as a string. The
710 second argument, SETP, is `t' or `nil', indicating whether the
711 privilege is to be turned on or off. Its default is `nil'. The
712 function returns `t' if successful, `nil' otherwise.
714 If the third argument, GETPRV, is non-`nil', `setprv' does not
715 change the privilege, but returns `t' or `nil' indicating whether
716 the privilege is currently enabled.
719 File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
724 - Variable: user-mail-address
725 This holds the nominal email address of the user who is using
726 Emacs. When Emacs starts up, it computes a default value that is
727 usually right, but users often set this themselves when the
728 default value is not right.
730 - Function: user-login-name &optional uid
731 If you don't specify UID, this function returns the name under
732 which the user is logged in. If the environment variable `LOGNAME'
733 is set, that value is used. Otherwise, if the environment variable
734 `USER' is set, that value is used. Otherwise, the value is based
735 on the effective UID, not the real UID.
737 If you specify UID, the value is the user name that corresponds to
738 UID (which should be an integer).
743 - Function: user-real-login-name
744 This function returns the user name corresponding to Emacs's real
745 UID. This ignores the effective UID and ignores the environment
746 variables `LOGNAME' and `USER'.
748 - Variable: user-full-name
749 This variable holds the name of the user running this Emacs. It is
750 initialized at startup time from the value of `NAME' environment
751 variable. You can change the value of this variable to alter the
752 result of the `user-full-name' function.
754 - Function: user-full-name &optional user
755 This function returns the full name of USER. If USER is `nil', it
756 defaults to the user running this Emacs. In that case, the value
757 of `user-full-name' variable, if non-`nil', will be used.
759 If USER is specified explicitly, `user-full-name' variable is
764 (setq user-full-name "Hrvoje \"Niksa\" Niksic")
766 => "Hrvoje \"Niksa\" Niksic"
767 (user-full-name "hniksic")
770 The symbols `user-login-name', `user-real-login-name' and
771 `user-full-name' are variables as well as functions. The functions
772 return the same values that the variables hold. These variables allow
773 you to "fake out" Emacs by telling the functions what to return. The
774 variables are also useful for constructing frame titles (*note Frame
777 - Function: user-real-uid
778 This function returns the real UID of the user.
784 This function returns the effective UID of the user.
786 - Function: user-home-directory
787 This function returns the "`HOME'" directory of the user, and is
788 intended to replace occurrences of "`(getenv "HOME")'". Under
789 Unix systems, the following is done:
791 1. Return the value of "`(getenv "HOME")'", if set.
793 2. Return "/", as a fallback, but issue a warning. (Future
794 versions of XEmacs will also attempt to lookup the `HOME'
795 directory via `getpwent()', but this has not yet been
798 Under MS Windows, this is done:
800 1. Return the value of "`(getenv "HOME")'", if set.
802 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
803 both set, return the concatenation (the following description
804 uses MS Windows environment variable substitution syntax):
805 `%HOMEDRIVE%%HOMEDIR%'.
807 3. Return "C:\", as a fallback, but issue a warning.
810 File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
815 This section explains how to determine the current time and the time
818 - Function: current-time-string &optional time-value
819 This function returns the current time and date as a
820 humanly-readable string. The format of the string is unvarying;
821 the number of characters used for each part is always the same, so
822 you can reliably use `substring' to extract pieces of it. It is
823 wise to count the characters from the beginning of the string
824 rather than from the end, as additional information may be added
827 The argument TIME-VALUE, if given, specifies a time to format
828 instead of the current time. The argument should be a list whose
829 first two elements are integers. Thus, you can use times obtained
830 from `current-time' (see below) and from `file-attributes' (*note
833 (current-time-string)
834 => "Wed Oct 14 22:21:05 1987"
836 - Function: current-time
837 This function returns the system's time value as a list of three
838 integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
839 combine to give the number of seconds since 0:00 January 1, 1970,
840 which is HIGH * 2**16 + LOW.
842 The third element, MICROSEC, gives the microseconds since the
843 start of the current second (or 0 for systems that return time
844 only on the resolution of a second).
846 The first two elements can be compared with file time values such
847 as you get with the function `file-attributes'. *Note File
850 - Function: current-time-zone &optional time-value
851 This function returns a list describing the time zone that the
854 The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
855 giving the number of seconds ahead of UTC (east of Greenwich). A
856 negative value means west of Greenwich. The second element, NAME
857 is a string giving the name of the time zone. Both elements
858 change when daylight savings time begins or ends; if the user has
859 specified a time zone that does not use a seasonal time
860 adjustment, then the value is constant through time.
862 If the operating system doesn't supply all the information
863 necessary to compute the value, both elements of the list are
866 The argument TIME-VALUE, if given, specifies a time to analyze
867 instead of the current time. The argument should be a cons cell
868 containing two integers, or a list whose first two elements are
869 integers. Thus, you can use times obtained from `current-time'
870 (see above) and from `file-attributes' (*note File Attributes::).
873 File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
878 These functions convert time values (lists of two or three integers)
879 to strings or to calendrical information. There is also a function to
880 convert calendrical information to a time value. You can get time
881 values from the functions `current-time' (*note Time of Day::) and
882 `file-attributes' (*note File Attributes::).
884 - Function: format-time-string format-string &optional time
885 This function converts TIME to a string according to
886 FORMAT-STRING. If TIME is omitted, it defaults to the current
887 time. The argument FORMAT-STRING may contain `%'-sequences which
888 say to substitute parts of the time. Here is a table of what the
892 This stands for the abbreviated name of the day of week.
895 This stands for the full name of the day of week.
898 This stands for the abbreviated name of the month.
901 This stands for the full name of the month.
904 This is a synonym for `%x %X'.
907 This has a locale-specific meaning. In the default locale
908 (named C), it is equivalent to `%A, %B %e, %Y'.
911 This stands for the day of month, zero-padded.
914 This is a synonym for `%m/%d/%y'.
917 This stands for the day of month, blank-padded.
920 This is a synonym for `%b'.
923 This stands for the hour (00-23).
926 This stands for the hour (00-12).
929 This stands for the day of the year (001-366).
932 This stands for the hour (0-23), blank padded.
935 This stands for the hour (1-12), blank padded.
938 This stands for the month (01-12).
941 This stands for the minute (00-59).
944 This stands for a newline.
947 This stands for `AM' or `PM', as appropriate.
950 This is a synonym for `%I:%M:%S %p'.
953 This is a synonym for `%H:%M'.
956 This stands for the seconds (00-60).
959 This stands for a tab character.
962 This is a synonym for `%H:%M:%S'.
965 This stands for the week of the year (01-52), assuming that
966 weeks start on Sunday.
969 This stands for the numeric day of week (0-6). Sunday is day
973 This stands for the week of the year (01-52), assuming that
974 weeks start on Monday.
977 This has a locale-specific meaning. In the default locale
978 (named C), it is equivalent to `%D'.
981 This has a locale-specific meaning. In the default locale
982 (named C), it is equivalent to `%T'.
985 This stands for the year without century (00-99).
988 This stands for the year with century.
991 This stands for the time zone abbreviation.
993 - Function: decode-time time
994 This function converts a time value into calendrical information.
995 The return value is a list of nine elements, as follows:
997 (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
999 Here is what the elements mean:
1002 The number of seconds past the minute, as an integer between
1006 The number of minutes past the hour, as an integer between 0
1010 The hour of the day, as an integer between 0 and 23.
1013 The day of the month, as an integer between 1 and 31.
1016 The month of the year, as an integer between 1 and 12.
1019 The year, an integer typically greater than 1900.
1022 The day of week, as an integer between 0 and 6, where 0
1026 `t' if daylight savings time is effect, otherwise `nil'.
1029 An integer indicating the time zone, as the number of seconds
1032 Note that Common Lisp has different meanings for DOW and ZONE.
1034 - Function: encode-time seconds minutes hour day month year &optional
1036 This function is the inverse of `decode-time'. It converts seven
1037 items of calendrical data into a time value. For the meanings of
1038 the arguments, see the table above under `decode-time'.
1040 Year numbers less than 100 are treated just like other year
1041 numbers. If you want them to stand for years above 1900, you must
1042 alter them yourself before you call `encode-time'.
1044 The optional argument ZONE defaults to the current time zone and
1045 its daylight savings time rules. If specified, it can be either a
1046 list (as you would get from `current-time-zone') or an integer (as
1047 you would get from `decode-time'). The specified zone is used
1048 without any further alteration for daylight savings time.
1051 File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
1053 Timers for Delayed Execution
1054 ============================
1056 You can set up a timer to call a function at a specified future time.
1058 - Function: add-timeout secs function object &optional resignal
1059 This function adds a timeout, to be signaled after the timeout
1060 period has elapsed. SECS is a number of seconds, expressed as an
1061 integer or a float. FUNCTION will be called after that many
1062 seconds have elapsed, with one argument, the given OBJECT. If the
1063 optional RESIGNAL argument is provided, then after this timeout
1064 expires, `add-timeout' will automatically be called again with
1065 RESIGNAL as the first argument.
1067 This function returns an object which is the "id" of this
1068 particular timeout. You can pass that object to `disable-timeout'
1069 to turn off the timeout before it has been signalled.
1071 The number of seconds may be expressed as a floating-point number,
1072 in which case some fractional part of a second will be used.
1073 Caveat: the usable timeout granularity will vary from system to
1076 Adding a timeout causes a timeout event to be returned by
1077 `next-event', and the function will be invoked by
1078 `dispatch-event', so if XEmacs is in a tight loop, the function
1079 will not be invoked until the next call to sit-for or until the
1080 return to top-level (the same is true of process filters).
1082 WARNING: if you are thinking of calling add-timeout from inside of
1083 a callback function as a way of resignalling a timeout, think
1084 again. There is a race condition. That's why the RESIGNAL
1087 (NOTE: In FSF Emacs, this function is called `run-at-time' and has
1088 different semantics.)
1090 - Function: disable-timeout id
1091 Cancel the requested action for ID, which should be a value
1092 previously returned by `add-timeout'. This cancels the effect of
1093 that call to `add-timeout'; the arrival of the specified time will
1094 not cause anything special to happen. (NOTE: In FSF Emacs, this
1095 function is called `cancel-timer'.)
1098 File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
1103 This section describes functions and variables for recording or
1104 manipulating terminal input. See *Note Display::, for related
1109 * Input Modes:: Options for how input is processed.
1110 * Translating Input:: Low level conversion of some characters or events
1112 * Recording Input:: Saving histories of recent or all input events.
1115 File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
1120 - Function: set-input-mode interrupt flow meta quit-char
1121 This function sets the mode for reading keyboard input. If
1122 INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
1123 `nil', then it uses CBREAK mode. When XEmacs communicates
1124 directly with X, it ignores this argument and uses interrupts if
1125 that is the way it knows how to communicate.
1127 If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
1128 flow control for output to the terminal. This has no effect except
1129 in CBREAK mode. *Note Flow Control::.
1131 The default setting is system dependent. Some systems always use
1132 CBREAK mode regardless of what is specified.
1134 The argument META controls support for input character codes above
1135 127. If META is `t', XEmacs converts characters with the 8th bit
1136 set into Meta characters. If META is `nil', XEmacs disregards the
1137 8th bit; this is necessary when the terminal uses it as a parity
1138 bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
1139 input unchanged. This is good for terminals using European 8-bit
1142 If QUIT-CHAR is non-`nil', it specifies the character to use for
1143 quitting. Normally this character is `C-g'. *Note Quitting::.
1145 The `current-input-mode' function returns the input mode settings
1146 XEmacs is currently using.
1148 - Function: current-input-mode
1149 This function returns current mode for reading keyboard input. It
1150 returns a list, corresponding to the arguments of `set-input-mode',
1151 of the form `(INTERRUPT FLOW META QUIT)' in which:
1153 is non-`nil' when XEmacs is using interrupt-driven input. If
1154 `nil', Emacs is using CBREAK mode.
1157 is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
1158 control for output to the terminal. This value has no effect
1159 unless INTERRUPT is non-`nil'.
1162 is `t' if XEmacs treats the eighth bit of input characters as
1163 the meta bit; `nil' means XEmacs clears the eighth bit of
1164 every input character; any other value means XEmacs uses all
1165 eight bits as the basic character code.
1168 is the character XEmacs currently uses for quitting, usually
1172 File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
1174 Translating Input Events
1175 ------------------------
1177 This section describes features for translating input events into
1178 other input events before they become part of key sequences.
1180 - Variable: function-key-map
1181 This variable holds a keymap that describes the character sequences
1182 sent by function keys on an ordinary character terminal. This
1183 keymap uses the same data structure as other keymaps, but is used
1184 differently: it specifies translations to make while reading
1187 If `function-key-map' "binds" a key sequence K to a vector V, then
1188 when K appears as a subsequence _anywhere_ in a key sequence, it
1189 is replaced with the events in V.
1191 For example, VT100 terminals send `<ESC> O P' when the keypad PF1
1192 key is pressed. Therefore, we want XEmacs to translate that
1193 sequence of events into the single event `pf1'. We accomplish
1194 this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
1197 Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
1198 P'; later the function `read-key-sequence' translates this back
1199 into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
1201 Entries in `function-key-map' are ignored if they conflict with
1202 bindings made in the minor mode, local, or global keymaps. The
1203 intent is that the character sequences that function keys send
1204 should not have command bindings in their own right.
1206 The value of `function-key-map' is usually set up automatically
1207 according to the terminal's Terminfo or Termcap entry, but
1208 sometimes those need help from terminal-specific Lisp files.
1209 XEmacs comes with terminal-specific files for many common
1210 terminals; their main purpose is to make entries in
1211 `function-key-map' beyond those that can be deduced from Termcap
1212 and Terminfo. *Note Terminal-Specific::.
1214 Emacs versions 18 and earlier used totally different means of
1215 detecting the character sequences that represent function keys.
1217 - Variable: key-translation-map
1218 This variable is another keymap used just like `function-key-map'
1219 to translate input events into other events. It differs from
1220 `function-key-map' in two ways:
1222 * `key-translation-map' goes to work after `function-key-map' is
1223 finished; it receives the results of translation by
1226 * `key-translation-map' overrides actual key bindings.
1228 The intent of `key-translation-map' is for users to map one
1229 character set to another, including ordinary characters normally
1230 bound to `self-insert-command'.
1232 You can use `function-key-map' or `key-translation-map' for more
1233 than simple aliases, by using a function, instead of a key sequence, as
1234 the "translation" of a key. Then this function is called to compute
1235 the translation of that key.
1237 The key translation function receives one argument, which is the
1238 prompt that was specified in `read-key-sequence'--or `nil' if the key
1239 sequence is being read by the editor command loop. In most cases you
1240 can ignore the prompt value.
1242 If the function reads input itself, it can have the effect of
1243 altering the event that follows. For example, here's how to define
1244 `C-c h' to turn the character that follows into a Hyper character:
1246 (defun hyperify (prompt)
1247 (let ((e (read-event)))
1248 (vector (if (numberp e)
1249 (logior (lsh 1 20) e)
1250 (if (memq 'hyper (event-modifiers e))
1252 (add-event-modifier "H-" e))))))
1254 (defun add-event-modifier (string e)
1255 (let ((symbol (if (symbolp e) e (car e))))
1256 (setq symbol (intern (concat string
1257 (symbol-name symbol))))
1260 (cons symbol (cdr e)))))
1262 (define-key function-key-map "\C-ch" 'hyperify)
1264 The `iso-transl' library uses this feature to provide a way of
1265 inputting non-ASCII Latin-1 characters.
1268 File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
1273 - Function: recent-keys &optional number
1274 This function returns a vector containing recent input events from
1275 the keyboard or mouse. By default, 100 events are recorded, which
1276 is how many `recent-keys' returns.
1278 All input events are included, whether or not they were used as
1279 parts of key sequences. Thus, you always get the last 100 inputs,
1280 not counting keyboard macros. (Events from keyboard macros are
1281 excluded because they are less interesting for debugging; it
1282 should be enough to see the events that invoked the macros.)
1284 If NUMBER is specified, not more than NUMBER events will be
1285 returned. You may change the number of stored events using
1286 `set-recent-keys-ring-size'.
1288 - Function: recent-keys-ring-size
1289 This function returns the number of recent events stored
1290 internally. This is also the maximum number of events
1291 `recent-keys' can return. By default, 100 events are stored.
1293 - Function: set-recent-keys-ring-size size
1294 This function changes the number of events stored by XEmacs and
1295 returned by `recent-keys'.
1297 For example, `(set-recent-keys-ring-size 250)' will make XEmacs
1298 remember last 250 events and will make `recent-keys' return last
1299 250 events by default.
1301 - Command: open-dribble-file filename
1302 This function opens a "dribble file" named FILENAME. When a
1303 dribble file is open, each input event from the keyboard or mouse
1304 (but not those from keyboard macros) is written in that file. A
1305 non-character event is expressed using its printed representation
1306 surrounded by `<...>'.
1308 You close the dribble file by calling this function with an
1311 This function is normally used to record the input necessary to
1312 trigger an XEmacs bug, for the sake of a bug report.
1314 (open-dribble-file "~/dribble")
1317 See also the `open-termscript' function (*note Terminal Output::).
projects / chise / xemacs-chise.git- / blob