annotate lispref/os.texi @ 71292:b8510d99b32e

*** empty log message ***
author Thien-Thi Nguyen <ttn@gnuvola.org>
date Fri, 09 Jun 2006 14:23:49 +0000
parents e617f5abce58
children a6b7cfaf2ff5 a5812696f7bf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
64889
e836425ee789 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64290
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
68648
067115a6e738 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 66543
diff changeset
4 @c 2004, 2005, 2006 Free Software Foundation, Inc.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/os
60996
acfc6c4c5fba (System In): Change name of previous node.
Glenn Morris <rgm@gnu.org>
parents: 60452
diff changeset
7 @node System Interface, Antinews, Display, Top
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Operating System Interface
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 This chapter is about starting and getting out of Emacs, access to
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
11 values in the operating system environment, and terminal input, output,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 and flow control.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 @xref{Building Emacs}, for related information. See also
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 @ref{Display}, for additional operating system status information
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 pertaining to the terminal and the screen.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 @menu
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
19 * Starting Up:: Customizing Emacs startup processing.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 * Getting Out:: How exiting works (permanent or temporary).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 * System Environment:: Distinguish the name and kind of system.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 * User Identification:: Finding the name and user id of the user.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 * Time of Day:: Getting the current time.
64914
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
24 * Time Conversion:: Converting a time from numeric form
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
25 to calendrical data, and vice versa).
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
26 * Time Parsing:: Converting a time from numeric form to text
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
27 and vice versa.
57989
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
28 * Processor Run Time:: Getting the run time used by Emacs.
43037
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
29 * Time Calculations:: Adding, subtracting, comparing times, etc.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 * Timers:: Setting a timer to call a function at a certain time.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 * Terminal Input:: Recording terminal input for debugging.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 * Terminal Output:: Recording terminal output for debugging.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
33 * Sound Output:: Playing sounds on the computer's speaker.
46228
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
34 * X11 Keysyms:: Operating on key symbols for X Windows
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 * Batch Mode:: Running Emacs without terminal interaction.
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
36 * Session Management:: Saving and restoring state with X Session Management.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 @node Starting Up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 @section Starting Up Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 This section describes what Emacs does when it is started, and how you
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 can customize these actions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 @menu
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
46 * Startup Summary:: Sequence of actions Emacs performs at startup.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 * Init File:: Details on reading the init file (@file{.emacs}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 * Terminal-Specific:: How the terminal-specific Lisp file is read.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
49 * Command-Line Arguments:: How command-line arguments are processed,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 and how you can customize them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
53 @node Startup Summary
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
54 @subsection Summary: Sequence of Actions at Startup
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 @cindex initialization
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
56 @cindex startup of Emacs
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 @cindex @file{startup.el}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 The order of operations performed (in @file{startup.el}) by Emacs when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 it is started up is as follows:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 @enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 @item
28603
cb9db16dba12 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27765
diff changeset
64 It adds subdirectories to @code{load-path}, by running the file named
cb9db16dba12 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27765
diff changeset
65 @file{subdirs.el} in each directory in the list. Normally this file
cb9db16dba12 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27765
diff changeset
66 adds the directory's subdirectories to the list, and these will be
cb9db16dba12 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27765
diff changeset
67 scanned in their turn. The files @file{subdirs.el} are normally
cb9db16dba12 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27765
diff changeset
68 generated automatically by Emacs installation.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
69
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
70 @item
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
71 It sets the language environment and the terminal coding system,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
72 if requested by environment variables such as @code{LANG}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
73
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
74 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 It loads the initialization library for the window system, if you are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 using a window system. This library's name is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 @file{term/@var{windowsystem}-win.el}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
80 It processes the initial options. (Some of them are handled
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
81 even earlier than this.)
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
82
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
83 @item
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
84 It initializes the window frame and faces, if appropriate.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 It runs the normal hook @code{before-init-hook}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 @item
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
90 It loads the library @file{site-start} (if any), unless the option
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
91 @samp{-Q} (or @samp{--no-site-file}) was specified. The library's file
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
92 name is usually @file{site-start.el}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 @cindex @file{site-start.el}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
95 @item
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63525
diff changeset
96 It loads your init file (usually @file{~/.emacs}), unless the option
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63525
diff changeset
97 @samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63525
diff changeset
98 specified on the command line. The @samp{-u} option can specify
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63525
diff changeset
99 another user whose home directory should be used instead of @file{~}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
101 @item
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
102 It loads the library @file{default} (if any), unless
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
103 @code{inhibit-default-init} is non-@code{nil}. (This is not done in
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
104 @samp{-batch} mode, or if @samp{-Q} or @samp{-q} was specified on the
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
105 command line.) The library's file name is usually @file{default.el}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 @cindex @file{default.el}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 It runs the normal hook @code{after-init-hook}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 It sets the major mode according to @code{initial-major-mode}, provided
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 the buffer @samp{*scratch*} is still current and still in Fundamental
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
116 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 It loads the terminal-specific Lisp file, if any, except when in batch
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 mode or using a window system.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 It displays the initial echo area message, unless you have suppressed
65171
b6de4c2b1b34 (Startup Summary): Fix the description of the initial startup message display.
Eli Zaretskii <eliz@gnu.org>
parents: 64914
diff changeset
122 that with @code{inhibit-startup-echo-area-message}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
124 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
125 It processes the action arguments from the command line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
127 @item
27353
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
128 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 It calls @code{frame-notice-user-settings}, which modifies the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 parameters of the selected frame according to whatever the init files
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 specify.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
135 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 It runs @code{window-setup-hook}. @xref{Window Systems}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
138 @item
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
139 It displays copyleft, nonwarranty, and basic use information, provided
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
140 the value of @code{inhibit-startup-message} is @code{nil}, you didn't
65171
b6de4c2b1b34 (Startup Summary): Fix the description of the initial startup message display.
Eli Zaretskii <eliz@gnu.org>
parents: 64914
diff changeset
141 specify @samp{--no-splash} or @samp{-Q}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 @end enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 @defopt inhibit-startup-message
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 This variable inhibits the initial startup messages (the nonwarranty,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 etc.). If it is non-@code{nil}, then the messages are not printed.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 This variable exists so you can set it in your personal init file, once
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 you are familiar with the contents of the startup message. Do not set
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 this variable in the init file of a new user, or in a way that affects
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 more than one user, because that would prevent new users from receiving
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 the information they are supposed to see.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 @defopt inhibit-startup-echo-area-message
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 This variable controls the display of the startup echo area message.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 You can suppress the startup echo area message by adding text with this
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
158 form to your init file:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 (setq inhibit-startup-echo-area-message
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 "@var{your-login-name}")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
165 Emacs explicitly checks for an expression as shown above in your init
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
166 file; your login name must appear in the expression as a Lisp string
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
167 constant. Other methods of setting
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
168 @code{inhibit-startup-echo-area-message} to the same value do not
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
169 inhibit the startup message.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 This way, you can easily inhibit the message for yourself if you wish,
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
172 but thoughtless copying of your init file will not inhibit the message
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
173 for someone else.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @node Init File
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
177 @subsection The Init File, @file{.emacs}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 @cindex init file
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 @cindex @file{.emacs}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
181 When you start Emacs, it normally attempts to load your @dfn{init
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
182 file}, a file in your home directory. Its normal name is
66543
673d94c09ed4 Document ~/.emacs.d/init.el.
Chong Yidong <cyd@stupidchicken.com>
parents: 65171
diff changeset
183 @file{.emacs}, but you can also call it @file{.emacs.el}.
673d94c09ed4 Document ~/.emacs.d/init.el.
Chong Yidong <cyd@stupidchicken.com>
parents: 65171
diff changeset
184 Alternatively, you can use a file named @file{init.el} in a
673d94c09ed4 Document ~/.emacs.d/init.el.
Chong Yidong <cyd@stupidchicken.com>
parents: 65171
diff changeset
185 subdirectory @file{.emacs.d}. Whichever place you use, you can also
673d94c09ed4 Document ~/.emacs.d/init.el.
Chong Yidong <cyd@stupidchicken.com>
parents: 65171
diff changeset
186 compile the file (@pxref{Byte Compilation}); then the actual file
673d94c09ed4 Document ~/.emacs.d/init.el.
Chong Yidong <cyd@stupidchicken.com>
parents: 65171
diff changeset
187 loaded will be @file{.emacs.elc} or @file{init.elc}.
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
188
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
189 The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
190 control whether and where to find the init file; @samp{-q} (and the
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
191 stronger @samp{-Q}) says not to load an init file, while @samp{-u
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
192 @var{user}} says to load @var{user}'s init file instead of yours.
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
193 @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
194 option is specified, Emacs uses the @code{LOGNAME} environment
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
195 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
196 systems) variable, to find your home directory and thus your init
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
197 file; this way, even if you have su'd, Emacs still loads your own init
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
198 file. If those environment variables are absent, though, Emacs uses
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
199 your user-id to find your home directory.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 @cindex default init file
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
202 A site may have a @dfn{default init file}, which is the library
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
203 named @file{default.el}. Emacs finds the @file{default.el} file
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
204 through the standard search path for libraries (@pxref{How Programs Do
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
205 Loading}). The Emacs distribution does not come with this file; sites
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
206 may provide one for local customizations. If the default init file
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
207 exists, it is loaded whenever you start Emacs, except in batch mode or
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
208 if @samp{-q} (or @samp{-Q}) is specified. But your own personal init
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
209 file, if any, is loaded first; if it sets @code{inhibit-default-init}
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
210 to a non-@code{nil} value, then Emacs does not subsequently load the
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
211 @file{default.el} file.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 Another file for site-customization is @file{site-start.el}. Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 loads this @emph{before} the user's init file. You can inhibit the
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
215 loading of this file with the option @samp{--no-site-file}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
217 @defvar site-run-file
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
218 This variable specifies the site-customization file to load before the
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
219 user's init file. Its normal value is @code{"site-start"}. The only
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
220 way you can change it with real effect is to do so before dumping
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
221 Emacs.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
222 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
223
50475
b65aa1d740eb Fix cross references.
Juanma Barranquero <lekktu@gmail.com>
parents: 49549
diff changeset
224 @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 examples of how to make various commonly desired customizations in your
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 @file{.emacs} file.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 @defopt inhibit-default-init
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 This variable prevents Emacs from loading the default initialization
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 library file for your session of Emacs. If its value is non-@code{nil},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 then the default library is not loaded. The default value is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 @defvar before-init-hook
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
236 This normal hook is run, once, just before loading all the init files
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
237 (the user's init file, @file{default.el}, and/or @file{site-start.el}).
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
238 (The only way to change it with real effect is before dumping Emacs.)
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
239 @end defvar
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
240
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
241 @defvar after-init-hook
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
242 This normal hook is run, once, just after loading all the init files
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
243 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
27353
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
244 before loading the terminal-specific library and processing the
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
245 command-line action arguments.
27353
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
246 @end defvar
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
247
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
248 @defvar emacs-startup-hook
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
249 @tindex emacs-startup-hook
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
250 This normal hook is run, once, just after handling the command line
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
251 arguments, just before @code{term-setup-hook}.
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
252 @end defvar
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
253
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
254 @defvar user-init-file
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
255 @tindex user-init-file
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
256 This variable holds the absolute file name of the user's init file. If the
27353
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
257 actual init file loaded is a compiled file, such as @file{.emacs.elc},
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
258 the value refers to the corresponding source file.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @node Terminal-Specific
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 @subsection Terminal-Specific Initialization
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 @cindex terminal-specific initialization
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 Each terminal type can have its own Lisp library that Emacs loads when
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
266 run on that type of terminal. The library's name is constructed by
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
267 concatenating the value of the variable @code{term-file-prefix} and the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
268 terminal type (specified by the environment variable @code{TERM}).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
269 Normally, @code{term-file-prefix} has the value
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
270 @code{"term/"}; changing this is not recommended. Emacs finds the file
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
271 in the normal manner, by searching the @code{load-path} directories, and
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
272 trying the @samp{.elc} and @samp{.el} suffixes.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273
70640
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
274 @cindex Termcap
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
275 The usual function of a terminal-specific library is to enable
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
276 special keys to send sequences that Emacs can recognize. It may also
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
277 need to set or add to @code{function-key-map} if the Termcap or
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
278 Terminfo entry does not specify all the terminal's function keys.
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
279 @xref{Terminal Input}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280
70640
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
281 When the name of the terminal type contains a hyphen, and no library
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
282 is found whose name is identical to the terminal's name, Emacs strips
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
283 from the terminal's name the last hyphen and everything that follows
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
284 it, and tries again. This process is repeated until Emacs finds a
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
285 matching library or until there are no more hyphens in the name (the
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
286 latter means the terminal doesn't have any library specific to it).
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
287 Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
288 libraries, Emacs will try the same library @file{term/aaa.el} for
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
289 terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
290 library can evaluate @code{(getenv "TERM")} to find the full name of
e617f5abce58 (Terminal-Specific): More accurate description of how Emacs searches for the
Eli Zaretskii <eliz@gnu.org>
parents: 69893
diff changeset
291 the terminal type.@refill
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
293 Your init file can prevent the loading of the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 terminal-specific library by setting the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 @code{term-file-prefix} to @code{nil}. This feature is useful when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 experimenting with your own peculiar customizations.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 You can also arrange to override some of the actions of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 terminal-specific library by setting the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @code{term-setup-hook}. This is a normal hook which Emacs runs using
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 @code{run-hooks} at the end of Emacs initialization, after loading both
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
302 your init file and any terminal-specific libraries. You can
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 use this variable to define initializations for terminals that do not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 have their own libraries. @xref{Hooks}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 @defvar term-file-prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 @cindex @code{TERM} environment variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 a terminal-specific initialization file as follows:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 (load (concat term-file-prefix (getenv "TERM")))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 You may set the @code{term-file-prefix} variable to @code{nil} in your
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
317 init file if you do not wish to load the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 terminal-initialization file. To do this, put the following in
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
319 your init file: @code{(setq term-file-prefix nil)}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
320
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
321 On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
322 uses @samp{internal} as the terminal type.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
325 @defvar term-setup-hook
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
326 This variable is a normal hook that Emacs runs after loading your
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
327 init file, the default initialization file (if any) and the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 terminal-specific Lisp file.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 You can use @code{term-setup-hook} to override the definitions made by a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 terminal-specific file.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 See @code{window-setup-hook} in @ref{Window Systems}, for a related
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 feature.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
337 @node Command-Line Arguments
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
338 @subsection Command-Line Arguments
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
339 @cindex command-line arguments
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
341 You can use command-line arguments to request various actions when you
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 start Emacs. Since you do not need to start Emacs more than once per
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 day, and will often leave your Emacs session running longer than that,
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
344 command-line arguments are hardly ever used. As a practical matter, it
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 is best to avoid making the habit of using them, since this habit would
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 encourage you to kill and restart Emacs unnecessarily often. These
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 options exist for two reasons: to be compatible with other editors (for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 invocation by other programs) and to enable shell scripts to run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 specific Lisp programs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
351 This section describes how Emacs processes command-line arguments,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 and how you can customize them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 (Note that some other editors require you to start afresh each time
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 you want to edit a file. With this kind of editor, you will probably
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
357 specify the file as a command-line argument. The recommended way to
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 use GNU Emacs is to start it only once, just after you log in, and do
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 all your editing in the same Emacs process. Each time you want to edit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 a different file, you visit it with the existing Emacs, which eventually
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 comes to have many files in it ready for editing. Usually you do not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 kill the Emacs until you are about to log out.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 @end ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 @defun command-line
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
366 This function parses the command line that Emacs was called with,
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
367 processes it, loads the user's init file and displays the
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
368 startup messages.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 @defvar command-line-processed
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 The value of this variable is @code{t} once the command line has been
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 processed.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 If you redump Emacs by calling @code{dump-emacs}, you may wish to set
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 this variable to @code{nil} first in order to cause the new dumped Emacs
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
377 to process its new command-line arguments.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 @defvar command-switch-alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 @cindex switches on command line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 @cindex options on command line
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
383 @cindex command-line options
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 The value of this variable is an alist of user-defined command-line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 options and associated handler functions. This variable exists so you
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 can add elements to it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
388 A @dfn{command-line option} is an argument on the command line, which
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
389 has the form:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 -@var{option}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
395 The elements of the @code{command-switch-alist} look like this:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 (@var{option} . @var{handler-function})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
401 The @sc{car}, @var{option}, is a string, the name of a command-line
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
402 option (not including the initial hyphen). The @var{handler-function}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
403 is called to handle @var{option}, and receives the option name as its
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
404 sole argument.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 In some cases, the option is followed in the command line by an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 argument. In these cases, the @var{handler-function} can find all the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 remaining command-line arguments in the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 @code{command-line-args-left}. (The entire list of command-line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 arguments is in @code{command-line-args}.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
412 The command-line arguments are parsed by the @code{command-line-1}
69893
8bba8d71e8cd (Command-Line Arguments): Update xref to emacs manual
Eli Zaretskii <eliz@gnu.org>
parents: 68648
diff changeset
413 function in the @file{startup.el} file. See also @ref{Emacs
8bba8d71e8cd (Command-Line Arguments): Update xref to emacs manual
Eli Zaretskii <eliz@gnu.org>
parents: 68648
diff changeset
414 Invocation, , Command Line Arguments for Emacs Invocation, emacs, The
8bba8d71e8cd (Command-Line Arguments): Update xref to emacs manual
Eli Zaretskii <eliz@gnu.org>
parents: 68648
diff changeset
415 GNU Emacs Manual}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 @defvar command-line-args
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
419 The value of this variable is the list of command-line arguments passed
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 to Emacs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 @defvar command-line-functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 This variable's value is a list of functions for handling an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 unrecognized command-line argument. Each time the next argument to be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 processed has no special meaning, the functions in this list are called,
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
427 in order of appearance, until one of them returns a non-@code{nil}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 These functions are called with no arguments. They can access the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 command-line argument under consideration through the variable
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
432 @code{argi}, which is bound temporarily at this point. The remaining
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
433 arguments (not including the current one) are in the variable
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
434 @code{command-line-args-left}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 When a function recognizes and processes the argument in @code{argi}, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 should return a non-@code{nil} value to say it has dealt with that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 argument. If it has also dealt with some of the following arguments, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 can indicate that by deleting them from @code{command-line-args-left}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 If all of these functions return @code{nil}, then the argument is used
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 as a file name to visit.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 @node Getting Out
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @section Getting Out of Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @cindex exiting Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 There are two ways to get out of Emacs: you can kill the Emacs job,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 which exits permanently, or you can suspend it, which permits you to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 reenter the Emacs process later. As a practical matter, you seldom kill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 Emacs---only when you are about to log out. Suspending is much more
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 common.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 * Killing Emacs:: Exiting Emacs irreversibly.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 * Suspending Emacs:: Exiting Emacs reversibly.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @node Killing Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 @subsection Killing Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 @cindex killing Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 Killing Emacs means ending the execution of the Emacs process. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 parent process normally resumes control. The low-level primitive for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 killing Emacs is @code{kill-emacs}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @defun kill-emacs &optional exit-data
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 This function exits the Emacs process and kills it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 If @var{exit-data} is an integer, then it is used as the exit status
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 of the Emacs process. (This is useful primarily in batch operation; see
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 @ref{Batch Mode}.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 If @var{exit-data} is a string, its contents are stuffed into the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 terminal input buffer so that the shell (or whatever program next reads
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 input) can read them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 All the information in the Emacs process, aside from files that have
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
482 been saved, is lost when the Emacs process is killed. Because killing
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
483 Emacs inadvertently can lose a lot of work, Emacs queries for
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
484 confirmation before actually terminating if you have buffers that need
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
485 saving or subprocesses that are running. This is done in the function
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
486 @code{save-buffers-kill-emacs}, the higher level function from which
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
487 @code{kill-emacs} is usually called.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 @defvar kill-emacs-query-functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 After asking the standard questions, @code{save-buffers-kill-emacs}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
491 calls the functions in the list @code{kill-emacs-query-functions}, in
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 order of appearance, with no arguments. These functions can ask for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 additional confirmation from the user. If any of them returns
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
494 @code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
495 does not run the remaining functions in this hook. Calling
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
496 @code{kill-emacs} directly does not run this hook.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 @defvar kill-emacs-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
501 finished with all file saving and confirmation, it calls
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
502 @code{kill-emacs} which runs the functions in this hook.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
503 @code{kill-emacs} does not run this hook in batch mode.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
504
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
505 @code{kill-emacs} may be invoked directly (that is not via
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
506 @code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
507 similar situations where interaction with the user is not possible.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
508 Thus, if your hook needs to interact with the user, put it on
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
509 @code{kill-emacs-query-functions}; if it needs to run regardless of
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
510 how Emacs is killed, put it on @code{kill-emacs-hook}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 @node Suspending Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 @subsection Suspending Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 @cindex suspending Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 control to its superior process, which is usually the shell. This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 allows you to resume editing later in the same Emacs process, with the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 same buffers, the same kill ring, the same undo history, and so on. To
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 resume Emacs, use the appropriate command in the parent shell---most
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 likely @code{fg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 Some operating systems do not support suspension of jobs; on these
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 systems, ``suspension'' actually creates a new shell temporarily as a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 subprocess of Emacs. Then you would exit the shell to return to Emacs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
528 Suspension is not useful with window systems, because the Emacs job
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
529 may not have a parent that can resume it again, and in any case you can
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
530 give input to some other job such as a shell merely by moving to a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
531 different window. Therefore, suspending is not allowed when Emacs is using
35476
26912db550c3 Change "X windows" instances.
Dave Love <fx@gnu.org>
parents: 33951
diff changeset
532 a window system (X or MS Windows).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
534 @defun suspend-emacs &optional string
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 This function stops Emacs and returns control to the superior process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 If and when the superior process resumes Emacs, @code{suspend-emacs}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 returns @code{nil} to its caller in Lisp.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 If @var{string} is non-@code{nil}, its characters are sent to be read
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 as terminal input by Emacs's superior shell. The characters in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 @var{string} are not echoed by the superior shell; only the results
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 appear.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 Before suspending, @code{suspend-emacs} runs the normal hook
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
545 @code{suspend-hook}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
547 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 @code{suspend-resume-hook}. @xref{Hooks}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 The next redisplay after resumption will redraw the entire screen,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 (@pxref{Refresh Screen}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 In the following example, note that @samp{pwd} is not echoed after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 Emacs is suspended. But it is read and executed by the shell.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 (suspend-emacs)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 (add-hook 'suspend-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 (function (lambda ()
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 (or (y-or-n-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 "Really suspend? ")
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
568 (error "Suspend canceled")))))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 @result{} (lambda nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 (or (y-or-n-p "Really suspend? ")
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
571 (error "Suspend canceled")))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 (add-hook 'suspend-resume-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 (function (lambda () (message "Resumed!"))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 @result{} (lambda nil (message "Resumed!"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 (suspend-emacs "pwd")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 ---------- Buffer: Minibuffer ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 Really suspend? @kbd{y}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 ---------- Buffer: Minibuffer ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 ---------- Parent Shell ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 lewis@@slug[23] % /user/lewis/manual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 lewis@@slug[24] % fg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 ---------- Echo Area ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 Resumed!
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
598 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 @defvar suspend-hook
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
602 This variable is a normal hook that Emacs runs before suspending.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 @defvar suspend-resume-hook
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
606 This variable is a normal hook that Emacs runs on resuming
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
607 after a suspension.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 @node System Environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 @section Operating System Environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 @cindex operating system environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 Emacs provides access to variables in the operating system environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 through various functions. These variables include the name of the
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52842
diff changeset
616 system, the user's @acronym{UID}, and so on.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
618 @defvar system-configuration
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63525
diff changeset
619 This variable holds the standard GNU configuration name for the
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63525
diff changeset
620 hardware/software configuration of your system, as a string. The
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63525
diff changeset
621 convenient way to test parts of this string is with
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63525
diff changeset
622 @code{string-match}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
623 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
624
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 @defvar system-type
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
626 The value of this variable is a symbol indicating the type of operating
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
627 system Emacs is operating on. Here is a table of the possible values:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 @table @code
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
630 @item alpha-vms
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
631 VMS on the Alpha.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
632
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 @item aix-v3
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 AIX.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 @item berkeley-unix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 Berkeley BSD.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
639 @item cygwin
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
640 Cygwin.
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
641
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
642 @item dgux
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
643 Data General DGUX operating system.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
644
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
645 @item gnu
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
646 the GNU system (using the GNU kernel, which consists of the HURD and Mach).
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
647
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
648 @item gnu/linux
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
649 A GNU/Linux system---that is, a variant GNU system, using the Linux
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
650 kernel. (These systems are the ones people often call ``Linux,'' but
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
651 actually Linux is just the kernel, not the whole system.)
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
652
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 @item hpux
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
654 Hewlett-Packard HPUX operating system.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656 @item irix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 Silicon Graphics Irix system.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
659 @item ms-dos
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
660 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
661 MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
662 MS-Windows.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
663
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
664 @item next-mach
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
665 NeXT Mach-based system.
7277
6a2af30d33fe *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
666
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 @item rtu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 Masscomp RTU, UCB universe.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 @item unisoft-unix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 UniSoft UniPlus.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 @item usg-unix-v
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 AT&T System V.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 @item vax-vms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 VAX VMS.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
679 @item windows-nt
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
680 Microsoft windows NT. The same executable supports Windows 9X, but the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
681 value of @code{system-type} is @code{windows-nt} in either case.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
682
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 @item xenix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684 SCO Xenix 386.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 We do not wish to add new symbols to make finer distinctions unless it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 is absolutely necessary! In fact, we hope to eliminate some of these
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 alternatives in the future. We recommend using
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 @code{system-configuration} to distinguish between different operating
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691 systems.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 @defun system-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 This function returns the name of the machine you are running on.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697 (system-name)
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
698 @result{} "www.gnu.org"
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
702 The symbol @code{system-name} is a variable as well as a function. In
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
703 fact, the function returns whatever value the variable
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
704 @code{system-name} currently holds. Thus, you can set the variable
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
705 @code{system-name} in case Emacs is confused about the name of your
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
706 system. The variable is also useful for constructing frame titles
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
707 (@pxref{Frame Titles}).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
708
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
709 @defvar mail-host-address
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
710 If this variable is non-@code{nil}, it is used instead of
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
711 @code{system-name} for purposes of generating email addresses. For
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
712 example, it is used when constructing the default value of
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
713 @code{user-mail-address}. @xref{User Identification}. (Since this is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
714 done when Emacs starts up, the value actually used is the one saved when
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
715 Emacs was dumped. @xref{Building Emacs}.)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
716 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
717
32839
4ab12a7fc269 getenv is a command
Dave Love <fx@gnu.org>
parents: 28635
diff changeset
718 @deffn Command getenv var
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 @cindex environment variable access
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 This function returns the value of the environment variable @var{var},
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
721 as a string. @var{var} should be a string. If @var{var} is undefined
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
722 in the environment, @code{getenv} returns @code{nil}. If returns
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
723 @samp{""} if @var{var} is set but null. Within Emacs, the environment
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
724 variable values are kept in the Lisp variable @code{process-environment}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 (getenv "USER")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 @result{} "lewis"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 lewis@@slug[10] % printenv
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 USER=lewis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 TERM=ibmapa16
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 SHELL=/bin/csh
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740 HOME=/user/lewis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 @end example
32924
b491fc65a56e *** empty log message ***
Dave Love <fx@gnu.org>
parents: 32839
diff changeset
743 @end deffn
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 @c Emacs 19 feature
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
746 @deffn Command setenv variable &optional value
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 This command sets the value of the environment variable named
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
748 @var{variable} to @var{value}. @var{variable} should be a string.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
749 Internally, Emacs Lisp can handle any string. However, normally
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
750 @var{variable} should be a valid shell identifier, that is, a sequence
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
751 of letters, digits and underscores, starting with a letter or
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
752 underscore. Otherwise, errors may occur if subprocesses of Emacs try
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
753 to access the value of @var{variable}. If @var{value} is omitted or
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
754 @code{nil}, @code{setenv} removes @var{variable} from the environment.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
755 Otherwise, @var{value} should be a string.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
756
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
757 @code{setenv} works by modifying @code{process-environment}; binding
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
758 that variable with @code{let} is also reasonable practice.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
759
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
760 @code{setenv} returns the new value of @var{variable}, or @code{nil}
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
761 if it removed @var{variable} from the environment.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 @defvar process-environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 This variable is a list of strings, each describing one environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 variable. The functions @code{getenv} and @code{setenv} work by means
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 of this variable.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 process-environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
774 "USER=lewis"
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776 @group
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
777 "TERM=ibmapa16"
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 "SHELL=/bin/csh"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779 "HOME=/user/lewis")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 @end smallexample
40311
a3a9223b152f Clarify what happens with duplicates in process-environment.
Richard M. Stallman <rms@gnu.org>
parents: 39221
diff changeset
782
a3a9223b152f Clarify what happens with duplicates in process-environment.
Richard M. Stallman <rms@gnu.org>
parents: 39221
diff changeset
783 If @code{process-environment} contains ``duplicate'' elements that
a3a9223b152f Clarify what happens with duplicates in process-environment.
Richard M. Stallman <rms@gnu.org>
parents: 39221
diff changeset
784 specify the same environment variable, the first of these elements
a3a9223b152f Clarify what happens with duplicates in process-environment.
Richard M. Stallman <rms@gnu.org>
parents: 39221
diff changeset
785 specifies the variable, and the other ``duplicates'' are ignored.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
788 @defvar path-separator
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
789 This variable holds a string which says which character separates
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
790 directories in a search path (as found in an environment variable). Its
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
791 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
792 and MS-Windows.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
793 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
794
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
795 @defun parse-colon-path path
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
796 @tindex parse-colon-path
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
797 This function takes a search path string such as would be the value of
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
798 the @code{PATH} environment variable, and splits it at the separators,
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
799 returning a list of directory names. @code{nil} in this list stands for
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
800 ``use the current directory.'' Although the function's name says
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
801 ``colon,'' it actually uses the value of @code{path-separator}.
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
802
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
803 @example
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
804 (parse-colon-path ":/foo:/bar")
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
805 @result{} (nil "/foo/" "/bar/")
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
806 @end example
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
807 @end defun
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
808
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
809 @defvar invocation-name
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
810 This variable holds the program name under which Emacs was invoked. The
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
811 value is a string, and does not include a directory name.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
812 @end defvar
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
813
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
814 @defvar invocation-directory
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
815 This variable holds the directory from which the Emacs executable was
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
816 invoked, or perhaps @code{nil} if that directory cannot be determined.
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
817 @end defvar
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
818
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
819 @defvar installation-directory
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
820 If non-@code{nil}, this is a directory within which to look for the
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
821 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil}
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
822 when Emacs can't find those directories in their standard installed
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
823 locations, but can find them in a directory related somehow to the one
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
824 containing the Emacs executable.
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
825 @end defvar
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
826
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
827 @defun load-average &optional use-float
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
828 This function returns the current 1-minute, 5-minute, and 15-minute load
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
829 averages, in a list.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
830
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
831 By default, the values are integers that are 100 times the system load
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
832 averages, which indicate the average number of processes trying to run.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
833 If @var{use-float} is non-@code{nil}, then they are returned
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
834 as floating point numbers and without multiplying by 100.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835
52842
1cc25f9733cf (System Environment): Clean up text for load-average errors.
Richard M. Stallman <rms@gnu.org>
parents: 52783
diff changeset
836 If it is impossible to obtain the load average, this function signals
1cc25f9733cf (System Environment): Clean up text for load-average errors.
Richard M. Stallman <rms@gnu.org>
parents: 52783
diff changeset
837 an error. On some platforms, access to load averages requires
1cc25f9733cf (System Environment): Clean up text for load-average errors.
Richard M. Stallman <rms@gnu.org>
parents: 52783
diff changeset
838 installing Emacs as setuid or setgid so that it can read kernel
1cc25f9733cf (System Environment): Clean up text for load-average errors.
Richard M. Stallman <rms@gnu.org>
parents: 52783
diff changeset
839 information, and that usually isn't advisable.
52783
3832b88b0957 Load average can throw error.
Dave Love <fx@gnu.org>
parents: 52401
diff changeset
840
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
841 If the 1-minute load average is available, but the 5- or 15-minute
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
842 averages are not, this function returns a shortened list containing
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
843 the available averages.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
844
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 (load-average)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 @result{} (169 48 36)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 @end group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
850 @group
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
851 (load-average t)
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
852 @result{} (1.69 0.48 0.36)
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
853 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 lewis@@rocky[5] % uptime
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 11:55am up 1 day, 19:37, 3 users,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858 load average: 1.69, 0.48, 0.36
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 @defun emacs-pid
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
864 This function returns the process @acronym{ID} of the Emacs process,
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
865 as an integer.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
868 @defvar tty-erase-char
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
869 This variable holds the erase character that was selected
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
870 in the system's terminal driver, before Emacs was started.
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
871 The value is @code{nil} if Emacs is running under a window system.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
872 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
873
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874 @defun setprv privilege-name &optional setp getprv
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 This function sets or resets a VMS privilege. (It does not exist on
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
876 other systems.) The first argument is the privilege name, as a string.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
877 The second argument, @var{setp}, is @code{t} or @code{nil}, indicating
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
878 whether the privilege is to be turned on or off. Its default is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
879 @code{nil}. The function returns @code{t} if successful, @code{nil}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
880 otherwise.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
881
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
882 If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883 does not change the privilege, but returns @code{t} or @code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 indicating whether the privilege is currently enabled.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 @node User Identification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888 @section User Identification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
890 @defvar init-file-user
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
891 This variable says which user's init files should be used by
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
892 Emacs---or @code{nil} if none. @code{""} stands for the user who
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
893 originally logged in. The value reflects command-line options such as
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
894 @samp{-q} or @samp{-u @var{user}}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
895
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
896 Lisp packages that load files of customizations, or any other sort of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
897 user profile, should obey this variable in deciding where to find it.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
898 They should load the profile of the user name found in this variable.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
899 If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
900 option was used, then Lisp packages should not load any customization
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
901 files or user profile.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
902 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
903
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
904 @defvar user-mail-address
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
905 This holds the nominal email address of the user who is using Emacs.
13367
a3e8c1d2492f Explain when user-mail-address is set.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
906 Emacs normally sets this variable to a default value after reading your
a3e8c1d2492f Explain when user-mail-address is set.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
907 init files, but not if you have already set it. So you can set the
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
908 variable to some other value in your init file if you do not
13367
a3e8c1d2492f Explain when user-mail-address is set.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
909 want to use the default value.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
910 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
911
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
912 @defun user-login-name &optional uid
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
913 If you don't specify @var{uid}, this function returns the name under
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
914 which the user is logged in. If the environment variable @code{LOGNAME}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
915 is set, that value is used. Otherwise, if the environment variable
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
916 @code{USER} is set, that value is used. Otherwise, the value is based
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52842
diff changeset
917 on the effective @acronym{UID}, not the real @acronym{UID}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
918
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
919 If you specify @var{uid}, the value is the user name that corresponds
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
920 to @var{uid} (which should be an integer), or @code{nil} if there is
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
921 no such user.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
922
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 (user-login-name)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926 @result{} "lewis"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
930
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
931 @defun user-real-login-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932 This function returns the user name corresponding to Emacs's real
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52842
diff changeset
933 @acronym{UID}. This ignores the effective @acronym{UID} and ignores the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 environment variables @code{LOGNAME} and @code{USER}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
937 @defun user-full-name &optional uid
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
938 This function returns the full name of the logged-in user---or the value
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
939 of the environment variable @code{NAME}, if that is set.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
941 @c "Bil" is the correct spelling.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 (user-full-name)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 @result{} "Bil Lewis"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 @end example
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
948
24848
ca34063731fc *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 23147
diff changeset
949 If the Emacs job's user-id does not correspond to any known user (and
ca34063731fc *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 23147
diff changeset
950 provided @code{NAME} is not set), the value is @code{"unknown"}.
ca34063731fc *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 23147
diff changeset
951
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
952 If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
24848
ca34063731fc *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 23147
diff changeset
953 or a string (a login name). Then @code{user-full-name} returns the full
ca34063731fc *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 23147
diff changeset
954 name corresponding to that user-id or login name. If you specify a
ca34063731fc *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 23147
diff changeset
955 user-id or login name that isn't defined, it returns @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
958 @vindex user-full-name
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
959 @vindex user-real-login-name
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
960 @vindex user-login-name
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
961 The symbols @code{user-login-name}, @code{user-real-login-name} and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
962 @code{user-full-name} are variables as well as functions. The functions
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
963 return the same values that the variables hold. These variables allow
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
964 you to ``fake out'' Emacs by telling the functions what to return. The
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
965 variables are also useful for constructing frame titles (@pxref{Frame
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
966 Titles}).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
967
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 @defun user-real-uid
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52842
diff changeset
969 This function returns the real @acronym{UID} of the user.
51918
9fbd3ef3087d (User Identification): user-uid, user-real-uid can return float.
Richard M. Stallman <rms@gnu.org>
parents: 50654
diff changeset
970 The value may be a floating point number.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 (user-real-uid)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 @result{} 19
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 @defun user-uid
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52842
diff changeset
981 This function returns the effective @acronym{UID} of the user.
51918
9fbd3ef3087d (User Identification): user-uid, user-real-uid can return float.
Richard M. Stallman <rms@gnu.org>
parents: 50654
diff changeset
982 The value may be a floating point number.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 @node Time of Day
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 @section Time of Day
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 This section explains how to determine the current time and the time
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989 zone.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991 @defun current-time-string &optional time-value
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
992 This function returns the current time and date as a human-readable
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993 string. The format of the string is unvarying; the number of characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 used for each part is always the same, so you can reliably use
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
995 @code{substring} to extract pieces of it. It is wise to count the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
996 characters from the beginning of the string rather than from the end, as
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
997 additional information may some day be added at the end.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 The argument @var{time-value}, if given, specifies a time to format
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1001 instead of the current time. The argument should be a list whose first
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1002 two elements are integers. Thus, you can use times obtained from
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1003 @code{current-time} (see below) and from @code{file-attributes}
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1004 (@pxref{Definition of file-attributes}). @var{time-value} can also be
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1005 a cons of two integers, but this is considered obsolete.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009 (current-time-string)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 @result{} "Wed Oct 14 22:21:05 1987"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016 @defun current-time
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 This function returns the system's time value as a list of three
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019 @var{high} and @var{low} combine to give the number of seconds since
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1020 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1021 @ifnottex
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 @var{high} * 2**16 + @var{low}.
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1023 @end ifnottex
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1024 @tex
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
1025 $high*2^{16}+low$.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026 @end tex
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 The third element, @var{microsec}, gives the microseconds since the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1029 start of the current second (or 0 for systems that return time with
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1030 the resolution of only one second).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 The first two elements can be compared with file time values such as you
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1033 get with the function @code{file-attributes}.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1034 @xref{Definition of file-attributes}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1035 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038 @defun current-time-zone &optional time-value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039 This function returns a list describing the time zone that the user is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040 in.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 The value has the form @code{(@var{offset} @var{name})}. Here
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043 @var{offset} is an integer giving the number of seconds ahead of UTC
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044 (east of Greenwich). A negative value means west of Greenwich. The
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1045 second element, @var{name}, is a string giving the name of the time
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 zone. Both elements change when daylight savings time begins or ends;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 if the user has specified a time zone that does not use a seasonal time
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048 adjustment, then the value is constant through time.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050 If the operating system doesn't supply all the information necessary to
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1051 compute the value, the unknown elements of the list are @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 The argument @var{time-value}, if given, specifies a time to analyze
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1054 instead of the current time. The argument should have the same form
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1055 as for @code{current-time-string} (see above). Thus, you can use
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1056 times obtained from @code{current-time} (see above) and from
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1057 @code{file-attributes}. @xref{Definition of file-attributes}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1058 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1059
53433
5bf3c4457aa3 (Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
1060 @defun set-time-zone-rule tz
5bf3c4457aa3 (Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
1061 This function specifies the local time zone according to @var{tz}. If
5bf3c4457aa3 (Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
1062 @var{tz} is @code{nil}, that means to use an implementation-defined
5bf3c4457aa3 (Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
1063 default time zone. If @var{tz} is @code{t}, that means to use
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1064 Universal Time. Otherwise, @var{tz} should be a string specifying a
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1065 time zone rule.
53433
5bf3c4457aa3 (Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
1066 @end defun
5bf3c4457aa3 (Time of Day): Add set-time-zone-rule.
Richard M. Stallman <rms@gnu.org>
parents: 52978
diff changeset
1067
39202
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1068 @defun float-time &optional time-value
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1069 This function returns the current time as a floating-point number of
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1070 seconds since the epoch. The argument @var{time-value}, if given,
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1071 specifies a time to convert instead of the current time. The argument
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1072 should have the same form as for @code{current-time-string} (see
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1073 above). Thus, it accepts the output of @code{current-time} and
39202
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1074 @code{file-attributes}.
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1075
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1076 @emph{Warning}: Since the result is floating point, it may not be
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1077 exact. Do not use this function if precise time stamps are required.
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1078 @end defun
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1079
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1080 @node Time Conversion
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1081 @section Time Conversion
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1082
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1083 These functions convert time values (lists of two or three integers)
64914
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1084 to calendrical information and vice versa. You can get time values
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1085 from the functions @code{current-time} (@pxref{Time of Day}) and
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1086 @code{file-attributes} (@pxref{Definition of file-attributes}).
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1087
64914
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1088 Many operating systems are limited to time values that contain 32 bits
15778
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1089 of information; these systems typically handle only the times from
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1090 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1091 operating systems have larger time values, and can represent times far
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1092 in the past or future.
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1093
64914
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1094 Time conversion functions always use the Gregorian calendar, even
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1095 for dates before the Gregorian calendar was introduced. Year numbers
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1096 count the number of years since the year 1 B.C., and do not skip zero
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1097 as traditional Gregorian years do; for example, the year number
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1098 @minus{}37 represents the Gregorian year 38 B.C@.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1099
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1100 @defun decode-time &optional time
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1101 This function converts a time value into calendrical information. If
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1102 you don't specify @var{time}, it decodes the current time. The return
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1103 value is a list of nine elements, as follows:
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1104
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1105 @example
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1106 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1107 @end example
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1108
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1109 Here is what the elements mean:
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1110
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1111 @table @var
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1112 @item seconds
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1113 The number of seconds past the minute, as an integer between 0 and 59.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1114 On some operating systems, this is 60 for leap seconds.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1115 @item minutes
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1116 The number of minutes past the hour, as an integer between 0 and 59.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1117 @item hour
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1118 The hour of the day, as an integer between 0 and 23.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1119 @item day
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1120 The day of the month, as an integer between 1 and 31.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1121 @item month
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1122 The month of the year, as an integer between 1 and 12.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1123 @item year
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1124 The year, an integer typically greater than 1900.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1125 @item dow
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1126 The day of week, as an integer between 0 and 6, where 0 stands for
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1127 Sunday.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1128 @item dst
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1129 @code{t} if daylight savings time is effect, otherwise @code{nil}.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1130 @item zone
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1131 An integer indicating the time zone, as the number of seconds east of
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1132 Greenwich.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1133 @end table
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1134
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1135 @strong{Common Lisp Note:} Common Lisp has different meanings for
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1136 @var{dow} and @var{zone}.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1137 @end defun
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1138
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1139 @defun encode-time seconds minutes hour day month year &optional zone
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1140 This function is the inverse of @code{decode-time}. It converts seven
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1141 items of calendrical data into a time value. For the meanings of the
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1142 arguments, see the table above under @code{decode-time}.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1143
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1144 Year numbers less than 100 are not treated specially. If you want them
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1145 to stand for years above 1900, or years above 2000, you must alter them
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1146 yourself before you call @code{encode-time}.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1147
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1148 The optional argument @var{zone} defaults to the current time zone and
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1149 its daylight savings time rules. If specified, it can be either a list
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1150 (as you would get from @code{current-time-zone}), a string as in the
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1151 @code{TZ} environment variable, @code{t} for Universal Time, or an
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1152 integer (as you would get from @code{decode-time}). The specified
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1153 zone is used without any further alteration for daylight savings time.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1154
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1155 If you pass more than seven arguments to @code{encode-time}, the first
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1156 six are used as @var{seconds} through @var{year}, the last argument is
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1157 used as @var{zone}, and the arguments in between are ignored. This
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1158 feature makes it possible to use the elements of a list returned by
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1159 @code{decode-time} as the arguments to @code{encode-time}, like this:
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1160
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1161 @example
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1162 (apply 'encode-time (decode-time @dots{}))
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1163 @end example
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1164
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1165 You can perform simple date arithmetic by using out-of-range values for
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1166 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1167 arguments; for example, day 0 means the day preceding the given month.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1168
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1169 The operating system puts limits on the range of possible time values;
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1170 if you try to encode a time that is out of range, an error results.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1171 For instance, years before 1970 do not work on some systems;
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1172 on others, years as early as 1901 do work.
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1173 @end defun
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1174
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1175 @node Time Parsing
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1176 @section Parsing and Formatting Times
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1177
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1178 These functions convert time values (lists of two or three integers)
6ed6c1b79d36 (Time Parsing): New node split out of Time Conversion.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
1179 to text in a string, and vice versa.
15778
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1180
43037
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1181 @defun date-to-time string
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1182 This function parses the time-string @var{string} and returns the
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1183 corresponding time value.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1184 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1185
26242
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1186 @defun format-time-string format-string &optional time universal
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1187 This function converts @var{time} (or the current time, if @var{time} is
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1188 omitted) to a string according to @var{format-string}. The argument
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1189 @var{format-string} may contain @samp{%}-sequences which say to
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1190 substitute parts of the time. Here is a table of what the
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1191 @samp{%}-sequences mean:
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1192
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1193 @table @samp
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1194 @item %a
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1195 This stands for the abbreviated name of the day of week.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1196 @item %A
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1197 This stands for the full name of the day of week.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1198 @item %b
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1199 This stands for the abbreviated name of the month.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1200 @item %B
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1201 This stands for the full name of the month.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1202 @item %c
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1203 This is a synonym for @samp{%x %X}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1204 @item %C
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1205 This has a locale-specific meaning. In the default locale (named C), it
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1206 is equivalent to @samp{%A, %B %e, %Y}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1207 @item %d
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1208 This stands for the day of month, zero-padded.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1209 @item %D
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1210 This is a synonym for @samp{%m/%d/%y}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1211 @item %e
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1212 This stands for the day of month, blank-padded.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1213 @item %h
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1214 This is a synonym for @samp{%b}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1215 @item %H
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1216 This stands for the hour (00-23).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1217 @item %I
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1218 This stands for the hour (01-12).
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1219 @item %j
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1220 This stands for the day of the year (001-366).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1221 @item %k
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1222 This stands for the hour (0-23), blank padded.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1223 @item %l
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1224 This stands for the hour (1-12), blank padded.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1225 @item %m
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1226 This stands for the month (01-12).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1227 @item %M
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1228 This stands for the minute (00-59).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1229 @item %n
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1230 This stands for a newline.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1231 @item %p
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1232 This stands for @samp{AM} or @samp{PM}, as appropriate.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1233 @item %r
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1234 This is a synonym for @samp{%I:%M:%S %p}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1235 @item %R
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1236 This is a synonym for @samp{%H:%M}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1237 @item %S
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1238 This stands for the seconds (00-59).
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1239 @item %t
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1240 This stands for a tab character.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1241 @item %T
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1242 This is a synonym for @samp{%H:%M:%S}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1243 @item %U
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1244 This stands for the week of the year (01-52), assuming that weeks
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1245 start on Sunday.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1246 @item %w
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1247 This stands for the numeric day of week (0-6). Sunday is day 0.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1248 @item %W
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1249 This stands for the week of the year (01-52), assuming that weeks
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1250 start on Monday.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1251 @item %x
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1252 This has a locale-specific meaning. In the default locale (named
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1253 @samp{C}), it is equivalent to @samp{%D}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1254 @item %X
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1255 This has a locale-specific meaning. In the default locale (named
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1256 @samp{C}), it is equivalent to @samp{%T}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1257 @item %y
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1258 This stands for the year without century (00-99).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1259 @item %Y
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1260 This stands for the year with century.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1261 @item %Z
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1262 This stands for the time zone abbreviation.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1263 @end table
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1264
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1265 You can also specify the field width and type of padding for any of
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1266 these @samp{%}-sequences. This works as in @code{printf}: you write
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1267 the field width as digits in the middle of a @samp{%}-sequences. If you
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1268 start the field width with @samp{0}, it means to pad with zeros. If you
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1269 start the field width with @samp{_}, it means to pad with spaces.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1270
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1271 For example, @samp{%S} specifies the number of seconds since the minute;
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1272 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1273 pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1274 because that is how @samp{%S} normally pads to two positions.
26242
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1275
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1276 The characters @samp{E} and @samp{O} act as modifiers when used between
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1277 @samp{%} and one of the letters in the table above. @samp{E} specifies
26288
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1278 using the current locale's ``alternative'' version of the date and time.
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1279 In a Japanese locale, for example, @code{%Ex} might yield a date format
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1280 based on the Japanese Emperors' reigns. @samp{E} is allowed in
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1281 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1282 @samp{%EY}.
26242
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1283
26288
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1284 @samp{O} means to use the current locale's ``alternative''
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1285 representation of numbers, instead of the ordinary decimal digits. This
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1286 is allowed with most letters, all the ones that output numbers.
26242
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1287
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1288 If @var{universal} is non-@code{nil}, that means to describe the time as
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1289 Universal Time; @code{nil} means describe it using what Emacs believes
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1290 is the local time zone (see @code{current-time-zone}).
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1291
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1292 This function uses the C library function @code{strftime} to do most of
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1293 the work. In order to communicate with that function, it first encodes
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1294 its argument using the coding system specified by
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1295 @code{locale-coding-system} (@pxref{Locales}); after @code{strftime}
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1296 returns the resulting string, @code{format-time-string} decodes the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1297 string using that same coding system.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1298 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1299
43037
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1300 @defun seconds-to-time seconds
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1301 This function converts @var{seconds}, a floating point number of
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1302 seconds since the epoch, to a time value and returns that. To perform
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1303 the inverse conversion, use @code{float-time}.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1304 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1305
57989
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1306 @node Processor Run Time
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1307 @section Processor Run time
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1308
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1309 @defun get-internal-run-time
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1310 This function returns the processor run time used by Emacs as a list
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1311 of three integers: @code{(@var{high} @var{low} @var{microsec})}. The
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1312 integers @var{high} and @var{low} combine to give the number of
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1313 seconds, which is
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1314 @ifnottex
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1315 @var{high} * 2**16 + @var{low}.
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1316 @end ifnottex
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1317 @tex
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1318 $high*2^{16}+low$.
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1319 @end tex
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1320
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1321 The third element, @var{microsec}, gives the microseconds (or 0 for
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1322 systems that return time with the resolution of only one second).
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1323
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1324 If the system doesn't provide a way to determine the processor run
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1325 time, get-internal-run-time returns the same time as current-time.
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1326 @end defun
2f160b3f3283 (Processor Run Time): New section documenting get-internal-run-time.
Eli Zaretskii <eliz@gnu.org>
parents: 56617
diff changeset
1327
43037
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1328 @node Time Calculations
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1329 @section Time Calculations
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1330
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1331 These functions perform calendrical computations using time values
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1332 (the kind of list that @code{current-time} returns).
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1333
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1334 @defun time-less-p t1 t2
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1335 This returns @code{t} if time value @var{t1} is less than time value
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1336 @var{t2}.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1337 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1338
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1339 @defun time-subtract t1 t2
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1340 This returns the time difference @var{t1} @minus{} @var{t2} between
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1341 two time values, in the same format as a time value.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1342 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1343
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1344 @defun time-add t1 t2
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1345 This returns the sum of two time values, one of which ought to
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1346 represent a time difference rather than a point in time.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1347 Here is how to add a number of seconds to a time value:
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1348
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1349 @example
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1350 (time-add @var{time} (seconds-to-time @var{seconds}))
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1351 @end example
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1352 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1353
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1354 @defun time-to-days time
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1355 This function returns the number of days between the beginning of year
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1356 1 and @var{time}.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1357 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1358
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1359 @defun time-to-day-in-year time
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1360 This returns the day number within the year corresponding to @var{time}.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1361 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1362
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1363 @defun date-leap-year-p year
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1364 This function returns @code{t} if @var{year} is a leap year.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1365 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1366
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 @node Timers
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1368 @section Timers for Delayed Execution
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1369 @cindex timer
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370
50654
07caa9606def (Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 50475
diff changeset
1371 You can set up a @dfn{timer} to call a function at a specified
07caa9606def (Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 50475
diff changeset
1372 future time or after a certain length of idleness.
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1373
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1374 Emacs cannot run timers at any arbitrary point in a Lisp program; it
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1375 can run them only when Emacs could accept output from a subprocess:
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1376 namely, while waiting or inside certain primitive functions such as
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1377 @code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1378 timer's execution may be delayed if Emacs is busy. However, the time of
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1379 execution is very precise if Emacs is idle.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1380
50654
07caa9606def (Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 50475
diff changeset
1381 Emacs binds @code{inhibit-quit} to @code{t} before calling the timer
07caa9606def (Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 50475
diff changeset
1382 function, because quitting out of many timer functions can leave
07caa9606def (Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 50475
diff changeset
1383 things in an inconsistent state. This is normally unproblematical
07caa9606def (Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 50475
diff changeset
1384 because most timer functions don't do a lot of work. Indeed, for a
54037
96796d3ede2e Minor fix.
Richard M. Stallman <rms@gnu.org>
parents: 53433
diff changeset
1385 timer to call a function that takes substantial time to run is likely
50654
07caa9606def (Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 50475
diff changeset
1386 to be annoying.
07caa9606def (Timers): Explain about timers and quitting.
Richard M. Stallman <rms@gnu.org>
parents: 50475
diff changeset
1387
59270
08777d10acff (Timers): Update previous change.
Richard M. Stallman <rms@gnu.org>
parents: 59190
diff changeset
1388 It is usually a bad idea for timer functions to alter buffer
08777d10acff (Timers): Update previous change.
Richard M. Stallman <rms@gnu.org>
parents: 59190
diff changeset
1389 contents. When they do, they usually should call @code{undo-boundary}
08777d10acff (Timers): Update previous change.
Richard M. Stallman <rms@gnu.org>
parents: 59190
diff changeset
1390 both before and after changing the buffer, to separate the timer's
59390
70a8ca9b81e0 (Timers): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 59270
diff changeset
1391 changes from user commands' changes and prevent a single undo entry
70a8ca9b81e0 (Timers): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 59270
diff changeset
1392 from growing to be quite large.
59190
6142d449ffb8 (Timers): Discuss timers vs editing the buffer and undo.
Richard M. Stallman <rms@gnu.org>
parents: 57989
diff changeset
1393
63525
da42b07587f1 (Timers): Timers should save and restore the match data if they change it.
Luc Teirlinck <teirllm@auburn.edu>
parents: 60996
diff changeset
1394 If a timer function calls functions that can change the match data,
da42b07587f1 (Timers): Timers should save and restore the match data if they change it.
Luc Teirlinck <teirllm@auburn.edu>
parents: 60996
diff changeset
1395 it should save and restore the match data. @xref{Saving Match Data}.
da42b07587f1 (Timers): Timers should save and restore the match data if they change it.
Luc Teirlinck <teirllm@auburn.edu>
parents: 60996
diff changeset
1396
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1397 @deffn Command run-at-time time repeat function &rest args
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1398 This sets up a timer that calls the function @var{function} with
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1399 arguments @var{args} at time @var{time}. If @var{repeat} is a number
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1400 (integer or floating point), the timer also runs every @var{repeat}
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1401 seconds after that. If @var{repeat} is @code{nil}, the timer runs
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1402 only once.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1403
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1404 @var{time} may specify an absolute or a relative time.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1406 Absolute times may be specified in a wide variety of formats; this
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1407 function tries to accept all the commonly used date formats. The most
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1408 convenient formats are strings. Valid such formats include these two,
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1409
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1410 @example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1411 @var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1412
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1413 @var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1414 @end example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1415
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1416 @noindent
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1417 where in both examples all fields are numbers; the format that
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1418 @code{current-time-string} returns is also allowed, and many others
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1419 as well.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1421 To specify a relative time as a string, use numbers followed by units.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1422 For example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1423
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 @table @samp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1425 @item 1 min
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1426 denotes 1 minute from now.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1427 @item 1 min 5 sec
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1428 denotes 65 seconds from now.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1429 @item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1430 denotes exactly 103 months, 123 days, and 10862 seconds from now.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1431 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1432
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1433 For relative time values, Emacs considers a month to be exactly thirty
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1434 days, and a year to be exactly 365.25 days.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1435
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1436 Not all convenient formats are strings. If @var{time} is a number
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1437 (integer or floating point), that specifies a relative time measured
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1438 in seconds.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1439
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1440 In most cases, @var{repeat} has no effect on when @emph{first} call
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1441 takes place---@var{time} alone specifies that. There is one exception:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1442 if @var{time} is @code{t}, then the timer runs whenever the time is a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1443 multiple of @var{repeat} seconds after the epoch. This is useful for
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1444 functions like @code{display-time}.
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
1445
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
1446 The function @code{run-at-time} returns a timer value that identifies
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
1447 the particular scheduled future action. You can use this value to call
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1448 @code{cancel-timer} (see below).
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1449 @end deffn
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1450
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1451 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1452 Execute @var{body}, but give up after @var{seconds} seconds. If
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1453 @var{body} finishes before the time is up, @code{with-timeout} returns
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1454 the value of the last form in @var{body}. If, however, the execution of
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1455 @var{body} is cut short by the timeout, then @code{with-timeout}
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1456 executes all the @var{timeout-forms} and returns the value of the last
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1457 of them.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1458
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1459 This macro works by setting a timer to run after @var{seconds} seconds. If
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1460 @var{body} finishes before that time, it cancels the timer. If the
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1461 timer actually runs, it terminates execution of @var{body}, then
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1462 executes @var{timeout-forms}.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1463
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1464 Since timers can run within a Lisp program only when the program calls a
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1465 primitive that can wait, @code{with-timeout} cannot stop executing
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1466 @var{body} while it is in the midst of a computation---only when it
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1467 calls one of those primitives. So use @code{with-timeout} only with a
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1468 @var{body} that waits for input, not one that does a long computation.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1469 @end defmac
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1470
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1471 The function @code{y-or-n-p-with-timeout} provides a simple way to use
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1472 a timer to avoid waiting too long for an answer. @xref{Yes-or-No
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1473 Queries}.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1474
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1475 @deffn Command run-with-idle-timer secs repeat function &rest args
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1476 Set up a timer which runs when Emacs has been idle for @var{secs}
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1477 seconds. The value of @var{secs} may be an integer or a floating point
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1478 number.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1479
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1480 If @var{repeat} is @code{nil}, the timer runs just once, the first time
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1481 Emacs remains idle for a long enough time. More often @var{repeat} is
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1482 non-@code{nil}, which means to run the timer @emph{each time} Emacs
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1483 remains idle for @var{secs} seconds.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1484
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1485 The function @code{run-with-idle-timer} returns a timer value which you
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1486 can use in calling @code{cancel-timer} (see below).
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1487 @end deffn
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1488
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1489 @cindex idleness
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1490 Emacs becomes ``idle'' when it starts waiting for user input, and it
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1491 remains idle until the user provides some input. If a timer is set for
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1492 five seconds of idleness, it runs approximately five seconds after Emacs
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1493 first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1494 will not run again as long as Emacs remains idle, because the duration
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1495 of idleness will continue to increase and will not go down to five
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1496 seconds again.
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1497
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1498 Emacs can do various things while idle: garbage collect, autosave or
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1499 handle data from a subprocess. But these interludes during idleness do
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1500 not interfere with idle timers, because they do not reset the clock of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1501 idleness to zero. An idle timer set for 600 seconds will run when ten
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1502 minutes have elapsed since the last user command was finished, even if
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1503 subprocess output has been accepted thousands of times within those ten
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1504 minutes, and even if there have been garbage collections and autosaves.
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1505
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1506 When the user supplies input, Emacs becomes non-idle while executing the
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1507 input. Then it becomes idle again, and all the idle timers that are
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1508 set up to repeat will subsequently run another time, one by one.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1509
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1510 @defun cancel-timer timer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1511 Cancel the requested action for @var{timer}, which should be a value
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1512 previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1513 This cancels the effect of that call to one of these functions; the
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1514 arrival of the specified time will not cause anything special to happen.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1515 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1516
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1517 @node Terminal Input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518 @section Terminal Input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1519 @cindex terminal input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1520
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1521 This section describes functions and variables for recording or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1522 manipulating terminal input. See @ref{Display}, for related
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1523 functions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1524
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1525 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526 * Input Modes:: Options for how input is processed.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1527 * Translating Input:: Low level conversion of some characters or events
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1528 into others.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1529 * Recording Input:: Saving histories of recent or all input events.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1530 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1532 @node Input Modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533 @subsection Input Modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1534 @cindex input modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1535 @cindex terminal input modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1537 @defun set-input-mode interrupt flow meta &optional quit-char
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538 This function sets the mode for reading keyboard input. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539 @var{interrupt} is non-null, then Emacs uses input interrupts. If it is
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1540 @code{nil}, then it uses @sc{cbreak} mode. The default setting is
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1541 system-dependent. Some systems always use @sc{cbreak} mode regardless
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1542 of what is specified.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1544 When Emacs communicates directly with X, it ignores this argument and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1545 uses interrupts if that is the way it knows how to communicate.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1546
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1547 If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1548 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
1549 has no effect except in @sc{cbreak} mode.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1550
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1551 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1552 The argument @var{meta} controls support for input character codes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1553 above 127. If @var{meta} is @code{t}, Emacs converts characters with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1554 the 8th bit set into Meta characters. If @var{meta} is @code{nil},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1555 Emacs disregards the 8th bit; this is necessary when the terminal uses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1556 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1557 Emacs uses all 8 bits of input unchanged. This is good for terminals
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1558 that use 8-bit character sets.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1559
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1560 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1561 If @var{quit-char} is non-@code{nil}, it specifies the character to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1562 use for quitting. Normally this character is @kbd{C-g}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1563 @xref{Quitting}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1565
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1566 The @code{current-input-mode} function returns the input mode settings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1567 Emacs is currently using.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1568
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1569 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1570 @defun current-input-mode
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1571 This function returns the current mode for reading keyboard input. It
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1572 returns a list, corresponding to the arguments of @code{set-input-mode},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1573 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574 which:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1575 @table @var
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1576 @item interrupt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1577 is non-@code{nil} when Emacs is using interrupt-driven input. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1578 @code{nil}, Emacs is using @sc{cbreak} mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1579 @item flow
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1580 is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1581 flow control for output to the terminal. This value is meaningful only
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1582 when @var{interrupt} is @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1583 @item meta
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1584 is @code{t} if Emacs treats the eighth bit of input characters as
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1585 the meta bit; @code{nil} means Emacs clears the eighth bit of every
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1586 input character; any other value means Emacs uses all eight bits as the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1587 basic character code.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1588 @item quit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1589 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1590 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1591 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1592
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1593 @node Translating Input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1594 @subsection Translating Input Events
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1595 @cindex translating input events
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1596
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1597 This section describes features for translating input events into
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1598 other input events before they become part of key sequences. These
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1599 features apply to each event in the order they are described here: each
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1600 event is first modified according to @code{extra-keyboard-modifiers},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1601 then translated through @code{keyboard-translate-table} (if applicable),
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1602 and finally decoded with the specified keyboard coding system. If it is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1603 being read as part of a key sequence, it is then added to the sequence
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1604 being read; then subsequences containing it are checked first with
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1605 @code{function-key-map} and then with @code{key-translation-map}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1606
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1607 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1608 @defvar extra-keyboard-modifiers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1609 This variable lets Lisp programs ``press'' the modifier keys on the
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1610 keyboard. The value is a character. Only the modifiers of the
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1611 character matter. Each time the user types a keyboard key, it is
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1612 altered as if those modifier keys were held down. For instance, if
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1613 you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1614 keyboard input characters typed during the scope of the binding will
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1615 have the control and meta modifiers applied to them. The character
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1616 @code{?\C-@@}, equivalent to the integer 0, does not count as a control
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1617 character for this purpose, but as a character with no modifiers.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1618 Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1619 modification.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1620
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1621 When using a window system, the program can ``press'' any of the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1622 modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1623 keys can be virtually pressed.
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1624
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1625 Note that this variable applies only to events that really come from
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1626 the keyboard, and has no effect on mouse events or any other events.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1627 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1628
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1629 @defvar keyboard-translate-table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630 This variable is the translate table for keyboard characters. It lets
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1631 you reshuffle the keys on the keyboard without changing any command
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1632 bindings. Its value is normally a char-table, or else @code{nil}.
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1633 (It can also be a string or vector, but this is considered obsolete.)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1634
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1635 If @code{keyboard-translate-table} is a char-table
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1636 (@pxref{Char-Tables}), then each character read from the keyboard is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1637 looked up in this char-table. If the value found there is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1638 non-@code{nil}, then it is used instead of the actual input character.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1639
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1640 Note that this translation is the first thing that happens to a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1641 character after it is read from the terminal. Record-keeping features
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1642 such as @code{recent-keys} and dribble files record the characters after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1643 translation.
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1644
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1645 Note also that this translation is done before the characters are
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1646 supplied to input methods (@pxref{Input Methods}). Use
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1647 @code{translation-table-for-input} (@pxref{Translation of Characters}),
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1648 if you want to translate characters after input methods operate.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1649 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1650
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1651 @defun keyboard-translate from to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1652 This function modifies @code{keyboard-translate-table} to translate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1653 character code @var{from} into character code @var{to}. It creates
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1654 the keyboard translate table if necessary.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1655 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1656
60452
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1657 Here's an example of using the @code{keyboard-translate-table} to
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1658 make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1659 operations:
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1660
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1661 @example
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1662 (keyboard-translate ?\C-x 'control-x)
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1663 (keyboard-translate ?\C-c 'control-c)
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1664 (keyboard-translate ?\C-v 'control-v)
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1665 (global-set-key [control-x] 'kill-region)
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1666 (global-set-key [control-c] 'kill-ring-save)
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1667 (global-set-key [control-v] 'yank)
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1668 @end example
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1669
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1670 @noindent
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1671 On a graphical terminal that supports extended @acronym{ASCII} input,
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1672 you can still get the standard Emacs meanings of one of those
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1673 characters by typing it with the shift key. That makes it a different
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1674 character as far as keyboard translation is concerned, but it has the
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1675 same usual meaning.
53520941e72d (Translating Input): Replace flow-control example
Richard M. Stallman <rms@gnu.org>
parents: 60269
diff changeset
1676
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1677 The remaining translation features translate subsequences of key
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1678 sequences being read. They are implemented in @code{read-key-sequence}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1679 and have no effect on input read with @code{read-event}.
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1680
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1681 @defvar function-key-map
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1682 This variable holds a keymap that describes the character sequences sent
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1683 by function keys on an ordinary character terminal. This keymap has the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1684 same structure as other keymaps, but is used differently: it specifies
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1685 translations to make while reading key sequences, rather than bindings
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1686 for key sequences.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1687
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1688 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1689 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1690 key sequence, it is replaced with the events in @var{v}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1691
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1692 For example, VT100 terminals send @kbd{@key{ESC} O P} when the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1693 keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1694 that sequence of events into the single event @code{pf1}. We accomplish
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1695 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1696 @code{function-key-map}, when using a VT100.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1697
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1698 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1699 @key{ESC} O P}; later the function @code{read-key-sequence} translates
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1700 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1701 @code{[?\C-c pf1]}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1702
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1703 Entries in @code{function-key-map} are ignored if they conflict with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1704 bindings made in the minor mode, local, or global keymaps. The intent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1705 is that the character sequences that function keys send should not have
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1706 command bindings in their own right---but if they do, the ordinary
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1707 bindings take priority.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1708
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1709 The value of @code{function-key-map} is usually set up automatically
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1710 according to the terminal's Terminfo or Termcap entry, but sometimes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1711 those need help from terminal-specific Lisp files. Emacs comes with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1712 terminal-specific files for many common terminals; their main purpose is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1713 to make entries in @code{function-key-map} beyond those that can be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1714 deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1715 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1716
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1717 @defvar key-translation-map
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1718 This variable is another keymap used just like @code{function-key-map}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1719 to translate input events into other events. It differs from
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1720 @code{function-key-map} in two ways:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1721
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1722 @itemize @bullet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1723 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1724 @code{key-translation-map} goes to work after @code{function-key-map} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1725 finished; it receives the results of translation by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1726 @code{function-key-map}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1727
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1728 @item
56617
8685ad649821 (Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents: 56369
diff changeset
1729 Non-prefix bindings in @code{key-translation-map} override actual key
8685ad649821 (Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents: 56369
diff changeset
1730 bindings. For example, if @kbd{C-x f} has a non-prefix binding in
8685ad649821 (Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents: 56369
diff changeset
1731 @code{key-translation-map}, that translation takes effect even though
8685ad649821 (Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents: 56369
diff changeset
1732 @kbd{C-x f} also has a key binding in the global map.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1733 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1734
56617
8685ad649821 (Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents: 56369
diff changeset
1735 Note however that actual key bindings can have an effect on
8685ad649821 (Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents: 56369
diff changeset
1736 @code{key-translation-map}, even though they are overridden by it.
8685ad649821 (Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents: 56369
diff changeset
1737 Indeed, actual key bindings override @code{function-key-map} and thus
8685ad649821 (Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents: 56369
diff changeset
1738 may alter the key sequence that @code{key-translation-map} receives.
64290
25e7c854aa97 (Translating Input): Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 63583
diff changeset
1739 Clearly, it is better to avoid this type of situation.
56617
8685ad649821 (Translating Input): Only non-prefix bindings in `key-translation-map'
Luc Teirlinck <teirllm@auburn.edu>
parents: 56369
diff changeset
1740
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1741 The intent of @code{key-translation-map} is for users to map one
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1742 character set to another, including ordinary characters normally bound
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1743 to @code{self-insert-command}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1744 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1745
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1746 @cindex key translation function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1747 You can use @code{function-key-map} or @code{key-translation-map} for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1748 more than simple aliases, by using a function, instead of a key
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1749 sequence, as the ``translation'' of a key. Then this function is called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1750 to compute the translation of that key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1751
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1752 The key translation function receives one argument, which is the prompt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1753 that was specified in @code{read-key-sequence}---or @code{nil} if the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1754 key sequence is being read by the editor command loop. In most cases
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1755 you can ignore the prompt value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1756
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1757 If the function reads input itself, it can have the effect of altering
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1758 the event that follows. For example, here's how to define @kbd{C-c h}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1759 to turn the character that follows into a Hyper character:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1760
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1761 @example
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
1762 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1763 (defun hyperify (prompt)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1764 (let ((e (read-event)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1765 (vector (if (numberp e)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1766 (logior (lsh 1 24) e)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1767 (if (memq 'hyper (event-modifiers e))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1768 e
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1769 (add-event-modifier "H-" e))))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1770
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1771 (defun add-event-modifier (string e)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1772 (let ((symbol (if (symbolp e) e (car e))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1773 (setq symbol (intern (concat string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1774 (symbol-name symbol))))
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
1775 @end group
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
1776 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1777 (if (symbolp e)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1778 symbol
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1779 (cons symbol (cdr e)))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1780
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1781 (define-key function-key-map "\C-ch" 'hyperify)
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
1782 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1783 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1784
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1785 Finally, if you have enabled keyboard character set decoding using
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1786 @code{set-keyboard-coding-system}, decoding is done after the
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1787 translations listed above. @xref{Terminal I/O Encoding}. In future
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1788 Emacs versions, character set decoding may be done before the other
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1789 translations.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1790
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1791 @node Recording Input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1792 @subsection Recording Input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1793
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1794 @defun recent-keys
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1795 This function returns a vector containing the last 100 input events from
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1796 the keyboard or mouse. All input events are included, whether or not
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1797 they were used as parts of key sequences. Thus, you always get the last
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1798 100 input events, not counting events generated by keyboard macros.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1799 (These are excluded because they are less interesting for debugging; it
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
1800 should be enough to see the events that invoked the macros.)
39202
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1801
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1802 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39202
diff changeset
1803 causes this function to return an empty vector immediately afterward.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1804 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1805
26242
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1806 @deffn Command open-dribble-file filename
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1807 @cindex dribble file
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1808 This function opens a @dfn{dribble file} named @var{filename}. When a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1809 dribble file is open, each input event from the keyboard or mouse (but
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1810 not those from keyboard macros) is written in that file. A
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1811 non-character event is expressed using its printed representation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1812 surrounded by @samp{<@dots{}>}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1813
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1814 You close the dribble file by calling this function with an argument
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1815 of @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1816
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1817 This function is normally used to record the input necessary to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1818 trigger an Emacs bug, for the sake of a bug report.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1819
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1820 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1821 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1822 (open-dribble-file "~/dribble")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1823 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1824 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1825 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1826 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1827
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1828 See also the @code{open-termscript} function (@pxref{Terminal Output}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1829
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1830 @node Terminal Output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1831 @section Terminal Output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1832 @cindex terminal output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1833
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
1834 The terminal output functions send output to a text terminal, or keep
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1835 track of output sent to the terminal. The variable @code{baud-rate}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1836 tells you what Emacs thinks is the output speed of the terminal.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1837
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1838 @defvar baud-rate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1839 This variable's value is the output speed of the terminal, as far as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1840 Emacs knows. Setting this variable does not change the speed of actual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1841 data transmission, but the value is used for calculations such as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1842 padding. It also affects decisions about whether to scroll part of the
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
1843 screen or repaint---even when using a window system. (We designed it
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1844 this way despite the fact that a window system has no true ``output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1845 speed'', to give you a way to tune these decisions.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1846
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1847 The value is measured in baud.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1848 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1849
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1850 If you are running across a network, and different parts of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1851 network work at different baud rates, the value returned by Emacs may be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1852 different from the value used by your local terminal. Some network
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1853 protocols communicate the local terminal speed to the remote machine, so
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1854 that Emacs and other programs can get the proper value, but others do
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1855 not. If Emacs has the wrong value, it makes decisions that are less
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1856 than optimal. To fix the problem, set @code{baud-rate}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1857
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1858 @defun baud-rate
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1859 This obsolete function returns the value of the variable
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1860 @code{baud-rate}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1861 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1862
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1863 @defun send-string-to-terminal string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1864 This function sends @var{string} to the terminal without alteration.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1865 Control characters in @var{string} have terminal-dependent effects.
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
1866 This function operates only on text terminals.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1867
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1868 One use of this function is to define function keys on terminals that
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1869 have downloadable function key definitions. For example, this is how (on
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1870 certain terminals) to define function key 4 to move forward four
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1871 characters (by transmitting the characters @kbd{C-u C-f} to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1872 computer):
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1873
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1874 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1875 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1876 (send-string-to-terminal "\eF4\^U\^F")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1877 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1878 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1879 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1880 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1881
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1882 @deffn Command open-termscript filename
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1883 @cindex termscript file
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1884 This function is used to open a @dfn{termscript file} that will record
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1885 all the characters sent by Emacs to the terminal. It returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1886 @code{nil}. Termscript files are useful for investigating problems
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1887 where Emacs garbles the screen, problems that are due to incorrect
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1888 Termcap entries or to undesirable settings of terminal options more
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1889 often than to actual Emacs bugs. Once you are certain which characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1890 were actually output, you can determine reliably whether they correspond
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1891 to the Termcap specifications in use.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1892
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1893 You close the termscript file by calling this function with an
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1894 argument of @code{nil}.
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1895
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
1896 See also @code{open-dribble-file} in @ref{Recording Input}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1897
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1898 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1899 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1900 (open-termscript "../junk/termscript")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1901 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1902 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1903 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1904 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1905
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1906 @node Sound Output
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1907 @section Sound Output
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1908 @cindex sound
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1909
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1910 To play sound using Emacs, use the function @code{play-sound}. Only
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1911 certain systems are supported; if you call @code{play-sound} on a system
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1912 which cannot really do the job, it gives an error. Emacs version 20 and
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1913 earlier did not support sound at all.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1914
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1915 The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1916 or Sun Audio format (@samp{.au}).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1917
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1918 @tindex play-sound
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1919 @defun play-sound sound
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1920 This function plays a specified sound. The argument, @var{sound}, has
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1921 the form @code{(sound @var{properties}...)}, where the @var{properties}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1922 consist of alternating keywords (particular symbols recognized
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1923 specially) and values corresponding to them.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1924
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1925 Here is a table of the keywords that are currently meaningful in
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1926 @var{sound}, and their meanings:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1927
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1928 @table @code
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1929 @item :file @var{file}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1930 This specifies the file containing the sound to play.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1931 If the file name is not absolute, it is expanded against
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1932 the directory @code{data-directory}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1933
27259
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
1934 @item :data @var{data}
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
1935 This specifies the sound to play without need to refer to a file. The
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
1936 value, @var{data}, should be a string containing the same bytes as a
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
1937 sound file. We recommend using a unibyte string.
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
1938
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1939 @item :volume @var{volume}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1940 This specifies how loud to play the sound. It should be a number in the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1941 range of 0 to 1. The default is to use whatever volume has been
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1942 specified before.
33951
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1943
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1944 @item :device @var{device}
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1945 This specifies the system device on which to play the sound, as a
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1946 string. The default device is system-dependent.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1947 @end table
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1948
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1949 Before actually playing the sound, @code{play-sound}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1950 calls the functions in the list @code{play-sound-functions}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1951 Each function is called with one argument, @var{sound}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1952 @end defun
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1953
33951
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1954 @defun play-sound-file file &optional volume device
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1955 @tindex play-sound-file
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1956 This function is an alternative interface to playing a sound @var{file}
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1957 specifying an optional @var{volume} and @var{device}.
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1958 @end defun
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1959
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1960 @tindex play-sound-functions
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1961 @defvar play-sound-functions
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1962 A list of functions to be called before playing a sound. Each function
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1963 is called with one argument, a property list that describes the sound.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1964 @end defvar
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1965
46228
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
1966 @node X11 Keysyms
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
1967 @section Operating on X11 Keysyms
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1968
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1969 To define system-specific X11 keysyms, set the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1970 @code{system-key-alist}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1971
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1972 @defvar system-key-alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1973 This variable's value should be an alist with one element for each
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1974 system-specific keysym. Each element has the form @code{(@var{code}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1975 . @var{symbol})}, where @var{code} is the numeric keysym code (not
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
1976 including the ``vendor specific'' bit,
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1977 @ifnottex
24934
f5e3b4ecd255 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24848
diff changeset
1978 -2**28),
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1979 @end ifnottex
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
1980 @tex
24934
f5e3b4ecd255 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24848
diff changeset
1981 $-2^{28}$),
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1982 @end tex
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1983 and @var{symbol} is the name for the function key.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1984
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1985 For example @code{(168 . mute-acute)} defines a system-specific key (used
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1986 by HP X servers) whose numeric code is
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1987 @ifnottex
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1988 -2**28
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1989 @end ifnottex
49549
99be3a1e2589 Cygwin support patch.
Juanma Barranquero <lekktu@gmail.com>
parents: 47870
diff changeset
1990 @tex
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1991 $-2^{28}$
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1992 @end tex
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1993 + 168.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1994
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1995 It is not crucial to exclude from the alist the keysyms of other X
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1996 servers; those do no harm, as long as they don't conflict with the ones
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1997 used by the X server actually in use.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1998
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1999 The variable is always local to the current terminal, and cannot be
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
2000 buffer-local. @xref{Multiple Displays}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2001 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2002
46228
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2003 You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables:
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2004
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2005 @defvar x-alt-keysym
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2006 @defvarx x-meta-keysym
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2007 @defvarx x-hyper-keysym
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2008 @defvarx x-super-keysym
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2009 The name of the keysym that should stand for the Alt modifier
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2010 (respectively, for Meta, Hyper, and Super). For example, here is
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2011 how to swap the Meta and Alt modifiers within Emacs:
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2012 @lisp
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2013 (setq x-alt-keysym 'meta)
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2014 (setq x-meta-keysym 'alt)
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2015 @end lisp
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2016 @end defvar
b77938fad6d0 Add x-*-keysym.
Richard M. Stallman <rms@gnu.org>
parents: 43829
diff changeset
2017
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2018 @node Batch Mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2019 @section Batch Mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2020 @cindex batch mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2021 @cindex noninteractive use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2022
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
2023 The command-line option @samp{-batch} causes Emacs to run
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2024 noninteractively. In this mode, Emacs does not read commands from the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2025 terminal, it does not alter the terminal modes, and it does not expect
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2026 to be outputting to an erasable screen. The idea is that you specify
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2027 Lisp programs to run; when they are finished, Emacs should exit. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2028 way to specify the programs to run is with @samp{-l @var{file}}, which
60269
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
2029 loads the library named @var{file}, or @samp{-f @var{function}}, which
cf30c1463800 (Startup Summary): Correct the options; add missing ones.
Richard M. Stallman <rms@gnu.org>
parents: 59390
diff changeset
2030 calls @var{function} with no arguments, or @samp{--eval @var{form}}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2031
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2032 Any Lisp program output that would normally go to the echo area,
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
2033 either using @code{message}, or using @code{prin1}, etc., with @code{t}
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2034 as the stream, goes instead to Emacs's standard error descriptor when
36873
705d5129bb72 batch read from minibuffer
Dave Love <fx@gnu.org>
parents: 35476
diff changeset
2035 in batch mode. Similarly, input that would normally come from the
705d5129bb72 batch read from minibuffer
Dave Love <fx@gnu.org>
parents: 35476
diff changeset
2036 minibuffer is read from the standard input descriptor.
705d5129bb72 batch read from minibuffer
Dave Love <fx@gnu.org>
parents: 35476
diff changeset
2037 Thus, Emacs behaves much like a noninteractive
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2038 application program. (The echo area output that Emacs itself normally
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2039 generates, such as command echoing, is suppressed entirely.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2040
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2041 @defvar noninteractive
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2042 This variable is non-@code{nil} when Emacs is running in batch mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2043 @end defvar
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2044
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2045 @node Session Management
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2046 @section Session Management
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2047 @cindex session manager
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2048
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2049 Emacs supports the X Session Management Protocol for suspension and
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2050 restart of applications. In the X Window System, a program called the
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2051 @dfn{session manager} has the responsibility to keep track of the
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2052 applications that are running. During shutdown, the session manager
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2053 asks applications to save their state, and delays the actual shutdown
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2054 until they respond. An application can also cancel the shutdown.
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2055
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2056 When the session manager restarts a suspended session, it directs
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2057 these applications to individually reload their saved state. It does
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2058 this by specifying a special command-line argument that says what
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2059 saved session to restore. For Emacs, this argument is @samp{--smid
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2060 @var{session}}.
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2061
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2062 @defvar emacs-save-session-functions
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2063 @tindex emacs-save-session-functions
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2064 Emacs supports saving state by using a hook called
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2065 @code{emacs-save-session-functions}. Each function in this hook is
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2066 called when the session manager tells Emacs that the window system is
56369
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
2067 shutting down. The functions are called with no arguments and with the
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
2068 current buffer set to a temporary buffer. Each function can use
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
2069 @code{insert} to add Lisp code to this buffer. At the end, Emacs
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
2070 saves the buffer in a file that a subsequent Emacs invocation will
6578797626ea Various small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 56353
diff changeset
2071 load in order to restart the saved session.
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2072
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2073 If a function in @code{emacs-save-session-functions} returns
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2074 non-@code{nil}, Emacs tells the session manager to cancel the
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2075 shutdown.
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2076 @end defvar
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2077
56353
1468ded18da0 Update copyright.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 54037
diff changeset
2078 Here is an example that just inserts some text into @samp{*scratch*} when
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2079 Emacs is restarted by the session manager.
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2080
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2081 @example
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2082 @group
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2083 (add-hook 'emacs-save-session-functions 'save-yourself-test)
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2084 @end group
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2085
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2086 @group
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2087 (defun save-yourself-test ()
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2088 (insert "(save-excursion
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2089 (switch-to-buffer \"*scratch*\")
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2090 (insert \"I am restored\"))")
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2091 nil)
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2092 @end group
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2093 @end example
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52189
diff changeset
2094
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52189
diff changeset
2095 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52189
diff changeset
2096 arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52189
diff changeset
2097 @end ignore