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