annotate man/cmdargs.texi @ 41178:a639b1cc4fd5

*** empty log message ***
author Jason Rumney <jasonr@gnu.org>
date Sat, 17 Nov 2001 01:00:14 +0000
parents 8dc305c093c1
children 72709f10af2b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1 @c This is part of the Emacs manual.
39287
3b40423b9355 Update the copyright years.
Eli Zaretskii <eliz@gnu.org>
parents: 39286
diff changeset
2 @c Copyright (C) 1985,86,87,93,94,95,1997,2001 Free Software Foundation, Inc.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
3 @c See file emacs.texi for copying conditions.
40524
5c00f23a93ec Everything about X resources moved to xresources.texi.
Richard M. Stallman <rms@gnu.org>
parents: 39287
diff changeset
4 @node Command Arguments, X Resources, Service, Top
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
5 @appendix Command Line Arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
6 @cindex command line arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
7 @cindex arguments (command line)
Dave Love <fx@gnu.org>
parents:
diff changeset
8 @cindex options (command line)
Dave Love <fx@gnu.org>
parents:
diff changeset
9 @cindex switches (command line)
Dave Love <fx@gnu.org>
parents:
diff changeset
10 @cindex startup (command line arguments)
Dave Love <fx@gnu.org>
parents:
diff changeset
11
Dave Love <fx@gnu.org>
parents:
diff changeset
12 GNU Emacs supports command line arguments to request various actions
Dave Love <fx@gnu.org>
parents:
diff changeset
13 when invoking Emacs. These are for compatibility with other editors and
Dave Love <fx@gnu.org>
parents:
diff changeset
14 for sophisticated activities. We don't recommend using them for
Dave Love <fx@gnu.org>
parents:
diff changeset
15 ordinary editing.
Dave Love <fx@gnu.org>
parents:
diff changeset
16
Dave Love <fx@gnu.org>
parents:
diff changeset
17 Arguments starting with @samp{-} are @dfn{options}. Other arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
18 specify files to visit. Emacs visits the specified files while it
37835
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
19 starts up. The last file name on your command line becomes the
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
20 current buffer; the other files are also visited in other buffers. If
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
21 there are two files, they are both displayed; otherwise the last file
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
22 is displayed along with a buffer list that shows what other buffers
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
23 there are. As with most programs, the special argument @samp{--} says
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
24 that all subsequent arguments are file names, not options, even if
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
25 they start with @samp{-}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
26
Dave Love <fx@gnu.org>
parents:
diff changeset
27 Emacs command options can specify many things, such as the size and
Dave Love <fx@gnu.org>
parents:
diff changeset
28 position of the X window Emacs uses, its colors, and so on. A few
Dave Love <fx@gnu.org>
parents:
diff changeset
29 options support advanced usage, such as running Lisp functions on files
Dave Love <fx@gnu.org>
parents:
diff changeset
30 in batch mode. The sections of this chapter describe the available
Dave Love <fx@gnu.org>
parents:
diff changeset
31 options, arranged according to their purpose.
Dave Love <fx@gnu.org>
parents:
diff changeset
32
Dave Love <fx@gnu.org>
parents:
diff changeset
33 There are two ways of writing options: the short forms that start with
Dave Love <fx@gnu.org>
parents:
diff changeset
34 a single @samp{-}, and the long forms that start with @samp{--}. For
Dave Love <fx@gnu.org>
parents:
diff changeset
35 example, @samp{-d} is a short form and @samp{--display} is the
Dave Love <fx@gnu.org>
parents:
diff changeset
36 corresponding long form.
Dave Love <fx@gnu.org>
parents:
diff changeset
37
Dave Love <fx@gnu.org>
parents:
diff changeset
38 The long forms with @samp{--} are easier to remember, but longer to
Dave Love <fx@gnu.org>
parents:
diff changeset
39 type. However, you don't have to spell out the whole option name; any
Dave Love <fx@gnu.org>
parents:
diff changeset
40 unambiguous abbreviation is enough. When a long option takes an
Dave Love <fx@gnu.org>
parents:
diff changeset
41 argument, you can use either a space or an equal sign to separate the
Dave Love <fx@gnu.org>
parents:
diff changeset
42 option name and the argument. Thus, you can write either
Dave Love <fx@gnu.org>
parents:
diff changeset
43 @samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}.
Dave Love <fx@gnu.org>
parents:
diff changeset
44 We recommend an equal sign because it makes the relationship clearer,
Dave Love <fx@gnu.org>
parents:
diff changeset
45 and the tables below always show an equal sign.
Dave Love <fx@gnu.org>
parents:
diff changeset
46
Dave Love <fx@gnu.org>
parents:
diff changeset
47 @cindex initial options (command line)
Dave Love <fx@gnu.org>
parents:
diff changeset
48 @cindex action options (command line)
Dave Love <fx@gnu.org>
parents:
diff changeset
49 Most options specify how to initialize Emacs, or set parameters for
Dave Love <fx@gnu.org>
parents:
diff changeset
50 the Emacs session. We call them @dfn{initial options}. A few options
Dave Love <fx@gnu.org>
parents:
diff changeset
51 specify things to do: for example, load libraries, call functions, or
38745
5464ee1ba8e2 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38669
diff changeset
52 terminate Emacs. These are called @dfn{action options}. These and file
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
53 names together are called @dfn{action arguments}. Emacs processes all
Dave Love <fx@gnu.org>
parents:
diff changeset
54 the action arguments in the order they are written.
Dave Love <fx@gnu.org>
parents:
diff changeset
55
Dave Love <fx@gnu.org>
parents:
diff changeset
56 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
57 * Action Arguments:: Arguments to visit files, load libraries,
Dave Love <fx@gnu.org>
parents:
diff changeset
58 and call functions.
Dave Love <fx@gnu.org>
parents:
diff changeset
59 * Initial Options:: Arguments that take effect while starting Emacs.
Dave Love <fx@gnu.org>
parents:
diff changeset
60 * Command Example:: Examples of using command line arguments.
Dave Love <fx@gnu.org>
parents:
diff changeset
61 * Resume Arguments:: Specifying arguments when you resume a running Emacs.
Dave Love <fx@gnu.org>
parents:
diff changeset
62 * Environment:: Environment variables that Emacs uses.
Dave Love <fx@gnu.org>
parents:
diff changeset
63 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
64
Dave Love <fx@gnu.org>
parents:
diff changeset
65 @node Action Arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
66 @appendixsec Action Arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
67
Dave Love <fx@gnu.org>
parents:
diff changeset
68 Here is a table of the action arguments and options:
Dave Love <fx@gnu.org>
parents:
diff changeset
69
Dave Love <fx@gnu.org>
parents:
diff changeset
70 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
71 @item @var{file}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
72 @opindex --visit
36500
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
73 @itemx --visit=@var{file}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
74 @opindex --file
36500
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
75 @itemx --file=@var{file}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
76 @cindex visiting files, command-line argument
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
77 Visit @var{file} using @code{find-file}. @xref{Visiting}.
Dave Love <fx@gnu.org>
parents:
diff changeset
78
Dave Love <fx@gnu.org>
parents:
diff changeset
79 @item +@var{linenum} @var{file}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
80 @opindex +@var{linenum}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
81 Visit @var{file} using @code{find-file}, then go to line number
Dave Love <fx@gnu.org>
parents:
diff changeset
82 @var{linenum} in it.
Dave Love <fx@gnu.org>
parents:
diff changeset
83
38466
7f9fe7268ee4 Add description of +LINE:COLUMN.
Gerd Moellmann <gerd@gnu.org>
parents: 37835
diff changeset
84 @item +@var{linenum}:@var{columnnum} @var{file}
7f9fe7268ee4 Add description of +LINE:COLUMN.
Gerd Moellmann <gerd@gnu.org>
parents: 37835
diff changeset
85 Visit @var{file} using @code{find-file}, then go to line number
38745
5464ee1ba8e2 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38669
diff changeset
86 @var{linenum} and put point at column number @var{columnnum}.
38466
7f9fe7268ee4 Add description of +LINE:COLUMN.
Gerd Moellmann <gerd@gnu.org>
parents: 37835
diff changeset
87
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
88 @need 3000
Dave Love <fx@gnu.org>
parents:
diff changeset
89 @item -l @var{file}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
90 @opindex -l
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
91 @itemx --load=@var{file}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
92 @opindex --load
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
93 @cindex loading Lisp libraries, command-line argument
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
94 Load a Lisp library named @var{file} with the function @code{load}.
Dave Love <fx@gnu.org>
parents:
diff changeset
95 @xref{Lisp Libraries}. The library can be found either in the current
Dave Love <fx@gnu.org>
parents:
diff changeset
96 directory, or in the Emacs library search path as specified
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
97 with @env{EMACSLOADPATH} (@pxref{General Variables}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
98
Dave Love <fx@gnu.org>
parents:
diff changeset
99 @item -f @var{function}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
100 @opindex -f
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
101 @itemx --funcall=@var{function}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
102 @opindex --funcall
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
103 @cindex call Lisp functions, command-line argument
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
104 Call Lisp function @var{function} with no arguments.
Dave Love <fx@gnu.org>
parents:
diff changeset
105
36500
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
106 @item --eval=@var{expression}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
107 @opindex --eval
36500
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
108 @itemx --execute=@var{expression}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
109 @opindex --execute
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
110 @cindex evaluate expression, command-line argument
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
111 Evaluate Lisp expression @var{expression}.
Dave Love <fx@gnu.org>
parents:
diff changeset
112
Dave Love <fx@gnu.org>
parents:
diff changeset
113 @item --insert=@var{file}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
114 @opindex --insert
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
115 @cindex insert file contents, command-line argument
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
116 Insert the contents of @var{file} into the current buffer. This is like
Dave Love <fx@gnu.org>
parents:
diff changeset
117 what @kbd{M-x insert-file} does. @xref{Misc File Ops}.
Dave Love <fx@gnu.org>
parents:
diff changeset
118
Dave Love <fx@gnu.org>
parents:
diff changeset
119 @item --kill
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
120 @opindex --kill
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
121 Exit from Emacs without asking for confirmation.
Dave Love <fx@gnu.org>
parents:
diff changeset
122 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
123
Dave Love <fx@gnu.org>
parents:
diff changeset
124 @vindex command-line-args
Dave Love <fx@gnu.org>
parents:
diff changeset
125 The init file can access the values of the action arguments as the
Dave Love <fx@gnu.org>
parents:
diff changeset
126 elements of a list in the variable @code{command-line-args}. The init
Dave Love <fx@gnu.org>
parents:
diff changeset
127 file can override the normal processing of the action arguments, or
Dave Love <fx@gnu.org>
parents:
diff changeset
128 define new ones, by reading and setting this variable.
Dave Love <fx@gnu.org>
parents:
diff changeset
129
Dave Love <fx@gnu.org>
parents:
diff changeset
130 @node Initial Options
Dave Love <fx@gnu.org>
parents:
diff changeset
131 @appendixsec Initial Options
Dave Love <fx@gnu.org>
parents:
diff changeset
132
Dave Love <fx@gnu.org>
parents:
diff changeset
133 The initial options specify parameters for the Emacs session. This
Dave Love <fx@gnu.org>
parents:
diff changeset
134 section describes the more general initial options; some other options
35188
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34221
diff changeset
135 specifically related to the X Window System appear in the following
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34221
diff changeset
136 sections.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
137
Dave Love <fx@gnu.org>
parents:
diff changeset
138 Some initial options affect the loading of init files. The normal
Dave Love <fx@gnu.org>
parents:
diff changeset
139 actions of Emacs are to first load @file{site-start.el} if it exists,
Dave Love <fx@gnu.org>
parents:
diff changeset
140 then your own init file @file{~/.emacs} if it exists, and finally
Dave Love <fx@gnu.org>
parents:
diff changeset
141 @file{default.el} if it exists; certain options prevent loading of some
Dave Love <fx@gnu.org>
parents:
diff changeset
142 of these files or substitute other files for them.
Dave Love <fx@gnu.org>
parents:
diff changeset
143
Dave Love <fx@gnu.org>
parents:
diff changeset
144 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
145 @item -t @var{device}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
146 @opindex -t
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
147 @itemx --terminal=@var{device}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
148 @opindex --terminal
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
149 @cindex device for Emacs terminal I/O
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
150 Use @var{device} as the device for terminal input and output.
Dave Love <fx@gnu.org>
parents:
diff changeset
151
Dave Love <fx@gnu.org>
parents:
diff changeset
152 @item -d @var{display}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
153 @opindex -d
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
154 @itemx --display=@var{display}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
155 @opindex --display
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
156 @cindex display for Emacs frame
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
157 Use the X Window System and use the display named @var{display} to open
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
158 the initial Emacs frame. @xref{Display X}, for more details.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
159
Dave Love <fx@gnu.org>
parents:
diff changeset
160 @item -nw
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
161 @opindex -nw
40563
62cd2910ba80 (Initial Options): Document command line option --no-window-system instead
Pavel Janík <Pavel@Janik.cz>
parents: 40524
diff changeset
162 @itemx --no-window-system
62cd2910ba80 (Initial Options): Document command line option --no-window-system instead
Pavel Janík <Pavel@Janik.cz>
parents: 40524
diff changeset
163 @opindex --no-window-system
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
164 @cindex disable window system
33012
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
165 Don't communicate directly with the window system, disregarding the
40652
8dc305c093c1 Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 40584
diff changeset
166 @env{DISPLAY} environment variable even if it is set. This means that
8dc305c093c1 Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 40584
diff changeset
167 Emacs uses the terminal from which it was launched for all its display
8dc305c093c1 Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 40584
diff changeset
168 and input.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
169
Dave Love <fx@gnu.org>
parents:
diff changeset
170 @need 3000
Dave Love <fx@gnu.org>
parents:
diff changeset
171 @cindex batch mode
Dave Love <fx@gnu.org>
parents:
diff changeset
172 @item -batch
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
173 @opindex --batch
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
174 @itemx --batch
Dave Love <fx@gnu.org>
parents:
diff changeset
175 Run Emacs in @dfn{batch mode}, which means that the text being edited is
Dave Love <fx@gnu.org>
parents:
diff changeset
176 not displayed and the standard terminal interrupt characters such as
Dave Love <fx@gnu.org>
parents:
diff changeset
177 @kbd{C-z} and @kbd{C-c} continue to have their normal effect. Emacs in
38870
d44abb4e68b2 Don't use "print" for displaying a message.
Richard M. Stallman <rms@gnu.org>
parents: 38773
diff changeset
178 batch mode outputs to @code{stderr} only what would normally be displayed
36875
6a6141e694a5 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 36841
diff changeset
179 in the echo area under program control, and functions which would
6a6141e694a5 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 36841
diff changeset
180 normally read from the minibuffer take their input from @code{stdin}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
181
Dave Love <fx@gnu.org>
parents:
diff changeset
182 Batch mode is used for running programs written in Emacs Lisp from
Dave Love <fx@gnu.org>
parents:
diff changeset
183 shell scripts, makefiles, and so on. Normally the @samp{-l} option
Dave Love <fx@gnu.org>
parents:
diff changeset
184 or @samp{-f} option will be used as well, to invoke a Lisp program
Dave Love <fx@gnu.org>
parents:
diff changeset
185 to do the batch processing.
Dave Love <fx@gnu.org>
parents:
diff changeset
186
38745
5464ee1ba8e2 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38669
diff changeset
187 @samp{-batch} implies @samp{-q} (do not load an init file). It also
5464ee1ba8e2 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38669
diff changeset
188 causes Emacs to exit after processing all the command options. In
5464ee1ba8e2 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38669
diff changeset
189 addition, it disables auto-saving except in buffers for which it has
5464ee1ba8e2 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38669
diff changeset
190 been explicitly requested.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
191
Dave Love <fx@gnu.org>
parents:
diff changeset
192 @item -q
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
193 @opindex -q
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
194 @itemx --no-init-file
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
195 @opindex --no-init-file
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
196 @cindex bypassing init and site-start file
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
197 @cindex init file, not loading
37595
fe04457ea88a (Initial Options): Add index entries for not loading startup files.
Eli Zaretskii <eliz@gnu.org>
parents: 37451
diff changeset
198 @cindex @file{default.el} file, not loading
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
199 Do not load your Emacs init file @file{~/.emacs}, or @file{default.el}
38659
492c796cd5af Fix "allows to save".
Eli Zaretskii <eliz@gnu.org>
parents: 38648
diff changeset
200 either. When invoked like this, Emacs does not allow saving options
37619
3b026479775e (Initial Options): Document that -q disables customizations saving.
Eli Zaretskii <eliz@gnu.org>
parents: 37595
diff changeset
201 changed with the @kbd{M-x customize} command and its variants.
3b026479775e (Initial Options): Document that -q disables customizations saving.
Eli Zaretskii <eliz@gnu.org>
parents: 37595
diff changeset
202 @xref{Easy Customization}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
203
Dave Love <fx@gnu.org>
parents:
diff changeset
204 @item --no-site-file
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
205 @opindex --no-site-file
37595
fe04457ea88a (Initial Options): Add index entries for not loading startup files.
Eli Zaretskii <eliz@gnu.org>
parents: 37451
diff changeset
206 @cindex @file{site-start.el} file, not loading
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
207 Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u}
Dave Love <fx@gnu.org>
parents:
diff changeset
208 and @samp{-batch} have no effect on the loading of this file---this is
Dave Love <fx@gnu.org>
parents:
diff changeset
209 the only option that blocks it.
Dave Love <fx@gnu.org>
parents:
diff changeset
210
Dave Love <fx@gnu.org>
parents:
diff changeset
211 @item -u @var{user}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
212 @opindex -u
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
213 @itemx --user=@var{user}
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
214 @opindex --user
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
215 @cindex load init file of another user
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
216 Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
Dave Love <fx@gnu.org>
parents:
diff changeset
217 your own.
Dave Love <fx@gnu.org>
parents:
diff changeset
218
Dave Love <fx@gnu.org>
parents:
diff changeset
219 @item --debug-init
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
220 @opindex --debug-init
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
221 @cindex errors in init file
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
222 Enable the Emacs Lisp debugger for errors in the init file.
Dave Love <fx@gnu.org>
parents:
diff changeset
223
Dave Love <fx@gnu.org>
parents:
diff changeset
224 @item --unibyte
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
225 @opindex --unibyte
31142
7d0a8b91a6c0 Mention that Lisp files are normally read as multibyte.
Eli Zaretskii <eliz@gnu.org>
parents: 30967
diff changeset
226 @cindex unibyte operation, command-line argument
38648
66e920bfc687 Fix typos; from Eric Hanchrow <offby1@blarg.net>.
Eli Zaretskii <eliz@gnu.org>
parents: 38466
diff changeset
227 Do almost everything with single-byte buffers and strings.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
228 All buffers and strings are unibyte unless you (or a Lisp program)
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
229 explicitly ask for a multibyte buffer or string. (Note that Emacs
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
230 always loads Lisp files in multibyte mode, even if @samp{--unibyte} is
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
231 specified; see @ref{Enabling Multibyte}.) Setting the environment
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
232 variable @env{EMACS_UNIBYTE} has the same effect.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
233
Dave Love <fx@gnu.org>
parents:
diff changeset
234 @item --multibyte
37451
ff30b541575a Add @opindex entries to index all command-line options.
Eli Zaretskii <eliz@gnu.org>
parents: 37425
diff changeset
235 @opindex --multibyte
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
236 Inhibit the effect of @env{EMACS_UNIBYTE}, so that Emacs
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
237 uses multibyte characters by default, as usual.
Dave Love <fx@gnu.org>
parents:
diff changeset
238 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
239
Dave Love <fx@gnu.org>
parents:
diff changeset
240 @node Command Example
Dave Love <fx@gnu.org>
parents:
diff changeset
241 @appendixsec Command Argument Example
Dave Love <fx@gnu.org>
parents:
diff changeset
242
Dave Love <fx@gnu.org>
parents:
diff changeset
243 Here is an example of using Emacs with arguments and options. It
Dave Love <fx@gnu.org>
parents:
diff changeset
244 assumes you have a Lisp program file called @file{hack-c.el} which, when
Dave Love <fx@gnu.org>
parents:
diff changeset
245 loaded, performs some useful operation on the current buffer, expected
Dave Love <fx@gnu.org>
parents:
diff changeset
246 to be a C program.
Dave Love <fx@gnu.org>
parents:
diff changeset
247
Dave Love <fx@gnu.org>
parents:
diff changeset
248 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
249 emacs -batch foo.c -l hack-c -f save-buffer >& log
Dave Love <fx@gnu.org>
parents:
diff changeset
250 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
251
Dave Love <fx@gnu.org>
parents:
diff changeset
252 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
253 This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
Dave Love <fx@gnu.org>
parents:
diff changeset
254 changes in the visited file), save @file{foo.c} (note that
Dave Love <fx@gnu.org>
parents:
diff changeset
255 @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
Dave Love <fx@gnu.org>
parents:
diff changeset
256 then exit back to the shell (because of @samp{-batch}). @samp{-batch}
Dave Love <fx@gnu.org>
parents:
diff changeset
257 also guarantees there will be no problem redirecting output to
Dave Love <fx@gnu.org>
parents:
diff changeset
258 @file{log}, because Emacs will not assume that it has a display terminal
Dave Love <fx@gnu.org>
parents:
diff changeset
259 to work with.
Dave Love <fx@gnu.org>
parents:
diff changeset
260
Dave Love <fx@gnu.org>
parents:
diff changeset
261 @node Resume Arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
262 @appendixsec Resuming Emacs with Arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
263
Dave Love <fx@gnu.org>
parents:
diff changeset
264 You can specify action arguments for Emacs when you resume it after
Dave Love <fx@gnu.org>
parents:
diff changeset
265 a suspension. To prepare for this, put the following code in your
Dave Love <fx@gnu.org>
parents:
diff changeset
266 @file{.emacs} file (@pxref{Hooks}):
Dave Love <fx@gnu.org>
parents:
diff changeset
267
37835
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
268 @c `resume-suspend-hook' is correct. It is the name of a function.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
269 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
270 (add-hook 'suspend-hook 'resume-suspend-hook)
Dave Love <fx@gnu.org>
parents:
diff changeset
271 (add-hook 'suspend-resume-hook 'resume-process-args)
Dave Love <fx@gnu.org>
parents:
diff changeset
272 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
273
Dave Love <fx@gnu.org>
parents:
diff changeset
274 As further preparation, you must execute the shell script
37835
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
275 @file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash}
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
276 (if you use bash as your shell). These scripts define an alias named
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
277 @code{edit}, which will resume Emacs giving it new command line
37835
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
278 arguments such as files to visit. The scripts are found in the
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
279 @file{etc} subdirectory of the Emacs distribution.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
280
Dave Love <fx@gnu.org>
parents:
diff changeset
281 Only action arguments work properly when you resume Emacs. Initial
Dave Love <fx@gnu.org>
parents:
diff changeset
282 arguments are not recognized---it's too late to execute them anyway.
Dave Love <fx@gnu.org>
parents:
diff changeset
283
Dave Love <fx@gnu.org>
parents:
diff changeset
284 Note that resuming Emacs (with or without arguments) must be done from
Dave Love <fx@gnu.org>
parents:
diff changeset
285 within the shell that is the parent of the Emacs job. This is why
Dave Love <fx@gnu.org>
parents:
diff changeset
286 @code{edit} is an alias rather than a program or a shell script. It is
Dave Love <fx@gnu.org>
parents:
diff changeset
287 not possible to implement a resumption command that could be run from
38648
66e920bfc687 Fix typos; from Eric Hanchrow <offby1@blarg.net>.
Eli Zaretskii <eliz@gnu.org>
parents: 38466
diff changeset
288 other subjobs of the shell; there is no way to define a command that could
66e920bfc687 Fix typos; from Eric Hanchrow <offby1@blarg.net>.
Eli Zaretskii <eliz@gnu.org>
parents: 38466
diff changeset
289 be made the value of @env{EDITOR}, for example. Therefore, this feature
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
290 does not take the place of the Emacs Server feature (@pxref{Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
291 Server}).
Dave Love <fx@gnu.org>
parents:
diff changeset
292
Dave Love <fx@gnu.org>
parents:
diff changeset
293 The aliases use the Emacs Server feature if you appear to have a
Dave Love <fx@gnu.org>
parents:
diff changeset
294 server Emacs running. However, they cannot determine this with complete
Dave Love <fx@gnu.org>
parents:
diff changeset
295 accuracy. They may think that a server is still running when in
Dave Love <fx@gnu.org>
parents:
diff changeset
296 actuality you have killed that Emacs, because the file
37835
a4f04496cfb0 Update description of visiting multiple files with the command line.
Richard M. Stallman <rms@gnu.org>
parents: 37796
diff changeset
297 @file{/tmp/esrv@dots{}} still exists. If this happens, find that
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
298 file and delete it.
Dave Love <fx@gnu.org>
parents:
diff changeset
299
Dave Love <fx@gnu.org>
parents:
diff changeset
300 @node Environment
Dave Love <fx@gnu.org>
parents:
diff changeset
301 @appendixsec Environment Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
302 @cindex environment variables
Dave Love <fx@gnu.org>
parents:
diff changeset
303
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
304 The @dfn{environment} is a feature of the operating system; it
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
305 consists of a collection of variables with names and values. Each
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
306 variable is called an @dfn{environment variable}; environment variable
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
307 names are case-sensitive, and it is conventional to use upper case
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
308 letters only. The values are all text strings.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
309
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
310 What makes the environment useful is that subprocesses inherit the
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
311 environment automatically from their parent process. This means you
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
312 can set up an environment variable in your login shell, and all the
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
313 programs you run (including Emacs) will automatically see it.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
314 Subprocesses of Emacs (such as shells, compilers, and version-control
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
315 software) inherit the environment from Emacs, too.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
316
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
317 @findex setenv
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
318 @findex getenv
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
319 Inside Emacs, the command @kbd{M-x getenv} gets the value of an
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
320 environment variable. @kbd{M-x setenv} sets a variable in the Emacs
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
321 environment. The way to set environment variables outside of Emacs
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
322 depends on the operating system, and especially the shell that you are
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
323 using. For example, here's how to set the environment variable
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
324 @env{ORGANIZATION} to @samp{not very much} using Bash:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
325
Dave Love <fx@gnu.org>
parents:
diff changeset
326 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
327 export ORGANIZATION="not very much"
Dave Love <fx@gnu.org>
parents:
diff changeset
328 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
329
Dave Love <fx@gnu.org>
parents:
diff changeset
330 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
331 and here's how to do it in csh or tcsh:
Dave Love <fx@gnu.org>
parents:
diff changeset
332
Dave Love <fx@gnu.org>
parents:
diff changeset
333 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
334 setenv ORGANIZATION "not very much"
Dave Love <fx@gnu.org>
parents:
diff changeset
335 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
336
38648
66e920bfc687 Fix typos; from Eric Hanchrow <offby1@blarg.net>.
Eli Zaretskii <eliz@gnu.org>
parents: 38466
diff changeset
337 When Emacs is uses the X Window System, it inherits the use
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
338 of a large number of environment variables from the X libraries. See
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
339 the X documentation for more information.
Dave Love <fx@gnu.org>
parents:
diff changeset
340
Dave Love <fx@gnu.org>
parents:
diff changeset
341 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
342 * General Variables:: Environment variables that all versions of Emacs use.
Dave Love <fx@gnu.org>
parents:
diff changeset
343 * Misc Variables:: Certain system-specific variables.
Dave Love <fx@gnu.org>
parents:
diff changeset
344 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
345
Dave Love <fx@gnu.org>
parents:
diff changeset
346 @node General Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
347 @appendixsubsec General Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
348
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
349 Here is an alphabetical list of specific environment variables that
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
350 have special meanings in Emacs, giving the name of each variable and
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
351 its meaning. Most of these variables are also used by some other
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
352 programs. Emacs does not require any of these environment variables
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
353 to be set, but it uses their values if they are set.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
354
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
355 @table @env
36362
193e0fa6c140 (General Variables): Fix a typo in the CDPATH entry.
Eli Zaretskii <eliz@gnu.org>
parents: 36346
diff changeset
356 @item CDPATH
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
357 Used by the @code{cd} command to search for the directory you specify,
Dave Love <fx@gnu.org>
parents:
diff changeset
358 when you specify a relative directory name.
Dave Love <fx@gnu.org>
parents:
diff changeset
359 @item EMACS_UNIBYTE
31142
7d0a8b91a6c0 Mention that Lisp files are normally read as multibyte.
Eli Zaretskii <eliz@gnu.org>
parents: 30967
diff changeset
360 @cindex unibyte operation, environment variable
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
361 Defining this environment variable with a nonempty value directs Emacs
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
362 to do almost everything with single-byte buffers and strings. It is
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
363 equivalent to using the @samp{--unibyte} command-line option on each
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
364 invocation. @xref{Initial Options}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
365 @item EMACSDATA
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
366 Directory for the architecture-independent files that come with Emacs.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
367 This is used to initialize the Lisp variable @code{data-directory}.
35490
2e4bf60771ea (General Variables): Document $EMACSDOC.
Eli Zaretskii <eliz@gnu.org>
parents: 35188
diff changeset
368 @item EMACSDOC
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
369 Directory for the documentation string file,
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
370 @file{DOC-@var{emacsversion}}. This is used to initialize the Lisp
36295
1203ee52391f (General Variables) <EMACSDOC>: It's used to
Gerd Moellmann <gerd@gnu.org>
parents: 36293
diff changeset
371 variable @code{doc-directory}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
372 @item EMACSLOADPATH
36364
fca71f0d9dc4 (General Variables): Add a footnote that all *PATH variables use
Eli Zaretskii <eliz@gnu.org>
parents: 36363
diff changeset
373 A colon-separated list of directories@footnote{
fca71f0d9dc4 (General Variables): Add a footnote that all *PATH variables use
Eli Zaretskii <eliz@gnu.org>
parents: 36363
diff changeset
374 Here and below, whenever we say ``colon-separated list of directories'',
fca71f0d9dc4 (General Variables): Add a footnote that all *PATH variables use
Eli Zaretskii <eliz@gnu.org>
parents: 36363
diff changeset
375 it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows,
fca71f0d9dc4 (General Variables): Add a footnote that all *PATH variables use
Eli Zaretskii <eliz@gnu.org>
parents: 36363
diff changeset
376 the directories are separated by semi-colons instead, since DOS/Windows
fca71f0d9dc4 (General Variables): Add a footnote that all *PATH variables use
Eli Zaretskii <eliz@gnu.org>
parents: 36363
diff changeset
377 file names might include a colon after a drive letter.}
fca71f0d9dc4 (General Variables): Add a footnote that all *PATH variables use
Eli Zaretskii <eliz@gnu.org>
parents: 36363
diff changeset
378 to search for Emacs Lisp files---used to initialize @code{load-path}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
379 @item EMACSPATH
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
380 A colon-separated list of directories to search for executable
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
381 files---used to initialize @code{exec-path}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
382 @item ESHELL
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
383 Used for shell-mode to override the @env{SHELL} environment variable.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
384 @item HISTFILE
Dave Love <fx@gnu.org>
parents:
diff changeset
385 The name of the file that shell commands are saved in between logins.
36500
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
386 This variable defaults to @file{~/.bash_history} if you use Bash, to
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
387 @file{~/.sh_history} if you use ksh, and to @file{~/.history}
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
388 otherwise.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
389 @item HOME
Dave Love <fx@gnu.org>
parents:
diff changeset
390 The location of the user's files in the directory tree; used for
Dave Love <fx@gnu.org>
parents:
diff changeset
391 expansion of file names starting with a tilde (@file{~}). On MS-DOS, it
Dave Love <fx@gnu.org>
parents:
diff changeset
392 defaults to the directory from which Emacs was started, with @samp{/bin}
36346
5bd8f163760f (General Variables): Document the default value of $HOME on Windows.
Eli Zaretskii <eliz@gnu.org>
parents: 36297
diff changeset
393 removed from the end if it was present. On Windows, the default value
5bd8f163760f (General Variables): Document the default value of $HOME on Windows.
Eli Zaretskii <eliz@gnu.org>
parents: 36297
diff changeset
394 of @code{HOME} is @file{C:/}, the root directory of drive @file{C:}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
395 @item HOSTNAME
Dave Love <fx@gnu.org>
parents:
diff changeset
396 The name of the machine that Emacs is running on.
Dave Love <fx@gnu.org>
parents:
diff changeset
397 @item INCPATH
Dave Love <fx@gnu.org>
parents:
diff changeset
398 A colon-separated list of directories. Used by the @code{complete} package
Dave Love <fx@gnu.org>
parents:
diff changeset
399 to search for files.
Dave Love <fx@gnu.org>
parents:
diff changeset
400 @item INFOPATH
36295
1203ee52391f (General Variables) <EMACSDOC>: It's used to
Gerd Moellmann <gerd@gnu.org>
parents: 36293
diff changeset
401 A colon-separated list of directories in which to search for Info files.
26140
068f7ad41d40 Describe new functions and variables for locales.
Paul Eggert <eggert@twinsun.com>
parents: 25829
diff changeset
402 @item LC_ALL
37085
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
403 @itemx LC_COLLATE
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
404 @itemx LC_CTYPE
37085
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
405 @itemx LC_MESSAGES
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
406 @itemx LC_MONETARY
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
407 @itemx LC_NUMERIC
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
408 @itemx LC_TIME
26140
068f7ad41d40 Describe new functions and variables for locales.
Paul Eggert <eggert@twinsun.com>
parents: 25829
diff changeset
409 @itemx LANG
37085
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
410 The user's preferred locale. The locale has six categories, specified
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
411 by the environment variables @env{LC_COLLATE} for sorting,
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
412 @env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
413 messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
414 numbers, and @env{LC_TIME} for dates and times. If one of these
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
415 variables is not set, the category defaults to the value of the
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
416 @env{LANG} environment variable, or to the default @samp{C} locale if
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
417 @env{LANG} is not set. But if @env{LC_ALL} is specified, it overrides
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
418 the settings of all the other locale environment variables.
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
419
37085
cce9b46e707b (General Variables): Update the docs according to current behavior
Eli Zaretskii <eliz@gnu.org>
parents: 36875
diff changeset
420 The value of the LC_CTYPE category is
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
421 matched against entries in @code{locale-language-names},
26140
068f7ad41d40 Describe new functions and variables for locales.
Paul Eggert <eggert@twinsun.com>
parents: 25829
diff changeset
422 @code{locale-charset-language-names}, and
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
423 @code{locale-preferred-coding-systems}, to select a default language
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
424 environment and coding system. @xref{Language Environments}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
425 @item LOGNAME
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
426 The user's login name. See also @env{USER}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
427 @item MAIL
Dave Love <fx@gnu.org>
parents:
diff changeset
428 The name of the user's system mail inbox.
Dave Love <fx@gnu.org>
parents:
diff changeset
429 @item MAILRC
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
430 Name of file containing mail aliases. (The default is
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
431 @file{~/.mailrc}.)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
432 @item MH
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
433 Name of setup file for the mh system. (The default is @file{~/.mh_profile}.)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
434 @item NAME
Dave Love <fx@gnu.org>
parents:
diff changeset
435 The real-world name of the user.
Dave Love <fx@gnu.org>
parents:
diff changeset
436 @item NNTPSERVER
36293
1bca8e306103 (General Variables): Remove description of
Gerd Moellmann <gerd@gnu.org>
parents: 36186
diff changeset
437 The name of the news server. Used by the mh and Gnus packages.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
438 @item ORGANIZATION
Dave Love <fx@gnu.org>
parents:
diff changeset
439 The name of the organization to which you belong. Used for setting the
36293
1bca8e306103 (General Variables): Remove description of
Gerd Moellmann <gerd@gnu.org>
parents: 36186
diff changeset
440 `Organization:' header in your posts from the Gnus package.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
441 @item PATH
36364
fca71f0d9dc4 (General Variables): Add a footnote that all *PATH variables use
Eli Zaretskii <eliz@gnu.org>
parents: 36363
diff changeset
442 A colon-separated list of directories in which executables reside. This
fca71f0d9dc4 (General Variables): Add a footnote that all *PATH variables use
Eli Zaretskii <eliz@gnu.org>
parents: 36363
diff changeset
443 is used to initialize the Emacs Lisp variable @code{exec-path}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
444 @item PWD
Dave Love <fx@gnu.org>
parents:
diff changeset
445 If set, this should be the default directory when Emacs was started.
Dave Love <fx@gnu.org>
parents:
diff changeset
446 @item REPLYTO
Dave Love <fx@gnu.org>
parents:
diff changeset
447 If set, this specifies an initial value for the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
448 @code{mail-default-reply-to}. @xref{Mail Headers}.
Dave Love <fx@gnu.org>
parents:
diff changeset
449 @item SAVEDIR
Dave Love <fx@gnu.org>
parents:
diff changeset
450 The name of a directory in which news articles are saved by default.
36293
1bca8e306103 (General Variables): Remove description of
Gerd Moellmann <gerd@gnu.org>
parents: 36186
diff changeset
451 Used by the Gnus package.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
452 @item SHELL
Dave Love <fx@gnu.org>
parents:
diff changeset
453 The name of an interpreter used to parse and execute programs run from
Dave Love <fx@gnu.org>
parents:
diff changeset
454 inside Emacs.
33017
4c7241b226fc Document that if $TERM says we are on xterm, the default background
Eli Zaretskii <eliz@gnu.org>
parents: 33012
diff changeset
455 @cindex background mode, on @code{xterm}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
456 @item TERM
38745
5464ee1ba8e2 Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38669
diff changeset
457 The type of the terminal that Emacs is using. This variable must be
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
458 set unless Emacs is run in batch mode. On MS-DOS, it defaults to
Dave Love <fx@gnu.org>
parents:
diff changeset
459 @samp{internal}, which specifies a built-in terminal emulation that
33017
4c7241b226fc Document that if $TERM says we are on xterm, the default background
Eli Zaretskii <eliz@gnu.org>
parents: 33012
diff changeset
460 handles the machine's own display. If the value of @env{TERM} indicates
4c7241b226fc Document that if $TERM says we are on xterm, the default background
Eli Zaretskii <eliz@gnu.org>
parents: 33012
diff changeset
461 that Emacs runs in non-windowed mode from @code{xterm} or a similar
4c7241b226fc Document that if $TERM says we are on xterm, the default background
Eli Zaretskii <eliz@gnu.org>
parents: 33012
diff changeset
462 terminal emulator, the background mode defaults to @samp{light}, and
4c7241b226fc Document that if $TERM says we are on xterm, the default background
Eli Zaretskii <eliz@gnu.org>
parents: 33012
diff changeset
463 Emacs will choose colors that are appropriate for a light background.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
464 @item TERMCAP
Dave Love <fx@gnu.org>
parents:
diff changeset
465 The name of the termcap library file describing how to program the
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
466 terminal specified by the @env{TERM} variable. This defaults to
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
467 @file{/etc/termcap}.
Dave Love <fx@gnu.org>
parents:
diff changeset
468 @item TMPDIR
Dave Love <fx@gnu.org>
parents:
diff changeset
469 Used by the Emerge package as a prefix for temporary files.
Dave Love <fx@gnu.org>
parents:
diff changeset
470 @item TZ
36186
e391cbe3a2fe Correction for TZ on Microsoft systems.
Richard M. Stallman <rms@gnu.org>
parents: 36146
diff changeset
471 This specifies the current time zone and possibly also daylight
36617
756d21b874ec (General Variables): "daylight savings" -> "daylight saving".
Eli Zaretskii <eliz@gnu.org>
parents: 36544
diff changeset
472 saving time information. On MS-DOS, if @code{TZ} is not set in the
36186
e391cbe3a2fe Correction for TZ on Microsoft systems.
Richard M. Stallman <rms@gnu.org>
parents: 36146
diff changeset
473 environment when Emacs starts, Emacs defines a default value as
36502
3f0def4a4210 Minor cleanups. Rename `Motif Resources' node to `LessTif Resources'.
Richard M. Stallman <rms@gnu.org>
parents: 36500
diff changeset
474 appropriate for the country code returned by DOS. On MS-Windows, Emacs
36186
e391cbe3a2fe Correction for TZ on Microsoft systems.
Richard M. Stallman <rms@gnu.org>
parents: 36146
diff changeset
475 does not use @code{TZ} at all.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
476 @item USER
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
477 The user's login name. See also @env{LOGNAME}. On MS-DOS, this
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
478 defaults to @samp{root}.
Dave Love <fx@gnu.org>
parents:
diff changeset
479 @item VERSION_CONTROL
Dave Love <fx@gnu.org>
parents:
diff changeset
480 Used to initialize the @code{version-control} variable (@pxref{Backup
Dave Love <fx@gnu.org>
parents:
diff changeset
481 Names}).
Dave Love <fx@gnu.org>
parents:
diff changeset
482 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
483
Dave Love <fx@gnu.org>
parents:
diff changeset
484 @node Misc Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
485 @appendixsubsec Miscellaneous Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
486
Dave Love <fx@gnu.org>
parents:
diff changeset
487 These variables are used only on particular configurations:
Dave Love <fx@gnu.org>
parents:
diff changeset
488
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
489 @table @env
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
490 @item COMSPEC
36500
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
491 On MS-DOS and MS-Windows, the name of the command interpreter to use
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
492 when invoking batch files and commands internal to the shell. On MS-DOS
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
493 this is also used to make a default value for the @env{SHELL} environment
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
494 variable.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
495
Dave Love <fx@gnu.org>
parents:
diff changeset
496 @item NAME
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
497 On MS-DOS, this variable defaults to the value of the @env{USER}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
498 variable.
Dave Love <fx@gnu.org>
parents:
diff changeset
499
Dave Love <fx@gnu.org>
parents:
diff changeset
500 @item TEMP
Dave Love <fx@gnu.org>
parents:
diff changeset
501 @itemx TMP
36500
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
502 On MS-DOS and MS-Windows, these specify the name of the directory for
3dfa039c6a8c Many typo-fixes and clarifications from Dr Francis J. Wright
Eli Zaretskii <eliz@gnu.org>
parents: 36364
diff changeset
503 storing temporary files in.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
504
Dave Love <fx@gnu.org>
parents:
diff changeset
505 @item EMACSTEST
Dave Love <fx@gnu.org>
parents:
diff changeset
506 On MS-DOS, this specifies a file to use to log the operation of the
Dave Love <fx@gnu.org>
parents:
diff changeset
507 internal terminal emulator. This feature is useful for submitting bug
Dave Love <fx@gnu.org>
parents:
diff changeset
508 reports.
Dave Love <fx@gnu.org>
parents:
diff changeset
509
Dave Love <fx@gnu.org>
parents:
diff changeset
510 @item EMACSCOLORS
36502
3f0def4a4210 Minor cleanups. Rename `Motif Resources' node to `LessTif Resources'.
Richard M. Stallman <rms@gnu.org>
parents: 36500
diff changeset
511 On MS-DOS, this specifies the screen colors. It is useful to set them
3f0def4a4210 Minor cleanups. Rename `Motif Resources' node to `LessTif Resources'.
Richard M. Stallman <rms@gnu.org>
parents: 36500
diff changeset
512 this way, since otherwise Emacs would display the default colors
3f0def4a4210 Minor cleanups. Rename `Motif Resources' node to `LessTif Resources'.
Richard M. Stallman <rms@gnu.org>
parents: 36500
diff changeset
513 momentarily when it starts up.
3f0def4a4210 Minor cleanups. Rename `Motif Resources' node to `LessTif Resources'.
Richard M. Stallman <rms@gnu.org>
parents: 36500
diff changeset
514
3f0def4a4210 Minor cleanups. Rename `Motif Resources' node to `LessTif Resources'.
Richard M. Stallman <rms@gnu.org>
parents: 36500
diff changeset
515 The value of this variable should be the two-character encoding of the
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
516 foreground (the first character) and the background (the second
Dave Love <fx@gnu.org>
parents:
diff changeset
517 character) colors of the default face. Each character should be the
Dave Love <fx@gnu.org>
parents:
diff changeset
518 hexadecimal code for the desired color on a standard PC text-mode
39267
a8c0a02f6129 Spelling corrections.
Richard M. Stallman <rms@gnu.org>
parents: 39074
diff changeset
519 display. For example, to get blue text on a light gray background,
36505
a7400c1ee57f (Misc Variables): Add example for setting EMACSCOLORS on MS-DOS.
Eli Zaretskii <eliz@gnu.org>
parents: 36502
diff changeset
520 specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and
39267
a8c0a02f6129 Spelling corrections.
Richard M. Stallman <rms@gnu.org>
parents: 39074
diff changeset
521 7 is the code of the light gray color.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
522
Dave Love <fx@gnu.org>
parents:
diff changeset
523 The PC display usually supports only eight background colors. However,
Dave Love <fx@gnu.org>
parents:
diff changeset
524 Emacs switches the DOS display to a mode where all 16 colors can be used
Dave Love <fx@gnu.org>
parents:
diff changeset
525 for the background, so all four bits of the background color are
Dave Love <fx@gnu.org>
parents:
diff changeset
526 actually used.
Dave Love <fx@gnu.org>
parents:
diff changeset
527
Dave Love <fx@gnu.org>
parents:
diff changeset
528 @item WINDOW_GFX
Dave Love <fx@gnu.org>
parents:
diff changeset
529 Used when initializing the Sun windows system.
Dave Love <fx@gnu.org>
parents:
diff changeset
530 @end table