1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node Command Arguments, Antinews, Service, Top
5 @appendix Command Line Arguments
6 @cindex command line arguments
7 @cindex arguments (command line)
8 @cindex options (command line)
9 @cindex switches (command line)
10 @cindex startup (command line arguments)
12 GNU Emacs supports command line arguments to request various actions
13 when invoking Emacs. These are for compatibility with other editors and
14 for sophisticated activities. We don't recommend using them for
17 Arguments starting with @samp{-} are @dfn{options}. Other arguments
18 specify files to visit. Emacs visits the specified files while it
19 starts up. The last file name on your command line becomes the current
20 buffer; the other files are also present in other buffers. As usual,
21 the special argument @samp{--} says that all subsequent arguments
22 are file names, not options, even if they start with @samp{-}.
24 Emacs command options can specify many things, such as the size and
25 position of the X window Emacs uses, its colors, and so on. A few
26 options support advanced usage, such as running Lisp functions on files
27 in batch mode. The sections of this chapter describe the available
28 options, arranged according to their purpose.
30 There are two ways of writing options: the short forms that start with
31 a single @samp{-}, and the long forms that start with @samp{--}. For
32 example, @samp{-d} is a short form and @samp{--display} is the
33 corresponding long form.
35 The long forms with @samp{--} are easier to remember, but longer to
36 type. However, you don't have to spell out the whole option name; any
37 unambiguous abbreviation is enough. When a long option takes an
38 argument, you can use either a space or an equal sign to separate the
39 option name and the argument. Thus, you can write either
40 @samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}.
41 We recommend an equal sign because it makes the relationship clearer,
42 and the tables below always show an equal sign.
44 @cindex initial options (command line)
45 @cindex action options (command line)
46 Most options specify how to initialize Emacs, or set parameters for
47 the Emacs session. We call them @dfn{initial options}. A few options
48 specify things to do: for example, load libraries, call functions, or
49 exit Emacs. These are called @dfn{action options}. These and file
50 names together are called @dfn{action arguments}. Emacs processes all
51 the action arguments in the order they are written.
54 * Action Arguments:: Arguments to visit files, load libraries,
56 * Initial Options:: Arguments that take effect while starting Emacs.
57 * Command Example:: Examples of using command line arguments.
58 * Resume Arguments:: Specifying arguments when you resume a running Emacs.
59 * Environment:: Environment variables that Emacs uses.
61 * Display X:: Changing the default display and using remote login.
62 * Font X:: Choosing a font for text, under X.
63 * Colors X:: Choosing colors, under X.
64 * Window Size X:: Start-up window size, under X.
65 * Borders X:: Internal and external borders, under X.
66 * Title X:: Specifying the initial frame's title.
67 * Icons X:: Choosing what sort of icon to use, under X.
68 * Resources X:: Advanced use of classes and resources, under X.
69 * Lucid Resources:: X resources for Lucid menus.
70 * LessTif Resources:: X resources for LessTif and Motif menus.
73 @node Action Arguments
74 @appendixsec Action Arguments
76 Here is a table of the action arguments and options:
81 @itemx --visit=@var{file}
83 @itemx --file=@var{file}
84 @cindex visiting files, command-line argument
85 Visit @var{file} using @code{find-file}. @xref{Visiting}.
87 @item +@var{linenum} @var{file}
88 @opindex +@var{linenum}
89 Visit @var{file} using @code{find-file}, then go to line number
95 @itemx --load=@var{file}
97 @cindex loading Lisp libraries, command-line argument
98 Load a Lisp library named @var{file} with the function @code{load}.
99 @xref{Lisp Libraries}. The library can be found either in the current
100 directory, or in the Emacs library search path as specified
101 with @env{EMACSLOADPATH} (@pxref{General Variables}).
103 @item -f @var{function}
105 @itemx --funcall=@var{function}
107 @cindex call Lisp functions, command-line argument
108 Call Lisp function @var{function} with no arguments.
110 @item --eval=@var{expression}
112 @itemx --execute=@var{expression}
114 @cindex evaluate expression, command-line argument
115 Evaluate Lisp expression @var{expression}.
117 @item --insert=@var{file}
119 @cindex insert file contents, command-line argument
120 Insert the contents of @var{file} into the current buffer. This is like
121 what @kbd{M-x insert-file} does. @xref{Misc File Ops}.
125 Exit from Emacs without asking for confirmation.
128 @vindex command-line-args
129 The init file can access the values of the action arguments as the
130 elements of a list in the variable @code{command-line-args}. The init
131 file can override the normal processing of the action arguments, or
132 define new ones, by reading and setting this variable.
134 @node Initial Options
135 @appendixsec Initial Options
137 The initial options specify parameters for the Emacs session. This
138 section describes the more general initial options; some other options
139 specifically related to the X Window System appear in the following
142 Some initial options affect the loading of init files. The normal
143 actions of Emacs are to first load @file{site-start.el} if it exists,
144 then your own init file @file{~/.emacs} if it exists, and finally
145 @file{default.el} if it exists; certain options prevent loading of some
146 of these files or substitute other files for them.
149 @item -t @var{device}
151 @itemx --terminal=@var{device}
153 @cindex device for Emacs terminal I/O
154 Use @var{device} as the device for terminal input and output.
156 @item -d @var{display}
158 @itemx --display=@var{display}
160 @cindex display for Emacs frame
161 Use the X Window System and use the display named @var{display} to open
162 the initial Emacs frame. @xref{Display X}, for more details.
167 @opindex --no-windows
168 @cindex disable window system
169 Don't communicate directly with the window system, disregarding the
170 @env{DISPLAY} environment variable even if it is set. This forces Emacs
171 to run as if the display were a text-only terminal.
178 Run Emacs in @dfn{batch mode}, which means that the text being edited is
179 not displayed and the standard terminal interrupt characters such as
180 @kbd{C-z} and @kbd{C-c} continue to have their normal effect. Emacs in
181 batch mode outputs to @code{stderr} only what would normally be printed
182 in the echo area under program control, and functions which would
183 normally read from the minibuffer take their input from @code{stdin}.
185 Batch mode is used for running programs written in Emacs Lisp from
186 shell scripts, makefiles, and so on. Normally the @samp{-l} option
187 or @samp{-f} option will be used as well, to invoke a Lisp program
188 to do the batch processing.
190 @samp{-batch} implies @samp{-q} (do not load an init file). It also causes
191 Emacs to kill itself after all command options have been processed. In
192 addition, auto-saving is not done except in buffers for which it has been
193 explicitly requested.
197 @itemx --no-init-file
198 @opindex --no-init-file
199 @cindex bypassing init and site-start file
200 @cindex init file, not loading
201 Do not load your Emacs init file @file{~/.emacs}, or @file{default.el}
205 @opindex --no-site-file
206 @cindex site-start file, not loading
207 Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u}
208 and @samp{-batch} have no effect on the loading of this file---this is
209 the only option that blocks it.
213 @itemx --user=@var{user}
215 @cindex load init file of another user
216 Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
220 @opindex --debug-init
221 @cindex errors in init file
222 Enable the Emacs Lisp debugger for errors in the init file.
226 @cindex unibyte operation, command-line argument
227 Set up to do almost everything with single-byte buffers and strings.
228 All buffers and strings are unibyte unless you (or a Lisp program)
229 explicitly ask for a multibyte buffer or string. (Note that Emacs
230 always loads Lisp files in multibyte mode, even if @samp{--unibyte} is
231 specified; see @ref{Enabling Multibyte}.) Setting the environment
232 variable @env{EMACS_UNIBYTE} has the same effect.
236 Inhibit the effect of @env{EMACS_UNIBYTE}, so that Emacs
237 uses multibyte characters by default, as usual.
240 @node Command Example
241 @appendixsec Command Argument Example
243 Here is an example of using Emacs with arguments and options. It
244 assumes you have a Lisp program file called @file{hack-c.el} which, when
245 loaded, performs some useful operation on the current buffer, expected
249 emacs -batch foo.c -l hack-c -f save-buffer >& log
253 This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
254 changes in the visited file), save @file{foo.c} (note that
255 @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
256 then exit back to the shell (because of @samp{-batch}). @samp{-batch}
257 also guarantees there will be no problem redirecting output to
258 @file{log}, because Emacs will not assume that it has a display terminal
261 @node Resume Arguments
262 @appendixsec Resuming Emacs with Arguments
264 You can specify action arguments for Emacs when you resume it after
265 a suspension. To prepare for this, put the following code in your
266 @file{.emacs} file (@pxref{Hooks}):
269 (add-hook 'suspend-hook 'resume-suspend-hook)
270 (add-hook 'suspend-resume-hook 'resume-process-args)
273 As further preparation, you must execute the shell script
274 @file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash} (if
275 you use bash as your shell). These scripts define an alias named
276 @code{edit}, which will resume Emacs giving it new command line
277 arguments such as files to visit.
279 Only action arguments work properly when you resume Emacs. Initial
280 arguments are not recognized---it's too late to execute them anyway.
282 Note that resuming Emacs (with or without arguments) must be done from
283 within the shell that is the parent of the Emacs job. This is why
284 @code{edit} is an alias rather than a program or a shell script. It is
285 not possible to implement a resumption command that could be run from
286 other subjobs of the shell; no way to define a command that could be
287 made the value of @env{EDITOR}, for example. Therefore, this feature
288 does not take the place of the Emacs Server feature (@pxref{Emacs
291 The aliases use the Emacs Server feature if you appear to have a
292 server Emacs running. However, they cannot determine this with complete
293 accuracy. They may think that a server is still running when in
294 actuality you have killed that Emacs, because the file
295 @file{/tmp/.esrv@dots{}} still exists. If this happens, find that
299 @appendixsec Environment Variables
300 @cindex environment variables
302 The @dfn{environment} is a feature of the operating system; it
303 consists of a collection of variables with names and values. Each
304 variable is called an @dfn{environment variable}; environment variable
305 names are case-sensitive, and it is conventional to use upper case
306 letters only. The values are all text strings.
308 What makes the environment useful is that subprocesses inherit the
309 environment automatically from their parent process. This means you
310 can set up an environment variable in your login shell, and all the
311 programs you run (including Emacs) will automatically see it.
312 Subprocesses of Emacs (such as shells, compilers, and version-control
313 software) inherit the environment from Emacs, too.
317 Inside Emacs, the command @kbd{M-x getenv} gets the value of an
318 environment variable. @kbd{M-x setenv} sets a variable in the Emacs
319 environment. The way to set environment variables outside of Emacs
320 depends on the operating system, and especially the shell that you are
321 using. For example, here's how to set the environment variable
322 @env{ORGANIZATION} to @samp{not very much} using Bash:
325 export ORGANIZATION="not very much"
329 and here's how to do it in csh or tcsh:
332 setenv ORGANIZATION "not very much"
335 When Emacs is set-up to use the X Window System, it inherits the use
336 of a large number of environment variables from the X libraries. See
337 the X documentation for more information.
340 * General Variables:: Environment variables that all versions of Emacs use.
341 * Misc Variables:: Certain system-specific variables.
344 @node General Variables
345 @appendixsubsec General Variables
347 Here is an alphabetical list of specific environment variables that
348 have special meanings in Emacs, giving the name of each variable and
349 its meaning. Most of these variables are also used by some other
350 programs. Emacs does not require any of these environment variables
351 to be set, but it uses their values if they are set.
355 Used by the @code{cd} command to search for the directory you specify,
356 when you specify a relative directory name.
358 The name of the Internet domain that the machine running Emacs is
359 located in. Used by the Gnus package.
361 @cindex unibyte operation, environment variable
362 Defining this environment variable with a nonempty value directs Emacs
363 to do almost everything with single-byte buffers and strings. It is
364 equivalent to using the @samp{--unibyte} command-line option on each
365 invocation. @xref{Initial Options}.
367 Directory for the architecture-independent files that come with Emacs.
368 This is used to initialize the Lisp variable @code{data-directory}.
370 Directory for the documentation string file,
371 @file{DOC-@var{emacsversion}}. This is used to initialize the Lisp
372 variable @code{doc-directory}.
374 A colon-separated list of directories@footnote{
375 Here and below, whenever we say ``colon-separated list of directories'',
376 it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows,
377 the directories are separated by semi-colons instead, since DOS/Windows
378 file names might include a colon after a drive letter.}
379 to search for Emacs Lisp files---used to initialize @code{load-path}.
381 A colon-separated list of directories to search for executable
382 files---used to initialize @code{exec-path}.
384 Used for shell-mode to override the @env{SHELL} environment variable.
386 The name of the file that shell commands are saved in between logins.
387 This variable defaults to @file{~/.bash_history} if you use Bash, to
388 @file{~/.sh_history} if you use ksh, and to @file{~/.history}
391 The location of the user's files in the directory tree; used for
392 expansion of file names starting with a tilde (@file{~}). On MS-DOS, it
393 defaults to the directory from which Emacs was started, with @samp{/bin}
394 removed from the end if it was present. On Windows, the default value
395 of @code{HOME} is @file{C:/}, the root directory of drive @file{C:}.
397 The name of the machine that Emacs is running on.
399 A colon-separated list of directories. Used by the @code{complete} package
402 A colon-separated list of directories in which to search for Info files.
411 The user's preferred locale. The locale has six categories, specified
412 by the environment variables @env{LC_COLLATE} for sorting,
413 @env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system
414 messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for
415 numbers, and @env{LC_TIME} for dates and times. If one of these
416 variables is not set, the category defaults to the value of the
417 @env{LANG} environment variable, or to the default @samp{C} locale if
418 @env{LANG} is not set. But if @env{LC_ALL} is specified, it overrides
419 the settings of all the other locale environment variables.
421 The value of the LC_CTYPE category is
422 matched against entries in @code{locale-language-names},
423 @code{locale-charset-language-names}, and
424 @code{locale-preferred-coding-systems}, to select a default language
425 environment and coding system. @xref{Language Environments}.
427 The user's login name. See also @env{USER}.
429 The name of the user's system mail inbox.
431 Name of file containing mail aliases. (The default is
434 Name of setup file for the mh system. (The default is @file{~/.mh_profile}.)
436 The real-world name of the user.
438 The name of the news server. Used by the mh and Gnus packages.
440 The name of the organization to which you belong. Used for setting the
441 `Organization:' header in your posts from the Gnus package.
443 A colon-separated list of directories in which executables reside. This
444 is used to initialize the Emacs Lisp variable @code{exec-path}.
446 If set, this should be the default directory when Emacs was started.
448 If set, this specifies an initial value for the variable
449 @code{mail-default-reply-to}. @xref{Mail Headers}.
451 The name of a directory in which news articles are saved by default.
452 Used by the Gnus package.
454 The name of an interpreter used to parse and execute programs run from
456 @cindex background mode, on @code{xterm}
458 The name of the terminal that Emacs is running on. The variable must be
459 set unless Emacs is run in batch mode. On MS-DOS, it defaults to
460 @samp{internal}, which specifies a built-in terminal emulation that
461 handles the machine's own display. If the value of @env{TERM} indicates
462 that Emacs runs in non-windowed mode from @code{xterm} or a similar
463 terminal emulator, the background mode defaults to @samp{light}, and
464 Emacs will choose colors that are appropriate for a light background.
466 The name of the termcap library file describing how to program the
467 terminal specified by the @env{TERM} variable. This defaults to
470 Used by the Emerge package as a prefix for temporary files.
472 This specifies the current time zone and possibly also daylight
473 saving time information. On MS-DOS, if @code{TZ} is not set in the
474 environment when Emacs starts, Emacs defines a default value as
475 appropriate for the country code returned by DOS. On MS-Windows, Emacs
476 does not use @code{TZ} at all.
478 The user's login name. See also @env{LOGNAME}. On MS-DOS, this
479 defaults to @samp{root}.
480 @item VERSION_CONTROL
481 Used to initialize the @code{version-control} variable (@pxref{Backup
486 @appendixsubsec Miscellaneous Variables
488 These variables are used only on particular configurations:
492 On MS-DOS and MS-Windows, the name of the command interpreter to use
493 when invoking batch files and commands internal to the shell. On MS-DOS
494 this is also used to make a default value for the @env{SHELL} environment
498 On MS-DOS, this variable defaults to the value of the @env{USER}
503 On MS-DOS and MS-Windows, these specify the name of the directory for
504 storing temporary files in.
507 On MS-DOS, this specifies a file to use to log the operation of the
508 internal terminal emulator. This feature is useful for submitting bug
512 On MS-DOS, this specifies the screen colors. It is useful to set them
513 this way, since otherwise Emacs would display the default colors
514 momentarily when it starts up.
516 The value of this variable should be the two-character encoding of the
517 foreground (the first character) and the background (the second
518 character) colors of the default face. Each character should be the
519 hexadecimal code for the desired color on a standard PC text-mode
520 display. For example, to get blue text on a lightgray backgraound,
521 specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and
522 7 is the code of the lightgray color.
524 The PC display usually supports only eight background colors. However,
525 Emacs switches the DOS display to a mode where all 16 colors can be used
526 for the background, so all four bits of the background color are
530 Used when initializing the Sun windows system.
534 @appendixsec Specifying the Display Name
535 @cindex display name (X Window System)
536 @cindex @env{DISPLAY} environment variable
538 The environment variable @env{DISPLAY} tells all X clients, including
539 Emacs, where to display their windows. Its value is set up by default
540 in ordinary circumstances, when you start an X server and run jobs
541 locally. Occasionally you may need to specify the display yourself; for
542 example, if you do a remote login and want to run a client program
543 remotely, displaying on your local screen.
545 With Emacs, the main reason people change the default display is to
546 let them log into another system, run Emacs on that system, but have the
547 window displayed at their local terminal. You might need to log in
548 to another system because the files you want to edit are there, or
549 because the Emacs executable file you want to run is there.
551 The syntax of the @env{DISPLAY} environment variable is
552 @samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the
553 host name of the X Window System server machine, @var{display} is an
554 arbitrarily-assigned number that distinguishes your server (X terminal)
555 from other servers on the same machine, and @var{screen} is a
556 rarely-used field that allows an X server to control multiple terminal
557 screens. The period and the @var{screen} field are optional. If
558 included, @var{screen} is usually zero.
560 For example, if your host is named @samp{glasperle} and your server is
561 the first (or perhaps the only) server listed in the configuration, your
562 @env{DISPLAY} is @samp{glasperle:0.0}.
564 You can specify the display name explicitly when you run Emacs, either
565 by changing the @env{DISPLAY} variable, or with the option @samp{-d
566 @var{display}} or @samp{--display=@var{display}}. Here is an example:
569 emacs --display=glasperle:0 &
572 You can inhibit the direct use of the window system and GUI with the
573 @samp{-nw} option. It tells Emacs to display using ordinary ASCII on
574 its controlling terminal. This is also an initial option.
576 Sometimes, security arrangements prevent a program on a remote system
577 from displaying on your local system. In this case, trying to run Emacs
578 produces messages like this:
581 Xlib: connection to "glasperle:0.0" refused by server
585 You might be able to overcome this problem by using the @code{xhost}
586 command on the local system to give permission for access from your
590 @appendixsec Font Specification Options
591 @cindex font name (X Window System)
593 By default, Emacs displays text in the font named @samp{9x15}, which
594 makes each character nine pixels wide and fifteen pixels high. You can
595 specify a different font on your command line through the option
596 @samp{-fn @var{name}} (or @samp{--font}, which is an alias for
602 @itemx --font=@var{name}
604 @cindex specify default font from the command line
605 Use font @var{name} as the default font.
608 Under X, each font has a long name which consists of eleven words or
609 numbers, separated by dashes. Some fonts also have shorter
610 nicknames---@samp{9x15} is such a nickname. You can use either kind of
611 name. You can use wildcard patterns for the font name; then Emacs lets
612 X choose one of the fonts that match the pattern. Here is an example,
613 which happens to specify the font whose nickname is @samp{6x13}:
616 emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" &
620 You can also specify the font in your @file{.Xdefaults} file:
623 emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
626 A long font name has the following form:
629 -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
630 @dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset}
635 This is the name of the font manufacturer.
637 This is the name of the font family---for example, @samp{courier}.
639 This is normally @samp{bold}, @samp{medium} or @samp{light}. Other
640 words may appear here in some font names.
642 This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique),
643 @samp{ri} (reverse italic), or @samp{ot} (other).
645 This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed}
646 or @samp{normal}. Other words may appear here in some font names.
648 This is an optional additional style name. Usually it is empty---most
649 long font names have two hyphens in a row at this point.
651 This is the font height, in pixels.
653 This is the font height on the screen, measured in tenths of a printer's
654 point---approximately 1/720 of an inch. In other words, it is the point
655 size of the font, times ten. For a given vertical resolution,
656 @var{height} and @var{pixels} are proportional; therefore, it is common
657 to specify just one of them and use @samp{*} for the other.
659 This is the horizontal resolution, in pixels per inch, of the screen for
660 which the font is intended.
662 This is the vertical resolution, in pixels per inch, of the screen for
663 which the font is intended. Normally the resolution of the fonts on
664 your system is the right value for your screen; therefore, you normally
665 specify @samp{*} for this and @var{horiz}.
667 This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c}
670 This is the average character width, in pixels, multiplied by ten.
672 This is the character set that the font depicts.
673 Normally you should use @samp{iso8859-1}.
676 @cindex listing system fonts
677 You will probably want to use a fixed-width default font---that is,
678 a font in which all characters have the same width. Any font with
679 @samp{m} or @samp{c} in the @var{spacing} field of the long name is a
680 fixed-width font. Here's how to use the @code{xlsfonts} program to
681 list all the fixed-width fonts available on your system:
684 xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"
685 xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
686 xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'
690 To see what a particular font looks like, use the @code{xfd} command.
698 displays the entire font @samp{6x13}.
700 While running Emacs, you can set the font of the current frame
701 (@pxref{Frame Parameters}) or for a specific kind of text
705 @appendixsec Window Color Options
706 @cindex color of window
707 @cindex text colors, from command line
709 @findex list-colors-display
710 @cindex available colors
711 On a color display, you can specify which color to use for various
712 parts of the Emacs display. To find out what colors are available on
713 your system, type @kbd{M-x list-colors-display}, or press
714 @kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu.
715 If you do not specify colors, on windowed displays the default for the
716 background is white and the default for all other colors is black. On a
717 monochrome display, the foreground is black, the background is white,
718 and the border is gray if the display supports that. On terminals, the
719 background is usually black and the foreground is white.
721 Here is a list of the command-line options for specifying colors:
724 @item -fg @var{color}
726 @itemx --foreground-color=@var{color}
727 @opindex --foreground-color
728 @cindex foreground color, command-line argument
729 Specify the foreground color. @var{color} should be a standard color
730 name, or a numeric specification of the color's red, green, and blue
731 components as in @samp{#4682B4} or @samp{RGB:46/82/B4}.
732 @item -bg @var{color}
734 @itemx --background-color=@var{color}
735 @opindex --background-color
736 @cindex background color, command-line argument
737 Specify the background color.
738 @item -bd @var{color}
740 @itemx --border-color=@var{color}
741 @opindex --border-color
742 @cindex border color, command-line argument
743 Specify the color of the border of the X window.
744 @item -cr @var{color}
746 @itemx --cursor-color=@var{color}
747 @opindex --cursor-color
748 @cindex cursor color, command-line argument
749 Specify the color of the Emacs cursor which indicates where point is.
750 @item -ms @var{color}
752 @itemx --mouse-color=@var{color}
753 @opindex --mouse-color
754 @cindex mouse pointer color, command-line argument
755 Specify the color for the mouse cursor when the mouse is in the Emacs window.
760 @itemx --reverse-video
761 @opindex --reverse-video
762 @cindex reverse video, command-line argument
763 Reverse video---swap the foreground and background colors.
766 For example, to use a coral mouse cursor and a slate blue text cursor,
770 emacs -ms coral -cr 'slate blue' &
773 You can reverse the foreground and background colors through the
774 @samp{-rv} option or with the X resource @samp{reverseVideo}.
776 The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on
777 text-only terminals as well as on window systems.
780 @appendixsec Options for Window Geometry
781 @cindex geometry of Emacs window
782 @cindex position and size of Emacs frame
784 The @samp{-geometry} option controls the size and position of the
785 initial Emacs frame. Here is the format for specifying the window
789 @item -g @var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
791 Specify window size @var{width} and @var{height} (measured in character
792 columns and lines), and positions @var{xoffset} and @var{yoffset}
793 (measured in pixels).
795 @item --geometry=@var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
797 This is another way of writing the same thing.
801 @code{@r{@{}+-@r{@}}} means either a plus sign or a minus sign. A plus
802 sign before @var{xoffset} means it is the distance from the left side of
803 the screen; a minus sign means it counts from the right side. A plus
804 sign before @var{yoffset} means it is the distance from the top of the
805 screen, and a minus sign there indicates the distance from the bottom.
806 The values @var{xoffset} and @var{yoffset} may themselves be positive or
807 negative, but that doesn't change their meaning, only their direction.
809 Emacs uses the same units as @code{xterm} does to interpret the geometry.
810 The @var{width} and @var{height} are measured in characters, so a large font
811 creates a larger frame than a small font. (If you specify a proportional
812 font, Emacs uses its maximum bounds width as the width unit.) The
813 @var{xoffset} and @var{yoffset} are measured in pixels.
815 Since the mode line and the echo area occupy the last 2 lines of the
816 frame, the height of the initial text window is 2 less than the height
817 specified in your geometry. In non-X-toolkit versions of Emacs, the
818 menu bar also takes one line of the specified number. But in the X
819 toolkit version, the menu bar is additional and does not count against
820 the specified height. The tool bar, if present, is also additional.
822 You do not have to specify all of the fields in the geometry
825 If you omit both @var{xoffset} and @var{yoffset}, the window manager
826 decides where to put the Emacs frame, possibly by letting you place
827 it with the mouse. For example, @samp{164x55} specifies a window 164
828 columns wide, enough for two ordinary width windows side by side, and 55
831 The default width for Emacs is 80 characters and the default height is
832 40 lines. You can omit either the width or the height or both. If
833 you start the geometry with an integer, Emacs interprets it as the
834 width. If you start with an @samp{x} followed by an integer, Emacs
835 interprets it as the height. Thus, @samp{81} specifies just the width;
836 @samp{x45} specifies just the height.
838 If you start with @samp{+} or @samp{-}, that introduces an offset,
839 which means both sizes are omitted. Thus, @samp{-3} specifies the
840 @var{xoffset} only. (If you give just one offset, it is always
841 @var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the
842 @var{yoffset}, placing the frame near the bottom left of the screen.
844 You can specify a default for any or all of the fields in
845 @file{.Xdefaults} file, and then override selected fields with a
846 @samp{--geometry} option.
849 @appendixsec Internal and External Borders
850 @cindex borders (X Window System)
852 An Emacs frame has an internal border and an external border. The
853 internal border is an extra strip of the background color around all
854 four edges of the frame. Emacs itself adds the internal border. The
855 external border is added by the window manager outside the internal
856 border; it may contain various boxes you can click on to move or iconify
860 @item -ib @var{width}
862 @itemx --internal-border=@var{width}
863 @opindex --internal-border
864 @cindex border width, command-line argument
865 Specify @var{width} as the width of the internal border, in pixels.
867 @item -bw @var{width}
869 @itemx --border-width=@var{width}
870 @opindex --border-width
871 Specify @var{width} as the width of the main border, in pixels.
874 When you specify the size of the frame, that does not count the
875 borders. The frame's position is measured from the outside edge of the
878 Use the @samp{-ib @var{n}} option to specify an internal border
879 @var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to
880 specify the width of the external border (though the window manager may
881 not pay attention to what you specify). The default width of the
882 external border is 2.
885 @appendixsec Frame Titles
887 An Emacs frame may or may not have a specified title. The frame
888 title, if specified, appears in window decorations and icons as the name
889 of the frame. If an Emacs frame has no specified title, the default
890 title is the name of the executable program (if there is only one frame)
891 or the selected window's buffer name (if there is more than one frame).
893 You can specify a title for the initial Emacs frame with a command
897 @item -title @var{title}
899 @itemx --title=@var{title}
900 @itemx -T @var{title}
902 @cindex frame title, command-line argument
903 Specify @var{title} as the title for the initial Emacs frame.
906 The @samp{--name} option (@pxref{Resources X}) also specifies the title
907 for the initial Emacs frame.
911 @cindex icons (X Window System)
913 Most window managers allow the user to ``iconify'' a frame, removing
914 it from sight, and leaving a small, distinctive ``icon'' window in its
915 place. Clicking on the icon window makes the frame itself appear again.
916 If you have many clients running at once, you can avoid cluttering up
917 the screen by iconifying most of the clients.
924 @cindex Emacs icon, a gnu
925 Use a picture of a gnu as the Emacs icon.
930 @cindex start iconified, command-line argument
931 Start Emacs in iconified state.
934 The @samp{-i} or @samp{--icon-type} option tells Emacs to use an icon
935 window containing a picture of the GNU gnu. If omitted, Emacs lets the
936 window manager choose what sort of icon to use---usually just a small
937 rectangle containing the frame's title.
939 The @samp{-iconic} option tells Emacs to begin running as an icon,
940 rather than showing a frame right away. In this situation, the icon
941 is the only indication that Emacs has started; the text frame doesn't
942 appear until you deiconify it.
945 @appendixsec X Resources
948 Programs running under the X Window System organize their user options
949 under a hierarchy of classes and resources. You can specify default
950 values for these options in your X resources file, usually named
953 Each line in the file specifies a value for one option or for a
954 collection of related options, for one program or for several programs
955 (optionally even for all programs).
957 @cindex Registry (MS-Windows)
958 MS-Windows systems don't support @file{~/.Xdefaults} files, but
959 Emacs compiled for Windows looks for X resources in the Windows
960 Registry, under the keys @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs}
961 and @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}.
963 Programs define named resources with particular meanings. They also
964 define how to group resources into named classes. For instance, in
965 Emacs, the @samp{internalBorder} resource controls the width of the
966 internal border, and the @samp{borderWidth} resource controls the width
967 of the external border. Both of these resources are part of the
968 @samp{BorderWidth} class. Case distinctions are significant in these
971 In @file{~/.Xdefaults}, you can specify a value for a single resource
972 on one line, like this:
979 Or you can use a class name to specify the same value for all resources
980 in that class. Here's an example:
986 If you specify a value for a class, it becomes the default for all
987 resources in that class. You can specify values for individual
988 resources as well; these override the class value, for those particular
989 resources. Thus, this example specifies 2 as the default width for all
990 borders, but overrides this value with 4 for the external border:
997 The order in which the lines appear in the file does not matter.
998 Also, command-line options always override the X resources file.
1000 The string @samp{emacs} in the examples above is also a resource
1001 name. It actually represents the name of the executable file that you
1002 invoke to run Emacs. If Emacs is installed under a different name, it
1003 looks for resources under that name instead of @samp{emacs}.
1006 @item -name @var{name}
1008 @itemx --name=@var{name}
1009 @cindex resource name, command-line argument
1010 Use @var{name} as the resource name (and the title) for the initial
1011 Emacs frame. This option does not affect subsequent frames, but Lisp
1012 programs can specify frame names when they create frames.
1014 If you don't specify this option, the default is to use the Emacs
1015 executable's name as the resource name.
1017 @item -xrm @var{resource-values}
1019 @itemx --xrm=@var{resource-values}
1020 @cindex resource values, command-line argument
1021 Specify X resource values for this Emacs job (see below).
1024 For consistency, @samp{-name} also specifies the name to use for
1025 other resource values that do not belong to any particular frame.
1027 The resources that name Emacs invocations also belong to a class; its
1028 name is @samp{Emacs}. If you write @samp{Emacs} instead of
1029 @samp{emacs}, the resource applies to all frames in all Emacs jobs,
1030 regardless of frame titles and regardless of the name of the executable
1031 file. Here is an example:
1034 Emacs.BorderWidth: 2
1035 Emacs.borderWidth: 4
1038 You can specify a string of additional resource values for Emacs to
1039 use with the command line option @samp{-xrm @var{resources}}. The text
1040 @var{resources} should have the same format that you would use inside a file
1041 of X resources. To include multiple resource specifications in
1042 @var{resources}, put a newline between them, just as you would in a file.
1043 You can also use @samp{#include "@var{filename}"} to include a file full
1044 of resource specifications. Resource values specified with @samp{-xrm}
1045 take precedence over all other resource specifications.
1047 The following table lists the resource names that designate options
1048 for Emacs, each with the class that it belongs to:
1051 @item @code{background} (class @code{Background})
1052 Background color name.
1054 @item @code{bitmapIcon} (class @code{BitmapIcon})
1055 Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
1056 manager choose an icon if @samp{off}.
1058 @item @code{borderColor} (class @code{BorderColor})
1059 Color name for the external border.
1061 @item @code{borderWidth} (class @code{BorderWidth})
1062 Width in pixels of the external border.
1064 @item @code{cursorColor} (class @code{Foreground})
1065 Color name for text cursor (point).
1067 @item @code{font} (class @code{Font})
1068 Font name for text (or fontset name, @pxref{Fontsets}).
1070 @item @code{foreground} (class @code{Foreground})
1071 Color name for text.
1073 @item @code{geometry} (class @code{Geometry})
1074 Window size and position. Be careful not to specify this resource as
1075 @samp{emacs*geometry}, because that may affect individual menus as well
1076 as the Emacs frame itself.
1078 If this resource specifies a position, that position applies only to the
1079 initial Emacs frame (or, in the case of a resource for a specific frame
1080 name, only that frame). However, the size if specified here applies to
1083 @item @code{iconName} (class @code{Title})
1084 Name to display in the icon.
1086 @item @code{internalBorder} (class @code{BorderWidth})
1087 Width in pixels of the internal border.
1089 @item @code{lineSpacing} (class LineSpacing)
1090 @cindex line spacing
1092 Additional space (@dfn{leading}) between lines, in pixels.
1094 @item @code{menuBar} (class @code{MenuBar})
1095 Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}.
1097 @item @code{toolBar} (class @code{ToolBar})
1098 Number of lines to reserve for the tool bar. A zero value suppresses
1099 the tool bar. If the value is non-zero and
1100 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size
1101 will be changed automatically so that all tool bar items are visible.
1103 @item @code{minibuffer} (class @code{Minibuffer})
1104 If @samp{none}, don't make a minibuffer in this frame.
1105 It will use a separate minibuffer frame instead.
1107 @item @code{paneFont} (class @code{Font})
1108 @cindex font for menus
1109 Font name for menu pane titles, in non-toolkit versions of Emacs.
1111 @item @code{pointerColor} (class @code{Foreground})
1112 Color of the mouse cursor.
1115 @item @code{privateColormap} (class @code{PrivateColormap})
1116 If @samp{on}, use a private colormap, in the case where the ``default
1117 visual'' of class PseudoColor and Emacs is using it.
1120 @item @code{reverseVideo} (class @code{ReverseVideo})
1121 Switch foreground and background default colors if @samp{on}, use colors as
1122 specified if @samp{off}.
1124 @item @code{screenGamma} (class @code{ScreenGamma})
1125 @cindex gamma correction
1126 Gamma correction for colors, equivalent to the frame parameter
1127 @code{screen-gamma}.
1129 @item @code{selectionFont} (class @code{Font})
1130 Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
1131 toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif
1134 @item @code{synchronous} (class @code{Synchronous})
1135 @cindex debugging X problems
1136 @cindex synchronous X mode
1137 Run Emacs in synchronous mode if @samp{on}. Synchronous mode is
1138 useful for debugging X problems.
1140 @item @code{title} (class @code{Title})
1141 Name to display in the title bar of the initial Emacs frame.
1143 @item @code{verticalScrollBars} (class @code{ScrollBars})
1144 Give frames scroll bars if @samp{on}; don't have scroll bars if
1148 Here are resources for controlling the appearance of particular faces
1152 @item @var{face}.attributeFont
1153 Font for face @var{face}.
1154 @item @var{face}.attributeForeground
1155 Foreground color for face @var{face}.
1156 @item @var{face}.attributeBackground
1157 Background color for face @var{face}.
1158 @item @var{face}.attributeUnderline
1159 Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
1163 @node Lucid Resources
1164 @section Lucid Menu X Resources
1165 @cindex Menu X Resources (Lucid widgets)
1166 @cindex Lucid Widget X Resources
1168 If the Emacs installed at your site was built to use the X toolkit
1169 with the Lucid menu widgets, then the menu bar is a separate widget and
1170 has its own resources. The resource names contain @samp{pane.menubar}
1171 (following, as always, the name of the Emacs invocation or @samp{Emacs}
1172 which stands for all Emacs invocations). Specify them like this:
1175 Emacs.pane.menubar.@var{resource}: @var{value}
1179 For example, to specify the font @samp{8x16} for the menu-bar items,
1183 Emacs.pane.menubar.font: 8x16
1187 Resources for @emph{non-menubar} toolkit pop-up menus have
1188 @samp{menu*}, in like fashion. For example, to specify the font
1189 @samp{8x16} for the pop-up menu items, write this:
1192 Emacs.menu*.font: 8x16
1196 For dialog boxes, use @samp{dialog} instead of @samp{menu}:
1199 Emacs.dialog*.font: 8x16
1203 Experience shows that on some systems you may need to add
1204 @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
1205 some other systems, you must not add @samp{shell.}.
1207 Here is a list of the specific resources for menu bars and pop-up menus:
1211 Font for menu item text.
1213 Color of the foreground.
1215 Color of the background.
1216 @item buttonForeground
1217 In the menu bar, the color of the foreground for a selected item.
1218 @item horizontalSpacing
1219 Horizontal spacing in pixels between items. Default is 3.
1220 @item verticalSpacing
1221 Vertical spacing in pixels between items. Default is 1.
1223 Horizontal spacing between the arrow (which indicates a submenu) and
1224 the associated text. Default is 10.
1225 @item shadowThickness
1226 Thickness of shadow line around the widget.
1228 The margin of the menu bar, in characters. The default of 4 makes the
1229 menu bar appear like the LessTif/Motif one.
1232 @node LessTif Resources
1233 @section LessTif Menu X Resources
1234 @cindex Menu X Resources (LessTif widgets)
1235 @cindex LessTif Widget X Resources
1237 If the Emacs installed at your site was built to use the X toolkit
1238 with the LessTif or Motif widgets, then the menu bar is a separate
1239 widget and has its own resources. The resource names contain
1240 @samp{pane.menubar} (following, as always, the name of the Emacs
1241 invocation or @samp{Emacs} which stands for all Emacs invocations).
1242 Specify them like this:
1245 Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value}
1248 Each individual string in the menu bar is a subwidget; the subwidget's
1249 name is the same as the menu item string. For example, the word
1250 @samp{File} in the menu bar is part of a subwidget named
1251 @samp{emacs.pane.menubar.File}. Most likely, you want to specify the
1252 same resources for the whole menu bar. To do this, use @samp{*} instead
1253 of a specific subwidget name. For example, to specify the font
1254 @samp{8x16} for the menu-bar items, write this:
1257 Emacs.pane.menubar.*.fontList: 8x16
1261 This also specifies the resource value for submenus.
1263 Each item in a submenu in the menu bar also has its own name for X
1264 resources; for example, the @samp{File} submenu has an item named
1265 @samp{Save (current buffer)}. A resource specification for a submenu
1266 item looks like this:
1269 Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
1273 For example, here's how to specify the font for the @samp{Save (current
1277 Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16
1281 For an item in a second-level submenu, such as @samp{Spell-Check Message}
1282 under @samp{Spell Checking} under @samp{Tools}, the resource fits this
1286 Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
1293 Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Spell-Check Message: @var{value}
1296 It's impossible to specify a resource for all the menu-bar items
1297 without also specifying it for the submenus as well. So if you want the
1298 submenu items to look different from the menu bar itself, you must ask
1299 for that in two steps. First, specify the resource for all of them;
1300 then, override the value for submenus alone. Here is an example:
1303 Emacs.pane.menubar.*.fontList: 8x16
1304 Emacs.pane.menubar.popup_*.fontList: 8x16
1308 For toolkit pop-up menus, use @samp{menu*} instead of
1309 @samp{pane.menubar}. For example, to specify the font @samp{8x16} for
1310 the pop-up menu items, write this:
1313 Emacs.menu*.fontList: 8x16
1319 Here is a list of the specific resources for menu bars and pop-up menus:
1323 The color to show in an armed button.
1332 Amount of space to leave around the item, within the border.
1334 The width of border around the menu item, on all sides.
1335 @item shadowThickness
1336 The width of the border shadow.
1337 @item bottomShadowColor
1338 The color for the border shadow, on the bottom and the right.
1339 @item topShadowColor
1340 The color for the border shadow, on the top and the left.