annotate lispref/os.texi @ 45152:0e9984418269

(make_drawing_gcs): The scaling factor passed to `x_alloc_lighter_color_for_widget' is a float, not an int, and it's a multiplicative factor, so the name `delta' is inaccurate. Always base disabled foreground on the normal foreground. Don't use the temporary variable `temp'.
author Pavel Janík <Pavel@Janik.cz>
date Tue, 07 May 2002 05:22:29 +0000
parents 7e937c00ff00
children b77938fad6d0
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.
27189
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
4 @c 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
26211
df0efa93750b Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
7 @node System Interface, Antinews, Calendar, 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.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
24 * Time Conversion:: Converting a time from numeric form to a string, or
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
25 to calendrical data (or vice versa).
43037
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
26 * Time Calculations:: Adding, subtracting, comparing times, etc.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 * Timers:: Setting a timer to call a function at a certain time.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 * Terminal Input:: Recording terminal input for debugging.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 * Terminal Output:: Recording terminal output for debugging.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
30 * Sound Output:: Playing sounds on the computer's speaker.
35476
26912db550c3 Change "X windows" instances.
Dave Love <fx@gnu.org>
parents: 33951
diff changeset
31 * Special Keysyms:: Defining system-specific key symbols for X.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 * Flow Control:: How to turn output flow control on or off.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 * 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
34 * Session Management:: Saving and restoring state with X Session Management.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 @node Starting Up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 @section Starting Up Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 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
41 can customize these actions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 @menu
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
44 * Startup Summary:: Sequence of actions Emacs performs at startup.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 * Init File:: Details on reading the init file (@file{.emacs}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 * 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
47 * Command-Line Arguments:: How command-line arguments are processed,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 and how you can customize them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
51 @node Startup Summary
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
52 @subsection Summary: Sequence of Actions at Startup
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 @cindex initialization
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
54 @cindex startup of Emacs
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 @cindex @file{startup.el}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 The order of operations performed (in @file{startup.el}) by Emacs when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 it is started up is as follows:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 @enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 @item
28603
cb9db16dba12 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27765
diff changeset
62 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
63 @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
64 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
65 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
66 generated automatically by Emacs installation.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
67
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
68 @item
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
69 It sets the language environment and the terminal coding system,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
70 if requested by environment variables such as @code{LANG}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
71
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
72 @item
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 It loads the initialization library for the window system, if you are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 using a window system. This library's name is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 @file{term/@var{windowsystem}-win.el}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
78 It processes the initial options. (Some of them are handled
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
79 even earlier than this.)
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
80
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
81 @item
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
82 It initializes the window frame and faces, if appropriate.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 It runs the normal hook @code{before-init-hook}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 It loads the library @file{site-start}, unless the option
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 @samp{-no-site-file} was specified. The library's file name is usually
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 @file{site-start.el}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @cindex @file{site-start.el}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 @item
26242
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
94 It loads your init file (usually @file{~/.emacs}), unless @samp{-q},
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
95 @samp{-no-init-file}, or @samp{-batch} was specified on the command line.
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
96 The @samp{-u} option can specify another user whose home directory
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
97 should be used instead of @file{~}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 @item
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
100 It loads the library @file{default}, unless @code{inhibit-default-init}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 is non-@code{nil}. (This is not done in @samp{-batch} mode or if
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
102 @samp{-q} was specified on the command line.) The library's file name
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
103 is usually @file{default.el}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @cindex @file{default.el}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 It runs the normal hook @code{after-init-hook}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 It sets the major mode according to @code{initial-major-mode}, provided
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 the buffer @samp{*scratch*} is still current and still in Fundamental
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 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
116 mode or using a window system.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 It displays the initial echo area message, unless you have suppressed
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 that with @code{inhibit-startup-echo-area-message}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
123 It processes the action arguments from the command line.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 @item
27353
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
126 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
127
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 It calls @code{frame-notice-user-settings}, which modifies the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 parameters of the selected frame according to whatever the init files
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 specify.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 It runs @code{window-setup-hook}. @xref{Window Systems}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 @item
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
137 It displays copyleft, nonwarranty, and basic use information, provided
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
138 there were no remaining command-line arguments (a few steps above),
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
139 the value of @code{inhibit-startup-message} is @code{nil}, and the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
140 buffer is still empty.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 @end enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 @defopt inhibit-startup-message
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 This variable inhibits the initial startup messages (the nonwarranty,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 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
146
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 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
148 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
149 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
150 more than one user, because that would prevent new users from receiving
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 the information they are supposed to see.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 @defopt inhibit-startup-echo-area-message
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 This variable controls the display of the startup echo area message.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 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
157 form to your init file:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 (setq inhibit-startup-echo-area-message
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 "@var{your-login-name}")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
164 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
165 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
166 constant. Other methods of setting
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
167 @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
168 inhibit the startup message.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 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
171 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
172 for someone else.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @node Init File
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
176 @subsection The Init File, @file{.emacs}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 @cindex init file
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 @cindex @file{.emacs}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
180 When you start Emacs, it normally attempts to load your @dfn{init
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
181 file}, a file in your home directory. Its normal name is @file{.emacs},
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
182 but you can alternatively call it @file{.emacs.el}, which enables you to
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
183 byte-compile it (@pxref{Byte Compilation}); then the actual file loaded
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
184 will be @file{.emacs.elc}.
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
185
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
186 The command-line switches @samp{-q} and @samp{-u} control whether and
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
187 where to find the init file; @samp{-q} says not to load an init file,
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
188 and @samp{-u @var{user}} says to load @var{user}'s init file instead of
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
189 yours. @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
190 neither option is specified, Emacs uses the @code{LOGNAME} environment
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
191 variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
192 systems) variable, to find your home directory and thus your init file;
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
193 this way, even if you have su'd, Emacs still loads your own init file.
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
194 If those environment variables are absent, though, Emacs uses your
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
195 user-id to find your home directory.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 @cindex default init file
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 A site may have a @dfn{default init file}, which is the library named
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 @file{default.el}. Emacs finds the @file{default.el} file through the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 standard search path for libraries (@pxref{How Programs Do Loading}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 The Emacs distribution does not come with this file; sites may provide
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 one for local customizations. If the default init file exists, it is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 loaded whenever you start Emacs, except in batch mode or if @samp{-q} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 specified. But your own personal init file, if any, is loaded first; if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 it sets @code{inhibit-default-init} to a non-@code{nil} value, then
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 Emacs does not subsequently load the @file{default.el} file.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 Another file for site-customization is @file{site-start.el}. Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 loads this @emph{before} the user's init file. You can inhibit the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 loading of this file with the option @samp{-no-site-file}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
212 @defvar site-run-file
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
213 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
214 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
215 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
216 Emacs.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
217 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
218
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
219 @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 examples of how to make various commonly desired customizations in your
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 @file{.emacs} file.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 @defopt inhibit-default-init
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 This variable prevents Emacs from loading the default initialization
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 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
226 then the default library is not loaded. The default value is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 @end defopt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 @defvar before-init-hook
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
231 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
232 (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
233 (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
234 @end defvar
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
235
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
236 @defvar after-init-hook
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
237 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
238 (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
239 before loading the terminal-specific library and processing the
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
240 command-line arguments.
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
241 @end defvar
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
242
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
243 @defvar emacs-startup-hook
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
244 @tindex emacs-startup-hook
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
245 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
246 arguments, just before @code{term-setup-hook}.
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
247 @end defvar
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
248
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
249 @defvar user-init-file
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
250 @tindex user-init-file
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
251 This variable holds the file name of the user's init file. If the
611b3854d888 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
252 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
253 the value refers to the corresponding source file.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 @node Terminal-Specific
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 @subsection Terminal-Specific Initialization
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 @cindex terminal-specific initialization
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 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
261 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
262 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
263 terminal type (specified by the environment variable @code{TERM}).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
264 Normally, @code{term-file-prefix} has the value
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
265 @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
266 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
267 trying the @samp{.elc} and @samp{.el} suffixes.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 The usual function of a terminal-specific library is to enable special
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 keys to send sequences that Emacs can recognize. It may also need to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 set or add to @code{function-key-map} if the Termcap entry does not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 specify all the terminal's function keys. @xref{Terminal Input}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 @cindex Termcap
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 When the name of the terminal type contains a hyphen, only the part of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 the name before the first hyphen is significant in choosing the library
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 the @file{term/aaa} library. If necessary, the library can evaluate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 @code{(getenv "TERM")} to find the full name of the terminal
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 type.@refill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
282 Your init file can prevent the loading of the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 terminal-specific library by setting the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 @code{term-file-prefix} to @code{nil}. This feature is useful when
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 experimenting with your own peculiar customizations.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 You can also arrange to override some of the actions of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 terminal-specific library by setting the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 @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
290 @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
291 your init file and any terminal-specific libraries. You can
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 use this variable to define initializations for terminals that do not
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 have their own libraries. @xref{Hooks}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 @defvar term-file-prefix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 @cindex @code{TERM} environment variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 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
298 a terminal-specific initialization file as follows:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 (load (concat term-file-prefix (getenv "TERM")))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 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
306 init file if you do not wish to load the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 terminal-initialization file. To do this, put the following in
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
308 your init file: @code{(setq term-file-prefix nil)}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
309
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
310 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
311 uses @samp{internal} as the terminal type.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 @defvar term-setup-hook
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
315 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
316 init file, the default initialization file (if any) and the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 terminal-specific Lisp file.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 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
320 terminal-specific file.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 See @code{window-setup-hook} in @ref{Window Systems}, for a related
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 feature.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
326 @node Command-Line Arguments
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
327 @subsection Command-Line Arguments
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
328 @cindex command-line arguments
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
330 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
331 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
332 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
333 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
334 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
335 encourage you to kill and restart Emacs unnecessarily often. These
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 options exist for two reasons: to be compatible with other editors (for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 invocation by other programs) and to enable shell scripts to run
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 specific Lisp programs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
340 This section describes how Emacs processes command-line arguments,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 and how you can customize them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @ignore
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 (Note that some other editors require you to start afresh each time
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 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
346 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
347 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
348 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
349 a different file, you visit it with the existing Emacs, which eventually
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 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
351 kill the Emacs until you are about to log out.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 @end ignore
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 @defun command-line
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
355 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
356 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
357 startup messages.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 @defvar command-line-processed
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 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
362 processed.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 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
365 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
366 to process its new command-line arguments.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 @defvar command-switch-alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 @cindex switches on command line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 @cindex options on command line
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
372 @cindex command-line options
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 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
374 options and associated handler functions. This variable exists so you
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 can add elements to it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
377 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
378 has the form:
6558
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 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 -@var{option}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 The elements of the @code{command-switch-alist} look like this:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 (@var{option} . @var{handler-function})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
390 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
391 option (not including the initial hyphen). The @var{handler-function}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
392 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
393 sole argument.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 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
396 argument. In these cases, the @var{handler-function} can find all the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 remaining command-line arguments in the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 @code{command-line-args-left}. (The entire list of command-line
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 arguments is in @code{command-line-args}.)
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 command-line arguments are parsed by the @code{command-line-1}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 function in the @file{startup.el} file. See also @ref{Command
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 Manual}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 @defvar command-line-args
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
408 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
409 to Emacs.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 @defvar command-line-functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 This variable's value is a list of functions for handling an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 unrecognized command-line argument. Each time the next argument to be
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 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
416 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
417 value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 These functions are called with no arguments. They can access the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 command-line argument under consideration through the variable
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
421 @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
422 arguments (not including the current one) are in the variable
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
423 @code{command-line-args-left}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 When a function recognizes and processes the argument in @code{argi}, it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 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
427 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
428 can indicate that by deleting them from @code{command-line-args-left}.
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 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
431 as a file name to visit.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 @node Getting Out
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 @section Getting Out of Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 @cindex exiting Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 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
439 which exits permanently, or you can suspend it, which permits you to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 reenter the Emacs process later. As a practical matter, you seldom kill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 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
442 common.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 * Killing Emacs:: Exiting Emacs irreversibly.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 * Suspending Emacs:: Exiting Emacs reversibly.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @end menu
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 @node Killing Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @comment node-name, next, previous, up
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @subsection Killing Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 @cindex killing Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 Killing Emacs means ending the execution of the Emacs process. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 parent process normally resumes control. The low-level primitive for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 killing Emacs is @code{kill-emacs}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @defun kill-emacs &optional exit-data
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 This function exits the Emacs process and kills it.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 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
462 of the Emacs process. (This is useful primarily in batch operation; see
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 @ref{Batch Mode}.)
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 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
466 terminal input buffer so that the shell (or whatever program next reads
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 input) can read them.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 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
471 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
472 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
473 confirmation before actually terminating if you have buffers that need
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
474 saving or subprocesses that are running. This is done in the function
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 @code{save-buffers-kill-emacs}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 @defvar kill-emacs-query-functions
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 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
479 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
480 order of appearance, with no arguments. These functions can ask for
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 additional confirmation from the user. If any of them returns
20103
7867bb9ff46a Elements of kill-emacs-query-functions return nil, not non-nil,
Karl Heuer <kwzh@gnu.org>
parents: 15778
diff changeset
482 @code{nil}, Emacs is not killed.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 @defvar kill-emacs-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 finished with all file saving and confirmation, it runs the functions in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 this hook.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @node Suspending Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @subsection Suspending Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 @cindex suspending Emacs
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 control to its superior process, which is usually the shell. This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 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
498 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
499 resume Emacs, use the appropriate command in the parent shell---most
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 likely @code{fg}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 Some operating systems do not support suspension of jobs; on these
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 systems, ``suspension'' actually creates a new shell temporarily as a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 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
505
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
506 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
507 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
508 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
509 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
510 a window system (X or MS Windows).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 @defun suspend-emacs string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 This function stops Emacs and returns control to the superior process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 If and when the superior process resumes Emacs, @code{suspend-emacs}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 returns @code{nil} to its caller in Lisp.
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 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
518 as terminal input by Emacs's superior shell. The characters in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 @var{string} are not echoed by the superior shell; only the results
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 appear.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 Before suspending, @code{suspend-emacs} runs the normal hook
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
523 @code{suspend-hook}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
525 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
526 @code{suspend-resume-hook}. @xref{Hooks}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 The next redisplay after resumption will redraw the entire screen,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 (@pxref{Refresh Screen}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 In the following example, note that @samp{pwd} is not echoed after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 Emacs is suspended. But it is read and executed by the shell.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 (suspend-emacs)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 (add-hook 'suspend-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 (function (lambda ()
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 (or (y-or-n-p
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 "Really suspend? ")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 (error "Suspend cancelled")))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @result{} (lambda nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 (or (y-or-n-p "Really suspend? ")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 (error "Suspend cancelled")))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 (add-hook 'suspend-resume-hook
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 (function (lambda () (message "Resumed!"))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 @result{} (lambda nil (message "Resumed!"))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 (suspend-emacs "pwd")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 ---------- Buffer: Minibuffer ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 Really suspend? @kbd{y}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 ---------- Buffer: Minibuffer ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 ---------- Parent Shell ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 lewis@@slug[23] % /user/lewis/manual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 lewis@@slug[24] % fg
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 ---------- Echo Area ----------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 Resumed!
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @defvar suspend-hook
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
580 This variable is a normal hook that Emacs runs before suspending.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 @defvar suspend-resume-hook
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
584 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
585 after a suspension.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 @end defvar
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 @node System Environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 @section Operating System Environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 @cindex operating system environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 Emacs provides access to variables in the operating system environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 through various functions. These variables include the name of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 system, the user's @sc{uid}, and so on.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
596 @defvar system-configuration
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
597 This variable holds the GNU configuration name for the hardware/software
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
598 configuration of your system, as a string. The convenient way to test
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
599 parts of this string is with @code{string-match}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
600 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
601
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 @defvar system-type
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
603 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
604 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
605
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 @table @code
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
607 @item alpha-vms
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
608 VMS on the Alpha.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
609
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 @item aix-v3
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 AIX.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 @item berkeley-unix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 Berkeley BSD.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
616 @item dgux
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
617 Data General DGUX operating system.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
618
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
619 @item gnu
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
620 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
621
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
622 @item gnu/linux
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
623 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
624 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
625 actually Linux is just the kernel, not the whole system.)
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
626
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @item hpux
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
628 Hewlett-Packard HPUX operating system.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 @item irix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 Silicon Graphics Irix system.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
633 @item ms-dos
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
634 Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
635 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
636 MS-Windows.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
637
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
638 @item next-mach
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
639 NeXT Mach-based system.
7277
6a2af30d33fe *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
640
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 @item rtu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642 Masscomp RTU, UCB universe.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 @item unisoft-unix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 UniSoft UniPlus.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 @item usg-unix-v
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 AT&T System V.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 @item vax-vms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 VAX VMS.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
653 @item windows-nt
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
654 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
655 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
656
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 @item xenix
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 SCO Xenix 386.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 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
662 is absolutely necessary! In fact, we hope to eliminate some of these
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663 alternatives in the future. We recommend using
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664 @code{system-configuration} to distinguish between different operating
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 systems.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 @defun system-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 This function returns the name of the machine you are running on.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 (system-name)
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
672 @result{} "www.gnu.org"
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
676 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
677 fact, the function returns whatever value the variable
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
678 @code{system-name} currently holds. Thus, you can set the variable
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
679 @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
680 system. The variable is also useful for constructing frame titles
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
681 (@pxref{Frame Titles}).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
682
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
683 @defvar mail-host-address
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
684 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
685 @code{system-name} for purposes of generating email addresses. For
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
686 example, it is used when constructing the default value of
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
687 @code{user-mail-address}. @xref{User Identification}. (Since this is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
688 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
689 Emacs was dumped. @xref{Building Emacs}.)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
690 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
691
32839
4ab12a7fc269 getenv is a command
Dave Love <fx@gnu.org>
parents: 28635
diff changeset
692 @deffn Command getenv var
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 @cindex environment variable access
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 This function returns the value of the environment variable @var{var},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 as a string. Within Emacs, the environment variable values are kept in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696 the Lisp variable @code{process-environment}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700 (getenv "USER")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 @result{} "lewis"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 lewis@@slug[10] % printenv
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 USER=lewis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 TERM=ibmapa16
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 SHELL=/bin/csh
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 HOME=/user/lewis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714 @end example
32924
b491fc65a56e *** empty log message ***
Dave Love <fx@gnu.org>
parents: 32839
diff changeset
715 @end deffn
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 @deffn Command setenv variable value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 This command sets the value of the environment variable named
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 @var{variable} to @var{value}. Both arguments should be strings. This
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 function works by modifying @code{process-environment}; binding that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 variable with @code{let} is also reasonable practice.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 @defvar process-environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 This variable is a list of strings, each describing one environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 variable. The functions @code{getenv} and @code{setenv} work by means
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 of this variable.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 process-environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/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 smallexample
40311
a3a9223b152f Clarify what happens with duplicates in process-environment.
Richard M. Stallman <rms@gnu.org>
parents: 39221
diff changeset
743
a3a9223b152f Clarify what happens with duplicates in process-environment.
Richard M. Stallman <rms@gnu.org>
parents: 39221
diff changeset
744 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
745 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
746 specifies the variable, and the other ``duplicates'' are ignored.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
749 @defvar path-separator
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
750 This variable holds a string which says which character separates
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
751 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
752 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
753 and MS-Windows.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
754 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
755
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
756 @defun parse-colon-path path
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
757 @tindex parse-colon-path
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
758 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
759 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
760 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
761 ``use the current directory.'' Although the function's name says
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
762 ``colon,'' it actually uses the value of @code{path-separator}.
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
763
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
764 @example
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
765 (parse-colon-path ":/foo:/bar")
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
766 @result{} (nil "/foo/" "/bar/")
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
767 @end example
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
768 @end defun
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28603
diff changeset
769
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
770 @defvar invocation-name
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
771 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
772 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
773 @end defvar
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
774
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
775 @defvar invocation-directory
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
776 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
777 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
778 @end defvar
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
779
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
780 @defvar installation-directory
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
781 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
782 @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
783 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
784 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
785 containing the Emacs executable.
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
786 @end defvar
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
787
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
788 @defun load-average &optional use-float
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
789 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
790 averages, in a list.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
791
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
792 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
793 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
794 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
795 as floating point numbers and without multiplying by 100.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 (load-average)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 @result{} (169 48 36)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 @end group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
802 @group
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
803 (load-average t)
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
804 @result{} (1.69 0.48 0.36)
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
805 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 lewis@@rocky[5] % uptime
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 11:55am up 1 day, 19:37, 3 users,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 load average: 1.69, 0.48, 0.36
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 @defun emacs-pid
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 This function returns the process @sc{id} of the Emacs process.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
819 @defvar tty-erase-char
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
820 This variable holds the erase character that was selected
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
821 in the system's terminal driver, before Emacs was started.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
822 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
823
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 @defun setprv privilege-name &optional setp getprv
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 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
826 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
827 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
828 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
829 @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
830 otherwise.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 does not change the privilege, but returns @code{t} or @code{nil}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 indicating whether the privilege is currently enabled.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 @node User Identification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 @section User Identification
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
840 @defvar init-file-user
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
841 This variable says which user's init files should be used by Emacs---or
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
842 @code{nil} if none. The value reflects command-line options such as
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
843 @samp{-q} or @samp{-u @var{user}}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
844
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
845 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
846 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
847 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
848 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
849 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
850 files or user profile.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
851 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
852
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
853 @defvar user-mail-address
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
854 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
855 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
856 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
857 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
858 want to use the default value.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
859 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
860
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
861 @defun user-login-name &optional uid
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
862 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
863 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
864 is set, that value is used. Otherwise, if the environment variable
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
865 @code{USER} is set, that value is used. Otherwise, the value is based
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
866 on the effective @sc{uid}, not the real @sc{uid}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
867
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
868 If you specify @var{uid}, the value is the user name that corresponds
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
869 to @var{uid} (which should be an integer).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 (user-login-name)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874 @result{} "lewis"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
879 @defun user-real-login-name
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
880 This function returns the user name corresponding to Emacs's real
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
881 @sc{uid}. This ignores the effective @sc{uid} and ignores the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
882 environment variables @code{LOGNAME} and @code{USER}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
885 @defun user-full-name &optional uid
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
886 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
887 of the environment variable @code{NAME}, if that is set.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
889 @c "Bil" is the correct spelling.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 (user-full-name)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893 @result{} "Bil Lewis"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895 @end example
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
896
24848
ca34063731fc *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 23147
diff changeset
897 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
898 provided @code{NAME} is not set), the value is @code{"unknown"}.
ca34063731fc *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 23147
diff changeset
899
ca34063731fc *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 23147
diff changeset
900 If @var{uid} is non-@code{nil}, then it should be an integer (a user-id)
ca34063731fc *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 23147
diff changeset
901 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
902 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
903 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
904 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
906 @vindex user-full-name
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
907 @vindex user-real-login-name
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
908 @vindex user-login-name
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
909 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
910 @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
911 return the same values that the variables hold. These variables allow
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
912 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
913 variables are also useful for constructing frame titles (@pxref{Frame
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
914 Titles}).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
915
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 @defun user-real-uid
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 This function returns the real @sc{uid} of the user.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
921 (user-real-uid)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
922 @result{} 19
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 @defun user-uid
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 This function returns the effective @sc{uid} of the user.
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 @node Time of Day
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932 @section Time of Day
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 This section explains how to determine the current time and the time
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 zone.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 @defun current-time-string &optional time-value
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
938 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
939 string. The format of the string is unvarying; the number of characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 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
941 @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
942 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
943 additional information may some day be added at the end.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 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
947 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
948 two elements are integers. Thus, you can use times obtained from
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
949 @code{current-time} (see below) and from @code{file-attributes}
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
950 (@pxref{File Attributes}).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954 (current-time-string)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955 @result{} "Wed Oct 14 22:21:05 1987"
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
958 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
959
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
960 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 @defun current-time
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
962 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
963 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 @var{high} and @var{low} combine to give the number of seconds since
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
965 0:00 January 1, 1970 (local time), which is
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
966 @ifnottex
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 @var{high} * 2**16 + @var{low}.
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
968 @end ifnottex
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 @tex
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
970 $high*2^{16}+low$.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971 @end tex
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973 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
974 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
975 the resolution of only one second).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 The first two elements can be compared with file time values such as you
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978 get with the function @code{file-attributes}. @xref{File Attributes}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 @defun current-time-zone &optional time-value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 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
984 in.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 The value has the form @code{(@var{offset} @var{name})}. Here
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 @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
988 (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
989 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
990 zone. Both elements change when daylight savings time begins or ends;
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991 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
992 adjustment, then the value is constant through time.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 If the operating system doesn't supply all the information necessary to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995 compute the value, both elements of the list are @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 The argument @var{time-value}, if given, specifies a time to analyze
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998 instead of the current time. The argument should be a cons cell
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 containing two integers, or a list whose first two elements are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 integers. Thus, you can use times obtained from @code{current-time}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1001 (see above) and from @code{file-attributes} (@pxref{File Attributes}).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1002 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1003
39202
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1004 @defun float-time &optional time-value
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1005 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
1006 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
1007 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
1008 should have the same form as for @code{current-time-string} (see
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1009 above), and it also accepts the output of @code{current-time} and
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1010 @code{file-attributes}.
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1011
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1012 @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
1013 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
1014 @end defun
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1015
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1016 @node Time Conversion
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1017 @section Time Conversion
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1018
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1019 These functions convert time values (lists of two or three integers)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1020 to strings or to calendrical information. There is also a function to
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1021 convert calendrical information to a time value. You can get time
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1022 values from the functions @code{current-time} (@pxref{Time of Day}) and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1023 @code{file-attributes} (@pxref{File Attributes}).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1024
15778
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1025 Many operating systems are limited to time values that contain 32 bits
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1026 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
1027 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
1028 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
1029 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
1030
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1031 Time conversion functions always use the Gregorian calendar, even for
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1032 dates before the Gregorian calendar was introduced. Year numbers count
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1033 the number of years since the year 1 B.C., and do not skip zero as
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1034 traditional Gregorian years do; for example, the year number @minus{}37
15778
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1035 represents the Gregorian year 38 B.C@.
c96cee4f8be8 Explain range of time values, and what negative year numbers mean.
Richard M. Stallman <rms@gnu.org>
parents: 15762
diff changeset
1036
43037
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1037 @defun date-to-time string
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1038 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
1039 corresponding time value.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1040 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1041
26242
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1042 @defun format-time-string format-string &optional time universal
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1043 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
1044 omitted) to a string according to @var{format-string}. The argument
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1045 @var{format-string} may contain @samp{%}-sequences which say to
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1046 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
1047 @samp{%}-sequences mean:
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1048
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1049 @table @samp
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1050 @item %a
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1051 This stands for the abbreviated name of the day of week.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1052 @item %A
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1053 This stands for the full name of the day of week.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1054 @item %b
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1055 This stands for the abbreviated name of the month.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1056 @item %B
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1057 This stands for the full name of the month.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1058 @item %c
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1059 This is a synonym for @samp{%x %X}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1060 @item %C
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1061 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
1062 is equivalent to @samp{%A, %B %e, %Y}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1063 @item %d
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1064 This stands for the day of month, zero-padded.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1065 @item %D
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1066 This is a synonym for @samp{%m/%d/%y}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1067 @item %e
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1068 This stands for the day of month, blank-padded.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1069 @item %h
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1070 This is a synonym for @samp{%b}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1071 @item %H
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1072 This stands for the hour (00-23).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1073 @item %I
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1074 This stands for the hour (01-12).
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1075 @item %j
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1076 This stands for the day of the year (001-366).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1077 @item %k
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1078 This stands for the hour (0-23), blank padded.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1079 @item %l
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1080 This stands for the hour (1-12), blank padded.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1081 @item %m
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1082 This stands for the month (01-12).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1083 @item %M
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1084 This stands for the minute (00-59).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1085 @item %n
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1086 This stands for a newline.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1087 @item %p
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1088 This stands for @samp{AM} or @samp{PM}, as appropriate.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1089 @item %r
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1090 This is a synonym for @samp{%I:%M:%S %p}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1091 @item %R
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1092 This is a synonym for @samp{%H:%M}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1093 @item %S
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1094 This stands for the seconds (00-59).
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1095 @item %t
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1096 This stands for a tab character.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1097 @item %T
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1098 This is a synonym for @samp{%H:%M:%S}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1099 @item %U
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1100 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
1101 start on Sunday.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1102 @item %w
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1103 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
1104 @item %W
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1105 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
1106 start on Monday.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1107 @item %x
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1108 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
1109 @samp{C}), it is equivalent to @samp{%D}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1110 @item %X
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1111 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
1112 @samp{C}), it is equivalent to @samp{%T}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1113 @item %y
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1114 This stands for the year without century (00-99).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1115 @item %Y
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1116 This stands for the year with century.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1117 @item %Z
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1118 This stands for the time zone abbreviation.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1119 @end table
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1120
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1121 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
1122 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
1123 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
1124 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
1125 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
1126
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1127 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
1128 @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
1129 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
1130 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
1131
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1132 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
1133 @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
1134 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
1135 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
1136 based on the Japanese Emperors' reigns. @samp{E} is allowed in
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1137 @samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1138 @samp{%EY}.
26242
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1139
26288
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1140 @samp{O} means to use the current locale's ``alternative''
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1141 representation of numbers, instead of the ordinary decimal digits. This
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26242
diff changeset
1142 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
1143
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1144 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
1145 Universal Time; @code{nil} means describe it using what Emacs believes
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1146 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
1147
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1148 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
1149 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
1150 its argument using the coding system specified by
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1151 @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
1152 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
1153 string using that same coding system.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1154 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1155
43037
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1156 @defun seconds-to-time seconds
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1157 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
1158 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
1159 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
1160 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1161
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1162 @defun decode-time time
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1163 This function converts a time value into calendrical information. The
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1164 return value is a list of nine elements, as follows:
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1165
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1166 @example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1167 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1168 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1169
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1170 Here is what the elements mean:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1171
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1172 @table @var
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1173 @item seconds
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1174 The number of seconds past the minute, as an integer between 0 and 59.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1175 @item minutes
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1176 The number of minutes past the hour, as an integer between 0 and 59.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1177 @item hour
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1178 The hour of the day, as an integer between 0 and 23.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1179 @item day
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1180 The day of the month, as an integer between 1 and 31.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1181 @item month
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1182 The month of the year, as an integer between 1 and 12.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1183 @item year
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1184 The year, an integer typically greater than 1900.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1185 @item dow
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1186 The day of week, as an integer between 0 and 6, where 0 stands for
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1187 Sunday.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1188 @item dst
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1189 @code{t} if daylight savings time is effect, otherwise @code{nil}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1190 @item zone
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1191 An integer indicating the time zone, as the number of seconds east of
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1192 Greenwich.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1193 @end table
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1194
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1195 @strong{Common Lisp Note:} Common Lisp has different meanings for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1196 @var{dow} and @var{zone}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1197 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1198
27765
277138d0f9f1 Remove @dots from encode-time header.
Dave Love <fx@gnu.org>
parents: 27370
diff changeset
1199 @defun encode-time seconds minutes hour day month year &optional zone
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1200 This function is the inverse of @code{decode-time}. It converts seven
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1201 items of calendrical data into a time value. For the meanings of the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1202 arguments, see the table above under @code{decode-time}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1203
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1204 Year numbers less than 100 are not treated specially. If you want them
27370
70846ee19545 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27353
diff changeset
1205 to stand for years above 1900, or years above 2000, you must alter them
70846ee19545 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27353
diff changeset
1206 yourself before you call @code{encode-time}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1207
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1208 The optional argument @var{zone} defaults to the current time zone and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1209 its daylight savings time rules. If specified, it can be either a list
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1210 (as you would get from @code{current-time-zone}), a string as in the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1211 @code{TZ} environment variable, or an integer (as you would get from
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1212 @code{decode-time}). The specified zone is used without any further
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1213 alteration for daylight savings time.
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1214
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1215 If you pass more than seven arguments to @code{encode-time}, the first
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1216 six are used as @var{seconds} through @var{year}, the last argument is
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1217 used as @var{zone}, and the arguments in between are ignored. This
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1218 feature makes it possible to use the elements of a list returned by
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1219 @code{decode-time} as the arguments to @code{encode-time}, like this:
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1220
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1221 @example
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1222 (apply 'encode-time (decode-time @dots{}))
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1223 @end example
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1224
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1225 You can perform simple date arithmetic by using out-of-range values for
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1226 the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1227 arguments; for example, day 0 means the day preceding the given month.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1228
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1229 The operating system puts limits on the range of possible time values;
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1230 if you try to encode a time that is out of range, an error results.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232
43037
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1233 @node Time Calculations
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1234 @section Time Calculations
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1235
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1236 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
1237 (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
1238
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1239 @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
1240 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
1241 @var{t2}.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1242 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1243
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1244 @defun time-subtract t1 t2
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1245 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
1246 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
1247 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1248
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1249 @defun time-add t1 t2
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1250 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
1251 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
1252 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
1253
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1254 @example
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1255 (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
1256 @end example
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1257 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1258
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1259 @defun time-to-days time
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1260 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
1261 1 and @var{time}.
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1262 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1263
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1264 @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
1265 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
1266 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1267
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1268 @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
1269 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
1270 @end defun
2f863ec2724c Document date-to-time and seconds-to-time.
Richard M. Stallman <rms@gnu.org>
parents: 40311
diff changeset
1271
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272 @node Timers
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1273 @section Timers for Delayed Execution
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1274 @cindex timer
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1275
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1276 You can set up a @dfn{timer} to call a function at a specified future time or
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1277 after a certain length of idleness.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1278
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1279 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
1280 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
1281 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
1282 @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
1283 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
1284 execution is very precise if Emacs is idle.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1285
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1286 @defun run-at-time time repeat function &rest args
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1287 This function arranges to call @var{function} with arguments @var{args}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1288 at time @var{time}. The argument @var{function} is a function to call
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1289 later, and @var{args} are the arguments to give it when it is called.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1290 The time @var{time} is specified as a string.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1291
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1292 Absolute times may be specified in a wide variety of formats; this
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1293 function tries to accept all the commonly used date formats. Valid
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1294 formats include these two,
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1295
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1296 @example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1297 @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
1298
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1299 @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
1300 @end example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1301
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1302 @noindent
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1303 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
1304 @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
1305 as well.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1306
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307 To specify a relative time, use numbers followed by units.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308 For example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1310 @table @samp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 @item 1 min
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1312 denotes 1 minute from now.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1313 @item 1 min 5 sec
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1314 denotes 65 seconds from now.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1315 @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
1316 denotes exactly 103 months, 123 days, and 10862 seconds from now.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1317 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1318
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1319 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
1320 days, and a year to be exactly 365.25 days.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1321
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1322 If @var{time} is a number (integer or floating point), that specifies a
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1323 relative time measured in seconds.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325 The argument @var{repeat} specifies how often to repeat the call. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 @var{repeat} is @code{nil}, there are no repetitions; @var{function} is
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1327 called just once, at @var{time}. If @var{repeat} is a number, it
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1328 specifies a repetition period measured in seconds.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1329
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1330 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
1331 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
1332 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
1333 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
1334 functions like @code{display-time}.
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
1335
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
1336 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
1337 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
1338 @code{cancel-timer} (see below).
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1339 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1341 @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
1342 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
1343 @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
1344 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
1345 @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
1346 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
1347 of them.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1348
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1349 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
1350 @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
1351 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
1352 executes @var{timeout-forms}.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1353
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1354 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
1355 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
1356 @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
1357 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
1358 @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
1359 @end defmac
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1360
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1361 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
1362 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
1363 Queries}.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1364
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1365 @defun run-with-idle-timer secs repeat function &rest args
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1366 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
1367 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
1368 number.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1369
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1370 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
1371 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
1372 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
1373 remains idle for @var{secs} seconds.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1374
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1375 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
1376 can use in calling @code{cancel-timer} (see below).
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1377 @end defun
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1378
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1379 @cindex idleness
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1380 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
1381 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
1382 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
1383 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
1384 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
1385 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
1386 seconds again.
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1387
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1388 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
1389 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
1390 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
1391 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
1392 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
1393 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
1394 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
1395
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1396 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
1397 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
1398 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
1399
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1400 @defun cancel-timer timer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1401 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
1402 previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1403 This cancels the effect of that call to @code{run-at-time}; the arrival
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1404 of the specified time will not cause anything special to happen.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407 @node Terminal Input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408 @section Terminal Input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409 @cindex terminal input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1411 This section describes functions and variables for recording or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1412 manipulating terminal input. See @ref{Display}, for related
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1413 functions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1414
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1415 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1416 * Input Modes:: Options for how input is processed.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1417 * Translating Input:: Low level conversion of some characters or events
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418 into others.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419 * Recording Input:: Saving histories of recent or all input events.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1422 @node Input Modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1423 @subsection Input Modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 @cindex input modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1425 @cindex terminal input modes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1426
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1427 @defun set-input-mode interrupt flow meta quit-char
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1428 This function sets the mode for reading keyboard input. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1429 @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
1430 @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
1431 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
1432 of what is specified.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1433
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1434 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
1435 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
1436
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1437 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
1438 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1439 has no effect except in @sc{cbreak} mode. @xref{Flow Control}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1442 The argument @var{meta} controls support for input character codes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443 above 127. If @var{meta} is @code{t}, Emacs converts characters with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444 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
1445 Emacs disregards the 8th bit; this is necessary when the terminal uses
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446 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
1447 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
1448 that use 8-bit character sets.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1449
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1450 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1451 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
1452 use for quitting. Normally this character is @kbd{C-g}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453 @xref{Quitting}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456 The @code{current-input-mode} function returns the input mode settings
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 Emacs is currently using.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460 @defun current-input-mode
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1461 This function returns the current mode for reading keyboard input. It
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462 returns a list, corresponding to the arguments of @code{set-input-mode},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 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
1464 which:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 @table @var
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466 @item interrupt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467 is non-@code{nil} when Emacs is using interrupt-driven input. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468 @code{nil}, Emacs is using @sc{cbreak} mode.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469 @item flow
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1470 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
1471 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
1472 when @var{interrupt} is @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 @item meta
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1474 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
1475 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
1476 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
1477 basic character code.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478 @item quit
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1479 is the character Emacs currently uses for quitting, usually @kbd{C-g}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1480 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1483 @node Translating Input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1484 @subsection Translating Input Events
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1485 @cindex translating input events
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1486
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1487 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
1488 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
1489 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
1490 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
1491 then translated through @code{keyboard-translate-table} (if applicable),
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1492 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
1493 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
1494 being read; then subsequences containing it are checked first with
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1495 @code{function-key-map} and then with @code{key-translation-map}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1496
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1497 @c Emacs 19 feature
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1498 @defvar extra-keyboard-modifiers
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1499 This variable lets Lisp programs ``press'' the modifier keys on the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500 keyboard. The value is a bit mask:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1501
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1502 @table @asis
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1503 @item 1
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1504 The @key{SHIFT} key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1505 @item 2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1506 The @key{LOCK} key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1507 @item 4
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1508 The @key{CTL} key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1509 @item 8
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1510 The @key{META} key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1511 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1512
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1513 Each time the user types a keyboard key, it is altered as if the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1514 modifier keys specified in the bit mask were held down.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1515
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1516 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
1517 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
1518 keys can be virtually pressed.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1519 @end defvar
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 @defvar keyboard-translate-table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1522 This variable is the translate table for keyboard characters. It lets
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1523 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
1524 bindings. Its value is normally a char-table, or else @code{nil}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1525
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1526 If @code{keyboard-translate-table} is a char-table
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1527 (@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
1528 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
1529 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
1530
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531 In the example below, we set @code{keyboard-translate-table} to a
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1532 char-table. Then we fill it in to swap the characters @kbd{C-s} and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1533 @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. Subsequently,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1534 typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice
25479
dcb2b7cbddca *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 25454
diff changeset
1535 versa. (@xref{Flow Control}, for more information on this subject.)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1537 @cindex flow control example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540 (defun evade-flow-control ()
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1541 "Replace C-s with C-\ and C-q with C-^."
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542 (interactive)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1544 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1545 (setq keyboard-translate-table
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1546 (make-char-table 'keyboard-translate-table nil))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1547 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1548 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1549 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1550 (aset keyboard-translate-table ?\034 ?\^s)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1551 (aset keyboard-translate-table ?\^s ?\034)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1552 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1553 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1554 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1555 (aset keyboard-translate-table ?\036 ?\^q)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1556 (aset keyboard-translate-table ?\^q ?\036))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1557 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1558 @end example
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 Note that this translation is the first thing that happens to a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1561 character after it is read from the terminal. Record-keeping features
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1562 such as @code{recent-keys} and dribble files record the characters after
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1563 translation.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564 @end defvar
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 @defun keyboard-translate from to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1567 This function modifies @code{keyboard-translate-table} to translate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1568 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
1569 the keyboard translate table if necessary.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1570 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1571
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1572 The remaining translation features translate subsequences of key
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1573 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
1574 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
1575
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1576 @defvar function-key-map
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1577 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
1578 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
1579 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
1580 translations to make while reading key sequences, rather than bindings
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1581 for key sequences.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1582
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1583 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
1584 @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
1585 key sequence, it is replaced with the events in @var{v}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1586
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1587 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
1588 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
1589 that sequence of events into the single event @code{pf1}. We accomplish
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1590 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1591 @code{function-key-map}, when using a VT100.
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 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
1594 @key{ESC} O P}; later the function @code{read-key-sequence} translates
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1595 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
1596 @code{[?\C-c pf1]}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1597
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1598 Entries in @code{function-key-map} are ignored if they conflict with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1599 bindings made in the minor mode, local, or global keymaps. The intent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1600 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
1601 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
1602 bindings take priority.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1603
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1604 The value of @code{function-key-map} is usually set up automatically
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1605 according to the terminal's Terminfo or Termcap entry, but sometimes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1606 those need help from terminal-specific Lisp files. Emacs comes with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1607 terminal-specific files for many common terminals; their main purpose is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1608 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
1609 deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1610 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1611
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1612 @defvar key-translation-map
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1613 This variable is another keymap used just like @code{function-key-map}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1614 to translate input events into other events. It differs from
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1615 @code{function-key-map} in two ways:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1616
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1617 @itemize @bullet
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1618 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1619 @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
1620 finished; it receives the results of translation by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1621 @code{function-key-map}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1622
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1623 @item
15762
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1624 @code{key-translation-map} overrides actual key bindings. For example,
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1625 if @kbd{C-x f} has a binding in @code{key-translation-map}, that
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1626 translation takes effect even though @kbd{C-x f} also has a key binding
9305e83c313d Lots of timer feature updates.
Richard M. Stallman <rms@gnu.org>
parents: 13367
diff changeset
1627 in the global map.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1628 @end itemize
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1629
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630 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
1631 character set to another, including ordinary characters normally bound
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1632 to @code{self-insert-command}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1633 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1634
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1635 @cindex key translation function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1636 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
1637 more than simple aliases, by using a function, instead of a key
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1638 sequence, as the ``translation'' of a key. Then this function is called
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1639 to compute the translation of that key.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1640
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1641 The key translation function receives one argument, which is the prompt
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1642 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
1643 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
1644 you can ignore the prompt value.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1645
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1646 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
1647 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
1648 to turn the character that follows into a Hyper character:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1649
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1650 @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
1651 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1652 (defun hyperify (prompt)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1653 (let ((e (read-event)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1654 (vector (if (numberp e)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1655 (logior (lsh 1 24) e)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1656 (if (memq 'hyper (event-modifiers e))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1657 e
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1658 (add-event-modifier "H-" e))))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1659
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1660 (defun add-event-modifier (string e)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1661 (let ((symbol (if (symbolp e) e (car e))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1662 (setq symbol (intern (concat string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1663 (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
1664 @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
1665 @group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1666 (if (symbolp e)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1667 symbol
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1668 (cons symbol (cdr e)))))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1669
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1670 (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
1671 @end group
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1672 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1673
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1674 Finally, if you have enabled keyboard character set decoding using
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1675 @code{set-keyboard-coding-system}, decoding is done after the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1676 translations listed above. @xref{Specifying Coding Systems}. In future
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1677 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
1678 translations.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1679
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1680 @node Recording Input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1681 @subsection Recording Input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1682
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1683 @defun recent-keys
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1684 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
1685 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
1686 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
1687 100 input events, not counting events generated by keyboard macros.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1688 (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
1689 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
1690
557aaff6fb23 (Time of Day): Document float-time.
Eli Zaretskii <eliz@gnu.org>
parents: 36873
diff changeset
1691 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
1692 causes this function to return an empty vector immediately afterward.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1693 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1694
26242
50d1336a4877 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 26211
diff changeset
1695 @deffn Command open-dribble-file filename
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1696 @cindex dribble file
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1697 This function opens a @dfn{dribble file} named @var{filename}. When a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1698 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
1699 not those from keyboard macros) is written in that file. A
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1700 non-character event is expressed using its printed representation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1701 surrounded by @samp{<@dots{}>}.
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 You close the dribble file by calling this function with an argument
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1704 of @code{nil}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1705
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1706 This function is normally used to record the input necessary to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1707 trigger an Emacs bug, for the sake of a bug report.
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 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1710 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1711 (open-dribble-file "~/dribble")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1712 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1713 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1714 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1715 @end deffn
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 See also the @code{open-termscript} function (@pxref{Terminal Output}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1718
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1719 @node Terminal Output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1720 @section Terminal Output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1721 @cindex terminal output
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1722
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1723 The terminal output functions send output to the terminal, or keep
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1724 track of output sent to the terminal. The variable @code{baud-rate}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1725 tells you what Emacs thinks is the output speed of the terminal.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1726
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1727 @defvar baud-rate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1728 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
1729 Emacs knows. Setting this variable does not change the speed of actual
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1730 data transmission, but the value is used for calculations such as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1731 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
1732 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
1733 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
1734 speed'', to give you a way to tune these decisions.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1735
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1736 The value is measured in baud.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1737 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1738
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1739 If you are running across a network, and different parts of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1740 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
1741 different from the value used by your local terminal. Some network
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1742 protocols communicate the local terminal speed to the remote machine, so
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1743 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
1744 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
1745 than optimal. To fix the problem, set @code{baud-rate}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1746
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1747 @defun baud-rate
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1748 This obsolete function returns the value of the variable
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1749 @code{baud-rate}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1750 @end defun
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 @defun send-string-to-terminal string
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1753 This function sends @var{string} to the terminal without alteration.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1754 Control characters in @var{string} have terminal-dependent effects.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1755
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1756 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
1757 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
1758 certain terminals) to define function key 4 to move forward four
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1759 characters (by transmitting the characters @kbd{C-u C-f} to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1760 computer):
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1761
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1762 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1763 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1764 (send-string-to-terminal "\eF4\^U\^F")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1765 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1766 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1767 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1768 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1769
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1770 @deffn Command open-termscript filename
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1771 @cindex termscript file
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1772 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
1773 all the characters sent by Emacs to the terminal. It returns
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1774 @code{nil}. Termscript files are useful for investigating problems
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1775 where Emacs garbles the screen, problems that are due to incorrect
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1776 Termcap entries or to undesirable settings of terminal options more
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1777 often than to actual Emacs bugs. Once you are certain which characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1778 were actually output, you can determine reliably whether they correspond
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1779 to the Termcap specifications in use.
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 See also @code{open-dribble-file} in @ref{Terminal Input}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1782
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1783 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1784 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1785 (open-termscript "../junk/termscript")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1786 @result{} nil
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1787 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1788 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1789 @end deffn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1790
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1791 @node Sound Output
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1792 @section Sound Output
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1793 @cindex sound
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1794
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1795 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
1796 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
1797 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
1798 earlier did not support sound at all.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1799
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1800 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
1801 or Sun Audio format (@samp{.au}).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1802
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1803 @tindex play-sound
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1804 @defun play-sound sound
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1805 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
1806 the form @code{(sound @var{properties}...)}, where the @var{properties}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1807 consist of alternating keywords (particular symbols recognized
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1808 specially) and values corresponding to them.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1809
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1810 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
1811 @var{sound}, and their meanings:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1812
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1813 @table @code
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1814 @item :file @var{file}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1815 This specifies the file containing the sound to play.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1816 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
1817 the directory @code{data-directory}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1818
27259
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
1819 @item :data @var{data}
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
1820 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
1821 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
1822 sound file. We recommend using a unibyte string.
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
1823
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1824 @item :volume @var{volume}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1825 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
1826 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
1827 specified before.
33951
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1828
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1829 @item :device @var{device}
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1830 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
1831 string. The default device is system-dependent.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1832 @end table
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1833
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1834 Before actually playing the sound, @code{play-sound}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1835 calls the functions in the list @code{play-sound-functions}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1836 Each function is called with one argument, @var{sound}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1837 @end defun
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1838
33951
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1839 @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
1840 @tindex play-sound-file
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1841 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
1842 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
1843 @end defun
ac7551c36926 Doc play-sound-file and sound :device.
Dave Love <fx@gnu.org>
parents: 32924
diff changeset
1844
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1845 @tindex play-sound-functions
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1846 @defvar play-sound-functions
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1847 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
1848 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
1849 @end defvar
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1850
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1851 @node Special Keysyms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1852 @section System-Specific X11 Keysyms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1853
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1854 To define system-specific X11 keysyms, set the variable
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1855 @code{system-key-alist}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1856
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1857 @defvar system-key-alist
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1858 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
1859 system-specific keysym. Each element has the form @code{(@var{code}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1860 . @var{symbol})}, where @var{code} is the numeric keysym code (not
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1861 including the ``vendor specific'' bit,
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1862 @ifnottex
24934
f5e3b4ecd255 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24848
diff changeset
1863 -2**28),
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1864 @end ifnottex
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1865 @tex
24934
f5e3b4ecd255 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24848
diff changeset
1866 $-2^{28}$),
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1867 @end tex
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1868 and @var{symbol} is the name for the function key.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1869
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1870 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
1871 by HP X servers) whose numeric code is
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1872 @ifnottex
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1873 -2**28
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1874 @end ifnottex
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1875 @tex
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1876 $-2^{28}$
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1877 @end tex
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1878 + 168.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1879
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1880 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
1881 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
1882 used by the X server actually in use.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 9009
diff changeset
1883
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1884 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
1885 buffer-local. @xref{Multiple Displays}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1886 @end defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1887
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1888 @node Flow Control
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1889 @section Flow Control
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1890 @cindex flow control characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1891
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1892 This section attempts to answer the question ``Why does Emacs use
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1893 flow-control characters in its command character set?'' For a second
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1894 view on this issue, read the comments on flow control in the
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1895 @file{emacs/INSTALL} file from the distribution; for help with Termcap
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1896 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
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 @cindex @kbd{C-s}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1899 @cindex @kbd{C-q}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1900 At one time, most terminals did not need flow control, and none used
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1901 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1902 @kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1903 was natural and uncontroversial. With so many commands needing key
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1904 assignments, of course we assigned meanings to nearly all @sc{ascii}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1905 control characters.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1906
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1907 Later, some terminals were introduced which required these characters
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1908 for flow control. They were not very good terminals for full-screen
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1909 editing, so Emacs maintainers ignored them. In later years, flow
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1910 control with @kbd{C-s} and @kbd{C-q} became widespread among terminals,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1911 but by this time it was usually an option. And the majority of Emacs
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1912 users, who can turn flow control off, did not want to switch to less
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1913 mnemonic key bindings for the sake of flow control.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1914
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1915 So which usage is ``right''---Emacs's or that of some terminal and
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1916 concentrator manufacturers? This question has no simple answer.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1917
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1918 One reason why we are reluctant to cater to the problems caused by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1919 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1920 techniques (albeit less common in practice) for flow control that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1921 preserve transparency of the character stream. Note also that their use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1922 for flow control is not an official standard. Interestingly, on the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1923 model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1924 @kbd{C-q} were sent by the computer to turn the punch on and off!
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1925
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1926 As window systems and PC terminal emulators replace character-only
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1927 terminals, the flow control problem is gradually disappearing. For the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1928 mean time, Emacs provides a convenient way of enabling flow control if
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1929 you want it: call the function @code{enable-flow-control}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1930
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1931 @deffn Command enable-flow-control
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1932 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1933 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1934 for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 20103
diff changeset
1935 @end deffn
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1936
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1937 You can use the function @code{enable-flow-control-on} in your
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
1938 init file to enable flow control automatically on certain
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1939 terminal types.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1940
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1941 @defun enable-flow-control-on &rest termtypes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1942 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^},
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1943 if the terminal type is one of @var{termtypes}. For example:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1944
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1945 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1946 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1947 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1948 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1949
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1950 Here is how @code{enable-flow-control} does its job:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1951
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1952 @enumerate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1953 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1954 @cindex @sc{cbreak}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1955 It sets @sc{cbreak} mode for terminal input, and tells the operating
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1956 system to handle flow control, with @code{(set-input-mode nil t)}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1957
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1958 @item
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1959 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7277
diff changeset
1960 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1961 lowest level, Emacs never knows that the characters typed were anything
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1962 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1963 and @kbd{C-^} even when they are input for other commands.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1964 @xref{Translating Input}.
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
1965 @end enumerate
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1966
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1967 If the terminal is the source of the flow control characters, then once
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1968 you enable kernel flow control handling, you probably can make do with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1969 less padding than normal for that terminal. You can reduce the amount
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1970 of padding by customizing the Termcap entry. You can also reduce it by
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1971 setting @code{baud-rate} to a smaller value so that Emacs uses a smaller
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1972 speed when calculating the padding needed. @xref{Terminal Output}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1973
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1974 @node Batch Mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1975 @section Batch Mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1976 @cindex batch mode
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1977 @cindex noninteractive use
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1978
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25479
diff changeset
1979 The command-line option @samp{-batch} causes Emacs to run
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1980 noninteractively. In this mode, Emacs does not read commands from the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1981 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
1982 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
1983 Lisp programs to run; when they are finished, Emacs should exit. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1984 way to specify the programs to run is with @samp{-l @var{file}}, which
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1985 loads the library named @var{file}, and @samp{-f @var{function}}, which
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1986 calls @var{function} with no arguments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1987
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1988 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
1989 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
1990 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
1991 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
1992 minibuffer is read from the standard input descriptor.
705d5129bb72 batch read from minibuffer
Dave Love <fx@gnu.org>
parents: 35476
diff changeset
1993 Thus, Emacs behaves much like a noninteractive
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1994 application program. (The echo area output that Emacs itself normally
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1995 generates, such as command echoing, is suppressed entirely.)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1996
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1997 @defvar noninteractive
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1998 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
1999 @end defvar
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2000
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2001 @node Session Management
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2002 @section Session Management
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2003 @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
2004
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2005 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
2006 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
2007 @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
2008 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
2009 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
2010 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
2011
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2012 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
2013 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
2014 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
2015 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
2016 @var{session}}.
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2017
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2018 @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
2019 @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
2020 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
2021 @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
2022 called when the session manager tells Emacs that the window system is
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2023 shutting down. The functions are called with the current buffer set
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2024 to a temporary buffer. Each functions can use @code{insert} to add
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2025 Lisp code to this buffer. At the end, Emacs saves the buffer in a
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2026 file that Emacs will 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
2027
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2028 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
2029 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
2030 shutdown.
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2031 @end defvar
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2032
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2033 Here is an example that just inserts some text into *scratch* when
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2034 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
2035
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2036 @example
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2037 @group
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2038 (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
2039 @end group
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2040
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2041 @group
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2042 (defun save-yourself-test ()
43829
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2043 (insert "(save-excursion
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2044 (switch-to-buffer \"*scratch*\")
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2045 (insert \"I am restored\"))")
7e937c00ff00 Clean up session manager node.
Richard M. Stallman <rms@gnu.org>
parents: 43822
diff changeset
2046 nil)
43822
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2047 @end group
340b4384f4ac (Session Management): New node about X Session management.
Jan Djärv <jan.h.d@swipnet.se>
parents: 43037
diff changeset
2048 @end example