Fix wording in TUTORIAL.ru. Suggested by Igor Potseluev <4eppelin@gmail.com>.
[bpt/emacs.git] / doc / emacs / cmdargs.texi
CommitLineData
8cf51b2c 1@c This is part of the Emacs manual.
acaf905b 2@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012
73b0cd50 3@c Free Software Foundation, Inc.
8cf51b2c 4@c See file emacs.texi for copying conditions.
abb9615e 5@node Emacs Invocation
8cf51b2c
GM
6@appendix Command Line Arguments for Emacs Invocation
7@cindex command line arguments
8@cindex arguments (command line)
9@cindex options (command line)
10@cindex switches (command line)
11@cindex startup (command line arguments)
12@cindex invocation (command line arguments)
13
63961e6a
CY
14 Emacs supports command line arguments to request various actions
15when invoking Emacs. These are for compatibility with other editors
16and for sophisticated activities. We don't recommend using them for
17ordinary editing (@xref{Emacs Server}, for a way to access an existing
18Emacs job from the command line).
8cf51b2c
GM
19
20 Arguments starting with @samp{-} are @dfn{options}, and so is
21@samp{+@var{linenum}}. All other arguments specify files to visit.
22Emacs visits the specified files while it starts up. The last file
63961e6a
CY
23specified on the command line becomes the current buffer; the other
24files are also visited in other buffers. As with most programs, the
25special argument @samp{--} says that all subsequent arguments are file
26names, not options, even if they start with @samp{-}.
8cf51b2c
GM
27
28 Emacs command options can specify many things, such as the size and
29position of the X window Emacs uses, its colors, and so on. A few
30options support advanced usage, such as running Lisp functions on files
31in batch mode. The sections of this chapter describe the available
32options, arranged according to their purpose.
33
34 There are two ways of writing options: the short forms that start with
35a single @samp{-}, and the long forms that start with @samp{--}. For
36example, @samp{-d} is a short form and @samp{--display} is the
37corresponding long form.
38
39 The long forms with @samp{--} are easier to remember, but longer to
40type. However, you don't have to spell out the whole option name; any
41unambiguous abbreviation is enough. When a long option takes an
42argument, you can use either a space or an equal sign to separate the
43option name and the argument. Thus, you can write either
44@samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}.
45We recommend an equal sign because it makes the relationship clearer,
46and the tables below always show an equal sign.
47
48@cindex initial options (command line)
49@cindex action options (command line)
50@vindex command-line-args
51 Most options specify how to initialize Emacs, or set parameters for
52the Emacs session. We call them @dfn{initial options}. A few options
63961e6a
CY
53specify things to do, such as loading libraries or calling Lisp
54functions. These are called @dfn{action options}. These and file
55names together are called @dfn{action arguments}. The action
56arguments are stored as a list of strings in the variable
57@code{command-line-args}. (Actually, when Emacs starts up,
58@code{command-line-args} contains all the arguments passed from the
59command line; during initialization, the initial arguments are removed
60from this list when they are processed, leaving only the action
61arguments.)
8cf51b2c
GM
62
63@menu
64* Action Arguments:: Arguments to visit files, load libraries,
65 and call functions.
66* Initial Options:: Arguments that take effect while starting Emacs.
67* Command Example:: Examples of using command line arguments.
8cf51b2c
GM
68* Environment:: Environment variables that Emacs uses.
69* Display X:: Changing the default display and using remote login.
70* Font X:: Choosing a font for text, under X.
8863a584 71* Colors X:: Choosing display colors.
8cf51b2c
GM
72* Window Size X:: Start-up window size, under X.
73* Borders X:: Internal and external borders, under X.
74* Title X:: Specifying the initial frame's title.
75* Icons X:: Choosing what sort of icon to use, under X.
76* Misc X:: Other display options.
77@end menu
78
79@node Action Arguments
80@appendixsec Action Arguments
81
63961e6a 82 Here is a table of action arguments:
8cf51b2c
GM
83
84@table @samp
85@item @var{file}
86@opindex --file
87@itemx --file=@var{file}
88@opindex --find-file
89@itemx --find-file=@var{file}
90@opindex --visit
91@itemx --visit=@var{file}
92@cindex visiting files, command-line argument
93@vindex inhibit-startup-buffer-menu
94Visit @var{file} using @code{find-file}. @xref{Visiting}.
63961e6a
CY
95
96When Emacs starts up, it displays the startup buffer in one window,
97and the buffer visiting @var{file} in another window
98(@pxref{Windows}). If you supply more than one file argument, the
99displayed file is the last one specified on the command line; the
100other files are visited but their buffers are not shown.
101
102If the startup buffer is disabled (@pxref{Entering Emacs}), then
103@var{file} is visited in a single window if one file argument was
104supplied; with two file arguments, Emacs displays the files in two
105different windows; with more than two file argument, Emacs displays
106the last file specified in one window, plus a Buffer Menu in a
107different window (@pxref{Several Buffers}). To inhibit using the
108Buffer Menu for this, change the variable
109@code{inhibit-startup-buffer-menu} to @code{t}.
8cf51b2c
GM
110
111@item +@var{linenum} @var{file}
112@opindex +@var{linenum}
113Visit @var{file} using @code{find-file}, then go to line number
114@var{linenum} in it.
115
116@item +@var{linenum}:@var{columnnum} @var{file}
117Visit @var{file} using @code{find-file}, then go to line number
118@var{linenum} and put point at column number @var{columnnum}.
119
8cf51b2c
GM
120@item -l @var{file}
121@opindex -l
122@itemx --load=@var{file}
123@opindex --load
124@cindex loading Lisp libraries, command-line argument
125Load a Lisp library named @var{file} with the function @code{load}.
a73a3461
CY
126If @var{file} is not an absolute file name, Emacs first looks for it
127in the current directory, then in the directories listed in
128@code{load-path} (@pxref{Lisp Libraries}).
8cf51b2c
GM
129
130@strong{Warning:} If previous command-line arguments have visited
131files, the current directory is the directory of the last file
132visited.
133
134@item -L @var{dir}
135@opindex -L
136@itemx --directory=@var{dir}
137@opindex --directory
138Add directory @var{dir} to the variable @code{load-path}.
139
140@item -f @var{function}
141@opindex -f
142@itemx --funcall=@var{function}
143@opindex --funcall
144@cindex call Lisp functions, command-line argument
145Call Lisp function @var{function}. If it is an interactive function
146(a command), it reads the arguments interactively just as if you had
147called the same function with a key sequence. Otherwise, it calls the
148function with no arguments.
149
150@item --eval=@var{expression}
151@opindex --eval
152@itemx --execute=@var{expression}
153@opindex --execute
154@cindex evaluate expression, command-line argument
155Evaluate Lisp expression @var{expression}.
156
157@item --insert=@var{file}
158@opindex --insert
159@cindex insert file contents, command-line argument
1c64e6ed 160Insert the contents of @var{file} into the @file{*scratch*} buffer
63961e6a
CY
161(@pxref{Lisp Interaction}). This is like what @kbd{M-x insert-file}
162does (@pxref{Misc File Ops}).
8cf51b2c
GM
163
164@item --kill
165@opindex --kill
166Exit from Emacs without asking for confirmation.
167
168@item --help
169@opindex --help
170Print a usage message listing all available options, then exit
171successfully.
172
173@item --version
174@opindex --version
175Print Emacs version, then exit successfully.
176@end table
177
178@node Initial Options
179@appendixsec Initial Options
180
181 The initial options specify parameters for the Emacs session. This
182section describes the more general initial options; some other options
183specifically related to the X Window System appear in the following
184sections.
185
63961e6a 186 Some initial options affect the loading of the initialization file.
a73a3461
CY
187Normally, Emacs first loads @file{site-start.el} if it exists, then
188your own initialization file if it exists, and finally the default
189initialization file @file{default.el} if it exists (@pxref{Init
190File}). Certain options prevent loading of some of these files or
191substitute other files for them.
8cf51b2c
GM
192
193@table @samp
f63d0028
JD
194@item -chdir @var{directory}
195@opindex -chdir
196@itemx --chdir=@var{directory}
197@opindex --chdir
198@cindex change Emacs directory
199Change to @var{directory} before doing anything else. This is mainly used
200by session management in X so that Emacs starts in the same directory as it
201stopped. This makes desktop saving and restoring easier.
202
8cf51b2c
GM
203@item -t @var{device}
204@opindex -t
205@itemx --terminal=@var{device}
206@opindex --terminal
207@cindex device for Emacs terminal I/O
a73a3461
CY
208Use @var{device} as the device for terminal input and output. This
209option implies @samp{--no-window-system}.
8cf51b2c
GM
210
211@item -d @var{display}
212@opindex -d
213@itemx --display=@var{display}
214@opindex --display
215@cindex display for Emacs frame
216Use the X Window System and use the display named @var{display} to open
217the initial Emacs frame. @xref{Display X}, for more details.
218
219@item -nw
220@opindex -nw
221@itemx --no-window-system
222@opindex --no-window-system
223@cindex disable window system
224Don't communicate directly with the window system, disregarding the
225@env{DISPLAY} environment variable even if it is set. This means that
226Emacs uses the terminal from which it was launched for all its display
227and input.
228
8cf51b2c
GM
229@cindex batch mode
230@item -batch
231@opindex --batch
232@itemx --batch
233Run Emacs in @dfn{batch mode}. Batch mode is used for running
234programs written in Emacs Lisp from shell scripts, makefiles, and so
63961e6a
CY
235on. To invoke a Lisp program, use the @samp{-batch} option in
236conjunction with one or more of @samp{-l}, @samp{-f} or @samp{--eval}
237(@pxref{Action Arguments}). @xref{Command Example}, for an example.
8cf51b2c
GM
238
239In batch mode, Emacs does not display the text being edited, and the
240standard terminal interrupt characters such as @kbd{C-z} and @kbd{C-c}
63961e6a
CY
241have their usual effect. Emacs functions that normally print a
242message in the echo area will print to either the standard output
243stream (@code{stdout}) or the standard error stream (@code{stderr})
244instead. (To be precise, functions like @code{prin1}, @code{princ}
245and @code{print} print to @code{stdout}, while @code{message} and
246@code{error} print to @code{stderr}.) Functions that normally read
247keyboard input from the minibuffer take their input from the
248terminal's standard input stream (@code{stdin}) instead.
249
250@samp{--batch} implies @samp{-q} (do not load an initialization file),
251but @file{site-start.el} is loaded nonetheless. It also causes Emacs
252to exit after processing all the command options. In addition, it
a73a3461 253disables auto-saving except in buffers for which auto-saving is
8cf51b2c
GM
254explicitly requested.
255
256@item --script @var{file}
257@opindex --script
258@cindex script mode
259Run Emacs in batch mode, like @samp{--batch}, and then read and
260execute the Lisp code in @var{file}.
261
262The normal use of this option is in executable script files that run
263Emacs. They can start with this text on the first line
264
265@example
266#!/usr/bin/emacs --script
267@end example
268
269@noindent
270which will invoke Emacs with @samp{--script} and supply the name of
a73a3461
CY
271the script file as @var{file}. Emacs Lisp then treats the @samp{#!}
272on this first line as a comment delimiter.
8cf51b2c
GM
273
274@item -q
275@opindex -q
276@itemx --no-init-file
277@opindex --no-init-file
278@cindex bypassing init and @file{default.el} file
279@cindex init file, not loading
280@cindex @file{default.el} file, not loading
a73a3461
CY
281Do not load any initialization file (@pxref{Init File}). When Emacs
282is invoked with this option, the Customize facility does not allow
283options to be saved (@pxref{Easy Customization}). This option does
284not disable loading @file{site-start.el}.
8cf51b2c
GM
285
286@item --no-site-file
287@opindex --no-site-file
288@cindex @file{site-start.el} file, not loading
fdeb32ec
CY
289Do not load @file{site-start.el} (@pxref{Init File}). The @samp{-Q}
290option does this too, but other options like @samp{-q} do not.
291
292@item --no-site-lisp
293@opindex --no-site-lisp
294@cindex @file{site-start.el} file, not loading
295Do not include the @file{site-lisp} directories in @code{load-path}
296(@pxref{Init File}). The @samp{-Q} option does this too.
8cf51b2c 297
63961e6a
CY
298@item --no-splash
299@opindex --no-splash
300@vindex inhibit-startup-screen
301@cindex splash screen
302@cindex startup message
303Do not display a startup screen. You can also achieve this effect by
304setting the variable @code{inhibit-startup-screen} to non-@code{nil}
305in your initialization file (@pxref{Entering Emacs}).
306
8cf51b2c
GM
307@item -Q
308@opindex -Q
309@itemx --quick
310@opindex --quick
9eb25ee8 311Start emacs with minimum customizations. This is similar to using @samp{-q},
fdeb32ec
CY
312@samp{--no-site-file}, @samp{--no-site-lisp}, and @samp{--no-splash}
313together. This also stops Emacs from processing X resources by
314setting @code{inhibit-x-resources} to @code{t} (@pxref{Resources}).
8cf51b2c 315
eab2ee89
DN
316@item -daemon
317@opindex -daemon
318@itemx --daemon
319@opindex --daemon
63961e6a
CY
320Start Emacs as a daemon---after Emacs starts up, it starts the Emacs
321server and disconnects from the terminal without opening any frames.
322You can then use the @command{emacsclient} command to connect to Emacs
323for editing. @xref{Emacs Server}, for information about using Emacs
324as a daemon.
eab2ee89 325
4ff029f6 326@item -daemon=@var{SERVER-NAME}
63961e6a
CY
327Start emacs in background as a daemon, and use @var{SERVER-NAME} as
328the server name.
8cf51b2c
GM
329
330@item --no-desktop
331@opindex --no-desktop
332Do not reload any saved desktop. @xref{Saving Emacs Sessions}.
333
334@item -u @var{user}
335@opindex -u
336@itemx --user=@var{user}
337@opindex --user
338@cindex load init file of another user
63961e6a
CY
339Load @var{user}'s initialization file instead of your
340own@footnote{This option has no effect on MS-Windows.}.
8cf51b2c
GM
341
342@item --debug-init
343@opindex --debug-init
344@cindex errors in init file
345Enable the Emacs Lisp debugger for errors in the init file.
346@xref{Error Debugging,, Entering the Debugger on an Error, elisp, The
347GNU Emacs Lisp Reference Manual}.
76a87a4d 348@end table
8cf51b2c 349
8cf51b2c
GM
350@node Command Example
351@appendixsec Command Argument Example
352
353 Here is an example of using Emacs with arguments and options. It
354assumes you have a Lisp program file called @file{hack-c.el} which, when
355loaded, performs some useful operation on the current buffer, expected
356to be a C program.
357
358@example
359emacs --batch foo.c -l hack-c -f save-buffer >& log
360@end example
361
362@noindent
363This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
364changes in the visited file), save @file{foo.c} (note that
365@code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
366then exit back to the shell (because of @samp{--batch}). @samp{--batch}
367also guarantees there will be no problem redirecting output to
368@file{log}, because Emacs will not assume that it has a display terminal
369to work with.
370
8cf51b2c
GM
371@node Environment
372@appendixsec Environment Variables
373@cindex environment variables
374
375 The @dfn{environment} is a feature of the operating system; it
376consists of a collection of variables with names and values. Each
377variable is called an @dfn{environment variable}; environment variable
378names are case-sensitive, and it is conventional to use upper case
379letters only. The values are all text strings.
380
381 What makes the environment useful is that subprocesses inherit the
382environment automatically from their parent process. This means you
383can set up an environment variable in your login shell, and all the
384programs you run (including Emacs) will automatically see it.
a73a3461
CY
385Subprocesses of Emacs (such as shells, compilers, and version control
386programs) inherit the environment from Emacs, too.
8cf51b2c
GM
387
388@findex setenv
389@findex getenv
63961e6a 390@vindex initial-environment
a73a3461
CY
391 Inside Emacs, the command @kbd{M-x getenv} reads the name of an
392environment variable, and prints its value in the echo area. @kbd{M-x
393setenv} sets a variable in the Emacs environment, and @kbd{C-u M-x
394setenv} removes a variable. (Environment variable substitutions with
395@samp{$} work in the value just as in file names; see @ref{File Names
396with $}.) The variable @code{initial-environment} stores the initial
397environment inherited by Emacs.
8cf51b2c
GM
398
399 The way to set environment variables outside of Emacs depends on the
400operating system, and especially the shell that you are using. For
401example, here's how to set the environment variable @env{ORGANIZATION}
402to @samp{not very much} using Bash:
403
404@example
405export ORGANIZATION="not very much"
406@end example
407
408@noindent
409and here's how to do it in csh or tcsh:
410
411@example
412setenv ORGANIZATION "not very much"
413@end example
414
415 When Emacs is using the X Window System, various environment
416variables that control X work for Emacs as well. See the X
417documentation for more information.
418
419@menu
420* General Variables:: Environment variables that all versions of Emacs use.
421* Misc Variables:: Certain system-specific variables.
422* MS-Windows Registry:: An alternative to the environment on MS-Windows.
423@end menu
424
425@node General Variables
426@appendixsubsec General Variables
427
63961e6a
CY
428 Here is an alphabetical list of environment variables that have
429special meanings in Emacs. Most of these variables are also used by
430some other programs. Emacs does not require any of these environment
431variables to be set, but it uses their values if they are set.
8cf51b2c
GM
432
433@table @env
434@item CDPATH
435Used by the @code{cd} command to search for the directory you specify,
436when you specify a relative directory name.
aa0ecd94
MA
437@item DBUS_SESSION_BUS_ADDRESS
438Used by D-Bus when Emacs is compiled with it. Usually, there is no
439need to change it. Setting it to a dummy address, like
440@samp{unix:path=/tmp/foo}, suppresses connections to the D-Bus session
441bus.
8cf51b2c
GM
442@item EMACSDATA
443Directory for the architecture-independent files that come with Emacs.
166bc0c8 444This is used to initialize the variable @code{data-directory}.
8cf51b2c 445@item EMACSDOC
ae742cb5
CY
446Directory for the documentation string file, which is used to
447initialize the Lisp variable @code{doc-directory}.
8cf51b2c 448@item EMACSLOADPATH
a73a3461 449A colon-separated list of directories@footnote{ Here and below,
16152b76 450whenever we say ``colon-separated list of directories'', it pertains
a73a3461
CY
451to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, the
452directories are separated by semi-colons instead, since DOS/Windows
453file names might include a colon after a drive letter.} to search for
454Emacs Lisp files. If set, it overrides the usual initial value of the
455@code{load-path} variable (@pxref{Lisp Libraries}).
8cf51b2c 456@item EMACSPATH
a73a3461
CY
457A colon-separated list of directories to search for executable files.
458If set, Emacs uses this in addition to @env{PATH} (see below) when
459initializing the variable @code{exec-path} (@pxref{Shell}).
8cf51b2c
GM
460@item EMAIL
461@vindex user-mail-address@r{, initialization}
462Your email address; used to initialize the Lisp variable
a73a3461
CY
463@code{user-mail-address}, which the Emacs mail interface puts into the
464@samp{From} header of outgoing messages (@pxref{Mail Headers}).
8cf51b2c 465@item ESHELL
a73a3461
CY
466Used for shell-mode to override the @env{SHELL} environment variable
467(@pxref{Interactive Shell}).
8cf51b2c
GM
468@item HISTFILE
469The name of the file that shell commands are saved in between logins.
470This variable defaults to @file{~/.bash_history} if you use Bash, to
471@file{~/.sh_history} if you use ksh, and to @file{~/.history}
472otherwise.
473@item HOME
474The location of your files in the directory tree; used for
475expansion of file names starting with a tilde (@file{~}). On MS-DOS,
476it defaults to the directory from which Emacs was started, with
477@samp{/bin} removed from the end if it was present. On Windows, the
478default value of @env{HOME} is the @file{Application Data}
479subdirectory of the user profile directory (normally, this is
480@file{C:/Documents and Settings/@var{username}/Application Data},
481where @var{username} is your user name), though for backwards
482compatibility @file{C:/} will be used instead if a @file{.emacs} file
483is found there.
484@item HOSTNAME
485The name of the machine that Emacs is running on.
486@item INCPATH
487A colon-separated list of directories. Used by the @code{complete} package
488to search for files.
489@item INFOPATH
490A colon-separated list of directories in which to search for Info files.
491@item LC_ALL
492@itemx LC_COLLATE
493@itemx LC_CTYPE
494@itemx LC_MESSAGES
495@itemx LC_MONETARY
496@itemx LC_NUMERIC
497@itemx LC_TIME
498@itemx LANG
499The user's preferred locale. The locale has six categories, specified
500by the environment variables @env{LC_COLLATE} for sorting,
501@env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system
502messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for
503numbers, and @env{LC_TIME} for dates and times. If one of these
504variables is not set, the category defaults to the value of the
505@env{LANG} environment variable, or to the default @samp{C} locale if
506@env{LANG} is not set. But if @env{LC_ALL} is specified, it overrides
507the settings of all the other locale environment variables.
508
509On MS-Windows, if @env{LANG} is not already set in the environment
510when Emacs starts, Emacs sets it based on the system-wide default
511language, which you can set in the @samp{Regional Settings} Control Panel
512on some versions of MS-Windows.
513
514The value of the @env{LC_CTYPE} category is
515matched against entries in @code{locale-language-names},
516@code{locale-charset-language-names}, and
517@code{locale-preferred-coding-systems}, to select a default language
518environment and coding system. @xref{Language Environments}.
519@item LOGNAME
520The user's login name. See also @env{USER}.
521@item MAIL
522The name of your system mail inbox.
a73a3461 523@ifnottex
8cf51b2c 524@item MH
a73a3461
CY
525Name of setup file for the mh system. @xref{Top,,MH-E,mh-e, The Emacs
526Interface to MH}.
527@end ifnottex
8cf51b2c 528@item NAME
a73a3461
CY
529Your real-world name. This is used to initialize the variable
530@code{user-full-name} (@pxref{Mail Headers}).
8cf51b2c
GM
531@item NNTPSERVER
532The name of the news server. Used by the mh and Gnus packages.
533@item ORGANIZATION
534The name of the organization to which you belong. Used for setting the
535`Organization:' header in your posts from the Gnus package.
536@item PATH
a73a3461
CY
537A colon-separated list of directories containing executable files.
538This is used to initialize the variable @code{exec-path}
539(@pxref{Shell}).
8cf51b2c
GM
540@item PWD
541If set, this should be the default directory when Emacs was started.
542@item REPLYTO
543If set, this specifies an initial value for the variable
a73a3461 544@code{mail-default-reply-to} (@pxref{Mail Headers}).
8cf51b2c
GM
545@item SAVEDIR
546The name of a directory in which news articles are saved by default.
547Used by the Gnus package.
548@item SHELL
549The name of an interpreter used to parse and execute programs run from
550inside Emacs.
551@item SMTPSERVER
a73a3461
CY
552The name of the outgoing mail server. This is used to initialize the
553variable @code{smtpmail-smtp-server} (@pxref{Mail Sending}).
8cf51b2c
GM
554@cindex background mode, on @command{xterm}
555@item TERM
556The type of the terminal that Emacs is using. This variable must be
557set unless Emacs is run in batch mode. On MS-DOS, it defaults to
558@samp{internal}, which specifies a built-in terminal emulation that
a73a3461 559handles the machine's own display.
8cf51b2c
GM
560@item TERMCAP
561The name of the termcap library file describing how to program the
a73a3461 562terminal specified by @env{TERM}. This defaults to
8cf51b2c
GM
563@file{/etc/termcap}.
564@item TMPDIR
a73a3461
CY
565@itemx TMP
566@itemx TEMP
567These environment variables are used to initialize the variable
568@code{temporary-file-directory}, which specifies a directory in which
569to put temporary files (@pxref{Backup}). Emacs tries to use
570@env{TMPDIR} first; if that is unset, it tries @env{TMP}, then
571@env{TEMP}, and finally @file{/tmp}. But on MS-Windows and MS-DOS,
572Emacs tries @env{TEMP}, then @env{TMPDIR}, then @env{TMP}, and finally
573@file{c:/temp}.
574
8cf51b2c
GM
575@item TZ
576This specifies the current time zone and possibly also daylight
577saving time information. On MS-DOS, if @env{TZ} is not set in the
578environment when Emacs starts, Emacs defines a default value as
579appropriate for the country code returned by DOS. On MS-Windows, Emacs
580does not use @env{TZ} at all.
581@item USER
582The user's login name. See also @env{LOGNAME}. On MS-DOS, this
583defaults to @samp{root}.
584@item VERSION_CONTROL
84f4a531
CY
585Used to initialize the @code{version-control} variable (@pxref{Backup
586Names}).
8cf51b2c
GM
587@end table
588
589@node Misc Variables
590@appendixsubsec Miscellaneous Variables
591
592These variables are used only on particular configurations:
593
594@table @env
595@item COMSPEC
596On MS-DOS and MS-Windows, the name of the command interpreter to use
597when invoking batch files and commands internal to the shell. On MS-DOS
598this is also used to make a default value for the @env{SHELL} environment
599variable.
600
601@item NAME
602On MS-DOS, this variable defaults to the value of the @env{USER}
603variable.
604
8cf51b2c
GM
605@item EMACSTEST
606On MS-DOS, this specifies a file to use to log the operation of the
607internal terminal emulator. This feature is useful for submitting bug
608reports.
609
610@item EMACSCOLORS
611On MS-DOS, this specifies the screen colors. It is useful to set them
612this way, since otherwise Emacs would display the default colors
613momentarily when it starts up.
614
615The value of this variable should be the two-character encoding of the
616foreground (the first character) and the background (the second
617character) colors of the default face. Each character should be the
618hexadecimal code for the desired color on a standard PC text-mode
619display. For example, to get blue text on a light gray background,
620specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and
6217 is the code of the light gray color.
622
623The PC display usually supports only eight background colors. However,
624Emacs switches the DOS display to a mode where all 16 colors can be used
625for the background, so all four bits of the background color are
626actually used.
627
8cf51b2c
GM
628@item PRELOAD_WINSOCK
629On MS-Windows, if you set this variable, Emacs will load and initialize
630the network library at startup, instead of waiting until the first
631time it is required.
632
633@item emacs_dir
634On MS-Windows, @env{emacs_dir} is a special environment variable, which
635indicates the full path of the directory in which Emacs is installed.
636If Emacs is installed in the standard directory structure, it
637calculates this value automatically. It is not much use setting this
638variable yourself unless your installation is non-standard, since
639unlike other environment variables, it will be overridden by Emacs at
640startup. When setting other environment variables, such as
641@env{EMACSLOADPATH}, you may find it useful to use @env{emacs_dir}
642rather than hard-coding an absolute path. This allows multiple
643versions of Emacs to share the same environment variable settings, and
644it allows you to move the Emacs installation directory, without
645changing any environment or registry settings.
646@end table
647
648@node MS-Windows Registry
649@appendixsubsec The MS-Windows System Registry
650@pindex addpm, MS-Windows installation program
8034735f 651@cindex registry, setting environment variables (MS-Windows)
8cf51b2c 652
8034735f 653On MS-Windows, the installation program @command{addpm.exe} adds
8cf51b2c
GM
654values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA},
655@env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the
656@file{HKEY_LOCAL_MACHINE} section of the system registry, under
657@file{/Software/GNU/Emacs}. It does this because there is no standard
658place to set environment variables across different versions of
659Windows. Running @command{addpm.exe} is no longer strictly necessary
660in recent versions of Emacs, but if you are upgrading from an older
661version, running @command{addpm.exe} ensures that you do not have
662older registry entries from a previous installation, which may not be
663compatible with the latest version of Emacs.
664
665When Emacs starts, as well as checking the environment, it also checks
666the System Registry for those variables and for @env{HOME}, @env{LANG}
667and @env{PRELOAD_WINSOCK}.
668
669To determine the value of those variables, Emacs goes through the
670following procedure. First, the environment is checked. If the
671variable is not found there, Emacs looks for registry keys by that
672name under @file{/Software/GNU/Emacs}; first in the
673@file{HKEY_CURRENT_USER} section of the registry, and if not found
674there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs
675still cannot determine the values, compiled-in defaults are used.
676
677In addition to the environment variables above, you can also add many
678of the settings which on X belong in the @file{.Xdefaults} file
679(@pxref{X Resources}) to the @file{/Software/GNU/Emacs} registry key.
8cf51b2c
GM
680
681@node Display X
682@appendixsec Specifying the Display Name
683@cindex display name (X Window System)
684@cindex @env{DISPLAY} environment variable
685
a73a3461
CY
686 The environment variable @env{DISPLAY} tells all X clients,
687including Emacs, where to display their windows. Its value is set by
688default in ordinary circumstances, when you start an X server and run
689jobs locally. You can specify the display yourself; one reason to do
690this is if you want to log into another system and run Emacs there,
691and have the window displayed at your local terminal.
8cf51b2c 692
ae742cb5 693 @env{DISPLAY} has the syntax
8cf51b2c
GM
694@samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the
695host name of the X Window System server machine, @var{display} is an
ae742cb5
CY
696arbitrarily-assigned number that distinguishes your server (X
697terminal) from other servers on the same machine, and @var{screen} is
a73a3461
CY
698a field that allows an X server to control multiple terminal screens.
699The period and the @var{screen} field are optional. If included,
700@var{screen} is usually zero.
8cf51b2c
GM
701
702 For example, if your host is named @samp{glasperle} and your server is
703the first (or perhaps the only) server listed in the configuration, your
704@env{DISPLAY} is @samp{glasperle:0.0}.
705
706 You can specify the display name explicitly when you run Emacs, either
707by changing the @env{DISPLAY} variable, or with the option @samp{-d
708@var{display}} or @samp{--display=@var{display}}. Here is an example:
709
710@smallexample
711emacs --display=glasperle:0 &
712@end smallexample
713
a73a3461
CY
714 You can inhibit the use of the X window system with the @samp{-nw}
715option. Then Emacs uses its controlling text terminal for display.
716@xref{Initial Options}.
8cf51b2c
GM
717
718 Sometimes, security arrangements prevent a program on a remote system
719from displaying on your local system. In this case, trying to run Emacs
720produces messages like this:
721
722@smallexample
723Xlib: connection to "glasperle:0.0" refused by server
724@end smallexample
725
726@noindent
727You might be able to overcome this problem by using the @command{xhost}
728command on the local system to give permission for access from your
729remote machine.
730
731@node Font X
732@appendixsec Font Specification Options
733@cindex font name (X Window System)
734
d68eb23c
CY
735You can use the command line option @samp{-fn @var{font}} (or
736@samp{--font}, which is an alias for @samp{-fn}) to specify a default
737font:
8cf51b2c
GM
738
739@table @samp
0e3f4049 740@item -fn @var{font}
8cf51b2c 741@opindex -fn
0e3f4049 742@itemx --font=@var{font}
8cf51b2c
GM
743@opindex --font
744@cindex specify default font from the command line
0e3f4049 745Use @var{font} as the default font.
8cf51b2c
GM
746@end table
747
a73a3461
CY
748When passing a font name to Emacs on the command line, you may need to
749``quote'' it, by enclosing it in quotation marks, if it contains
750characters that the shell treats specially (e.g.@: spaces). For
751example:
001b5dc9
CY
752
753@smallexample
754emacs -fn "DejaVu Sans Mono-12"
755@end smallexample
756
a73a3461
CY
757@xref{Fonts}, for details about font names and other ways to specify
758the default font.
8cf51b2c 759
8863a584 760@node Colors X
8cf51b2c
GM
761@appendixsec Window Color Options
762@cindex color of window, from command line
763@cindex text colors, from command line
764
8863a584
CY
765 You can use the following command-line options to specify the colors
766to use for various parts of the Emacs display. Colors may be
767specified using either color names or RGB triplets (@pxref{Colors}).
8cf51b2c
GM
768
769@table @samp
770@item -fg @var{color}
771@opindex -fg
772@itemx --foreground-color=@var{color}
773@opindex --foreground-color
774@cindex foreground color, command-line argument
8863a584
CY
775Specify the foreground color, overriding the color specified by the
776@code{default} face (@pxref{Faces}).
8cf51b2c
GM
777@item -bg @var{color}
778@opindex -bg
779@itemx --background-color=@var{color}
780@opindex --background-color
781@cindex background color, command-line argument
8863a584
CY
782Specify the background color, overriding the color specified by the
783@code{default} face.
8cf51b2c
GM
784@item -bd @var{color}
785@opindex -bd
786@itemx --border-color=@var{color}
787@opindex --border-color
788@cindex border color, command-line argument
a73a3461
CY
789Specify the color of the border of the X window. This has no effect
790if Emacs is compiled with GTK+ support.
8cf51b2c
GM
791@item -cr @var{color}
792@opindex -cr
793@itemx --cursor-color=@var{color}
794@opindex --cursor-color
795@cindex cursor color, command-line argument
796Specify the color of the Emacs cursor which indicates where point is.
797@item -ms @var{color}
798@opindex -ms
799@itemx --mouse-color=@var{color}
800@opindex --mouse-color
801@cindex mouse pointer color, command-line argument
802Specify the color for the mouse cursor when the mouse is in the Emacs window.
803@item -r
804@opindex -r
805@itemx -rv
806@opindex -rv
807@itemx --reverse-video
808@opindex --reverse-video
809@cindex reverse video, command-line argument
810Reverse video---swap the foreground and background colors.
811@item --color=@var{mode}
812@opindex --color
813@cindex standard colors on a character terminal
814@cindex override character terminal color support
a73a3461
CY
815Set the @dfn{color support mode} when Emacs is run on a text terminal.
816This option overrides the number of supported colors that the
817character terminal advertises in its @code{termcap} or @code{terminfo}
818database. The parameter @var{mode} can be one of the following:
8cf51b2c
GM
819@table @samp
820@item never
821@itemx no
822Don't use colors even if the terminal's capabilities specify color
823support.
824@item default
825@itemx auto
826Same as when @option{--color} is not used at all: Emacs detects at
827startup whether the terminal supports colors, and if it does, turns on
828colored display.
829@item always
830@itemx yes
831@itemx ansi8
832Turn on the color support unconditionally, and use color commands
833specified by the ANSI escape sequences for the 8 standard colors.
834@item @var{num}
835Use color mode for @var{num} colors. If @var{num} is -1, turn off
836color support (equivalent to @samp{never}); if it is 0, use the
837default color support for this terminal (equivalent to @samp{auto});
838otherwise use an appropriate standard mode for @var{num} colors.
839Depending on your terminal's capabilities, Emacs might be able to turn
840on a color mode for 8, 16, 88, or 256 as the value of @var{num}. If
841there is no mode that supports @var{num} colors, Emacs acts as if
842@var{num} were 0, i.e.@: it uses the terminal's default color support
843mode.
844@end table
845If @var{mode} is omitted, it defaults to @var{ansi8}.
846@end table
847
848 For example, to use a coral mouse cursor and a slate blue text cursor,
849enter:
850
851@example
852emacs -ms coral -cr 'slate blue' &
853@end example
854
855 You can reverse the foreground and background colors through the
856@samp{-rv} option or with the X resource @samp{reverseVideo}.
857
0be641c0
CY
858 The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on text
859terminals as well as on graphical displays.
8cf51b2c
GM
860
861@node Window Size X
862@appendixsec Options for Window Size and Position
863@cindex geometry of Emacs window
864@cindex position and size of Emacs frame
865@cindex width and height of Emacs frame
866@cindex specifying fullscreen for Emacs frame
867
868 Here is a list of the command-line options for specifying size and
869position of the initial Emacs frame:
870
871@table @samp
872@item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]}
873@opindex -g
874@itemx --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]}
875@opindex --geometry
876@cindex geometry, command-line argument
877Specify the size @var{width} and @var{height} (measured in character
878columns and lines), and positions @var{xoffset} and @var{yoffset}
879(measured in pixels). The @var{width} and @var{height} parameters
880apply to all frames, whereas @var{xoffset} and @var{yoffset} only to
881the initial frame.
882
883@item -fs
884@opindex -fs
885@itemx --fullscreen
886@opindex --fullscreen
887@cindex fullscreen, command-line argument
3f1c6666
JD
888Specify that width and height shall be the size of the screen. Normally
889no window manager decorations are shown.
890
891@item -mm
892@opindex -mm
893@itemx --maximized
894@opindex --maximized
895@cindex maximized, command-line argument
896Specify that the Emacs frame shall be maximized. This normally
897means that the frame has window manager decorations.
8cf51b2c
GM
898
899@item -fh
900@opindex -fh
901@itemx --fullheight
902@opindex --fullheight
903@cindex fullheight, command-line argument
904Specify that the height shall be the height of the screen.
905
906@item -fw
907@opindex -fw
908@itemx --fullwidth
909@opindex --fullwidth
910@cindex fullwidth, command-line argument
911Specify that the width shall be the width of the screen.
912@end table
913
8cf51b2c
GM
914@noindent
915In the @samp{--geometry} option, @code{@r{@{}+-@r{@}}} means either a plus
916 sign or a minus sign. A plus
917sign before @var{xoffset} means it is the distance from the left side of
918the screen; a minus sign means it counts from the right side. A plus
919sign before @var{yoffset} means it is the distance from the top of the
920screen, and a minus sign there indicates the distance from the bottom.
921The values @var{xoffset} and @var{yoffset} may themselves be positive or
922negative, but that doesn't change their meaning, only their direction.
923
924 Emacs uses the same units as @command{xterm} does to interpret the geometry.
925The @var{width} and @var{height} are measured in characters, so a large font
926creates a larger frame than a small font. (If you specify a proportional
927font, Emacs uses its maximum bounds width as the width unit.) The
928@var{xoffset} and @var{yoffset} are measured in pixels.
929
930 You do not have to specify all of the fields in the geometry
931specification. If you omit both @var{xoffset} and @var{yoffset}, the
932window manager decides where to put the Emacs frame, possibly by
933letting you place it with the mouse. For example, @samp{164x55}
934specifies a window 164 columns wide, enough for two ordinary width
935windows side by side, and 55 lines tall.
936
07c75e57 937 The default frame width is 80 characters and the default height is
8cf51b2c
GM
93840 lines. You can omit either the width or the height or both. If
939you start the geometry with an integer, Emacs interprets it as the
940width. If you start with an @samp{x} followed by an integer, Emacs
07c75e57
CY
941interprets it as the height. Thus, @samp{81} specifies just the
942width; @samp{x45} specifies just the height.
8cf51b2c
GM
943
944 If you start with @samp{+} or @samp{-}, that introduces an offset,
945which means both sizes are omitted. Thus, @samp{-3} specifies the
946@var{xoffset} only. (If you give just one offset, it is always
947@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the
948@var{yoffset}, placing the frame near the bottom left of the screen.
949
07c75e57
CY
950 You can specify a default for any or all of the fields in your X
951resource file (@pxref{Resources}), and then override selected fields
952with a @samp{--geometry} option.
8cf51b2c
GM
953
954 Since the mode line and the echo area occupy the last 2 lines of the
955frame, the height of the initial text window is 2 less than the height
956specified in your geometry. In non-X-toolkit versions of Emacs, the
957menu bar also takes one line of the specified number. But in the X
958toolkit version, the menu bar is additional and does not count against
959the specified height. The tool bar, if present, is also additional.
960
961 Enabling or disabling the menu bar or tool bar alters the amount of
962space available for ordinary text. Therefore, if Emacs starts up with
963a tool bar (which is the default), and handles the geometry
964specification assuming there is a tool bar, and then your
07c75e57 965initialization file disables the tool bar, you will end up with a
8cf51b2c
GM
966frame geometry different from what you asked for. To get the intended
967size with no tool bar, use an X resource to specify ``no tool bar''
968(@pxref{Table of Resources}); then Emacs will already know there's no
969tool bar when it processes the specified geometry.
970
3f1c6666
JD
971 When using one of @samp{--fullscreen}, @samp{--maximized}, @samp{--fullwidth}
972or @samp{--fullheight} there may be some space around the frame
8cf51b2c
GM
973anyway. That is because Emacs rounds the sizes so they are an
974even number of character heights and widths.
975
976 Some window managers have options that can make them ignore both
07c75e57
CY
977program-specified and user-specified positions. If these are set,
978Emacs fails to position the window correctly.
8cf51b2c
GM
979
980@node Borders X
981@appendixsec Internal and External Borders
982@cindex borders (X Window System)
983
984 An Emacs frame has an internal border and an external border. The
985internal border is an extra strip of the background color around the
986text portion of the frame. Emacs itself draws the internal border.
987The external border is added by the window manager outside the frame;
988depending on the window manager you use, it may contain various boxes
989you can click on to move or iconify the window.
990
991@table @samp
992@item -ib @var{width}
993@opindex -ib
994@itemx --internal-border=@var{width}
995@opindex --internal-border
996@cindex internal border width, command-line argument
997Specify @var{width} as the width of the internal border (between the text
998and the main border), in pixels.
999
1000@item -bw @var{width}
1001@opindex -bw
1002@itemx --border-width=@var{width}
1003@opindex --border-width
1004@cindex main border width, command-line argument
1005Specify @var{width} as the width of the main border, in pixels.
1006@end table
1007
1008 When you specify the size of the frame, that does not count the
1009borders. The frame's position is measured from the outside edge of the
1010external border.
1011
1012 Use the @samp{-ib @var{n}} option to specify an internal border
1013@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to
1014specify the width of the external border (though the window manager may
1015not pay attention to what you specify). The default width of the
1016external border is 2.
1017
1018@node Title X
1019@appendixsec Frame Titles
1020
1021 An Emacs frame may or may not have a specified title. The frame
1022title, if specified, appears in window decorations and icons as the
1023name of the frame. If an Emacs frame has no specified title, the
1024default title has the form @samp{@var{invocation-name}@@@var{machine}}
1025(if there is only one frame) or the selected window's buffer name (if
1026there is more than one frame).
1027
1028 You can specify a title for the initial Emacs frame with a command
1029line option:
1030
1031@table @samp
1032@item -T @var{title}
1033@opindex -T
1034@itemx --title=@var{title}
1035@opindex --title
1036@cindex frame title, command-line argument
1037Specify @var{title} as the title for the initial Emacs frame.
1038@end table
1039
1040 The @samp{--name} option (@pxref{Resources}) also specifies the title
1041for the initial Emacs frame.
1042
1043@node Icons X
1044@appendixsec Icons
1045@cindex icons (X Window System)
07c75e57 1046@cindex minimizing a frame at startup
8cf51b2c
GM
1047
1048@table @samp
07c75e57
CY
1049@item -iconic
1050@opindex --iconic
1051@itemx --iconic
1052@cindex start iconified, command-line argument
1053Start Emacs in an iconified (``minimized'') state.
1054
8cf51b2c
GM
1055@item -nbi
1056@opindex -nbi
1057@itemx --no-bitmap-icon
1058@opindex --no-bitmap-icon
1059@cindex Emacs icon, a gnu
a73a3461 1060Disable the use of the Emacs icon.
8cf51b2c
GM
1061@end table
1062
07c75e57
CY
1063 Most window managers allow you to ``iconify'' (or ``minimize'') an
1064Emacs frame, hiding it from sight. Some window managers replace
1065iconified windows with tiny ``icons'', while others remove them
1066entirely from sight. The @samp{-iconic} option tells Emacs to begin
1067running in an iconified state, rather than showing a frame right away.
1068The text frame doesn't appear until you deiconify (or ``un-minimize'')
1069it.
8cf51b2c 1070
07c75e57 1071 By default, Emacs uses an icon containing the Emacs logo. On
a73a3461
CY
1072desktop environments such as Gnome, this icon is also displayed in
1073other contexts, e.g.@: when switching into an Emacs frame. The
1074@samp{-nbi} or @samp{--no-bitmap-icon} option tells Emacs to let the
1075window manager choose what sort of icon to use---usually just a small
1076rectangle containing the frame's title.
8cf51b2c
GM
1077
1078@node Misc X
1079@appendixsec Other Display Options
1080
1081@table @samp
07c75e57
CY
1082@c @item -hb
1083@c @opindex -hb
1084@c @itemx --horizontal-scroll-bars
1085@c @opindex --horizontal-scroll-bars
1086@c @c @cindex horizontal scroll bars, command-line argument
1087@c Enable horizontal scroll bars. Since horizontal scroll bars
1088@c are not yet implemented, this actually does nothing.
8cf51b2c 1089
fdeb32ec
CY
1090@item --parent-id @var{ID}
1091Open Emacs as a client X window via the XEmbed protocol, with @var{ID}
1092as the parent X window id. Currently, this option is mainly useful
1093for developers.
1094
8cf51b2c
GM
1095@item -vb
1096@opindex -vb
1097@itemx --vertical-scroll-bars
1098@opindex --vertical-scroll-bars
1099@cindex vertical scroll bars, command-line argument
1100Enable vertical scroll bars.
1101
1102@item -lsp @var{pixels}
1103@opindex -lsp
1104@itemx --line-spacing=@var{pixels}
1105@opindex --line-spacing
1106@cindex line spacing, command-line argument
1107Specify @var{pixels} as additional space to put between lines, in pixels.
1108
1109@item -nbc
1110@opindex -nbc
1111@itemx --no-blinking-cursor
1112@opindex --no-blinking-cursor
1113@cindex blinking cursor disable, command-line argument
1114Disable the blinking cursor on graphical displays.
1115
1116@item -D
1117@opindex -D
1118@itemx --basic-display
1119@opindex --basic-display
1120Disable the menu-bar, the tool-bar, the scroll-bars, and tool tips,
1121and turn off the blinking cursor. This can be useful for making a
1122test case that simplifies debugging of display problems.
1123@end table
1124
1125 The @samp{--xrm} option (@pxref{Resources}) specifies additional
1126X resource values.