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 * Motif Resources:: X resources for Motif menus.
73 @node Action Arguments
74 @appendixsec Action Arguments
76 Here is a table of the action arguments and options:
80 @itemx --visit @var{file}
81 @itemx --file @var{file}
82 Visit @var{file} using @code{find-file}. @xref{Visiting}.
84 @item +@var{linenum} @var{file}
85 Visit @var{file} using @code{find-file}, then go to line number
90 @itemx --load=@var{file}
91 Load a Lisp library named @var{file} with the function @code{load}.
92 @xref{Lisp Libraries}. The library can be found either in the current
93 directory, or in the Emacs library search path as specified
94 with @env{EMACSLOADPATH} (@pxref{General Variables}).
96 @item -f @var{function}
97 @itemx --funcall=@var{function}
98 Call Lisp function @var{function} with no arguments.
100 @item --eval @var{expression}
101 @itemx --execute @var{expression}
102 Evaluate Lisp expression @var{expression}.
104 @item --insert=@var{file}
105 Insert the contents of @var{file} into the current buffer. This is like
106 what @kbd{M-x insert-file} does. @xref{Misc File Ops}.
109 Exit from Emacs without asking for confirmation.
112 @vindex command-line-args
113 The init file can access the values of the action arguments as the
114 elements of a list in the variable @code{command-line-args}. The init
115 file can override the normal processing of the action arguments, or
116 define new ones, by reading and setting this variable.
118 @node Initial Options
119 @appendixsec Initial Options
121 The initial options specify parameters for the Emacs session. This
122 section describes the more general initial options; some other options
123 specifically related to the X Window System appear in the following
126 Some initial options affect the loading of init files. The normal
127 actions of Emacs are to first load @file{site-start.el} if it exists,
128 then your own init file @file{~/.emacs} if it exists, and finally
129 @file{default.el} if it exists; certain options prevent loading of some
130 of these files or substitute other files for them.
133 @item -t @var{device}
134 @itemx --terminal=@var{device}
135 Use @var{device} as the device for terminal input and output.
137 @item -d @var{display}
138 @itemx --display=@var{display}
139 Use the X Window System and use the display named @var{display} to open
140 the initial Emacs frame.
144 Don't communicate directly with the window system, disregarding the
145 @env{DISPLAY} environment variable even if it is set. This forces Emacs
146 to run as if the display were a character terminal.
152 Run Emacs in @dfn{batch mode}, which means that the text being edited is
153 not displayed and the standard terminal interrupt characters such as
154 @kbd{C-z} and @kbd{C-c} continue to have their normal effect. Emacs in
155 batch mode outputs to @code{stderr} only what would normally be printed
156 in the echo area under program control.
158 Batch mode is used for running programs written in Emacs Lisp from
159 shell scripts, makefiles, and so on. Normally the @samp{-l} option
160 or @samp{-f} option will be used as well, to invoke a Lisp program
161 to do the batch processing.
163 @samp{-batch} implies @samp{-q} (do not load an init file). It also causes
164 Emacs to kill itself after all command options have been processed. In
165 addition, auto-saving is not done except in buffers for which it has been
166 explicitly requested.
169 @itemx --no-init-file
170 Do not load your Emacs init file @file{~/.emacs}, or @file{default.el}
174 Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u}
175 and @samp{-batch} have no effect on the loading of this file---this is
176 the only option that blocks it.
179 @itemx --user=@var{user}
180 Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
184 Enable the Emacs Lisp debugger for errors in the init file.
187 @cindex unibyte operation, command-line argument
188 Set up to do almost everything with single-byte buffers and strings.
189 All buffers and strings are unibyte unless you (or a Lisp program)
190 explicitly ask for a multibyte buffer or string. (Note that when Emacs
191 loads Lisp files for runnning, it normally does that in multibyte mode,
192 even if @samp{--unibyte} is specified; see @ref{Enabling Multibyte}.)
193 Setting the environment variable @env{EMACS_UNIBYTE} has the same
197 Inhibit the effect of @env{EMACS_UNIBYTE}, so that Emacs
198 uses multibyte characters by default, as usual.
201 @node Command Example
202 @appendixsec Command Argument Example
204 Here is an example of using Emacs with arguments and options. It
205 assumes you have a Lisp program file called @file{hack-c.el} which, when
206 loaded, performs some useful operation on the current buffer, expected
210 emacs -batch foo.c -l hack-c -f save-buffer >& log
214 This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
215 changes in the visited file), save @file{foo.c} (note that
216 @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
217 then exit back to the shell (because of @samp{-batch}). @samp{-batch}
218 also guarantees there will be no problem redirecting output to
219 @file{log}, because Emacs will not assume that it has a display terminal
222 @node Resume Arguments
223 @appendixsec Resuming Emacs with Arguments
225 You can specify action arguments for Emacs when you resume it after
226 a suspension. To prepare for this, put the following code in your
227 @file{.emacs} file (@pxref{Hooks}):
230 (add-hook 'suspend-hook 'resume-suspend-hook)
231 (add-hook 'suspend-resume-hook 'resume-process-args)
234 As further preparation, you must execute the shell script
235 @file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash} (if
236 you use bash as your shell). These scripts define an alias named
237 @code{edit}, which will resume Emacs giving it new command line
238 arguments such as files to visit.
240 Only action arguments work properly when you resume Emacs. Initial
241 arguments are not recognized---it's too late to execute them anyway.
243 Note that resuming Emacs (with or without arguments) must be done from
244 within the shell that is the parent of the Emacs job. This is why
245 @code{edit} is an alias rather than a program or a shell script. It is
246 not possible to implement a resumption command that could be run from
247 other subjobs of the shell; no way to define a command that could be
248 made the value of @env{EDITOR}, for example. Therefore, this feature
249 does not take the place of the Emacs Server feature (@pxref{Emacs
252 The aliases use the Emacs Server feature if you appear to have a
253 server Emacs running. However, they cannot determine this with complete
254 accuracy. They may think that a server is still running when in
255 actuality you have killed that Emacs, because the file
256 @file{/tmp/.esrv@dots{}} still exists. If this happens, find that
260 @appendixsec Environment Variables
261 @cindex environment variables
263 This appendix describes how Emacs uses environment variables. An
264 environment variable is a string passed from the operating system to
265 Emacs, and the collection of environment variables is known as the
266 environment. Environment variable names are case sensitive and it is
267 conventional to use upper case letters only.
269 Because environment variables come from the operating system there is no
270 general way to set them; it depends on the operating system and
271 especially the shell that you are using. For example, here's how to set
272 the environment variable @env{ORGANIZATION} to @samp{not very much}
276 export ORGANIZATION="not very much"
280 and here's how to do it in csh or tcsh:
283 setenv ORGANIZATION "not very much"
286 When Emacs is set-up to use the X windowing system, it inherits the
287 use of a large number of environment variables from the X library. See
288 the X documentation for more information.
292 The command @kbd{M-x setenv} sets a variable in the environment of the
293 Emacs process and its subprocesses and @kbd{M-x getenv} gets the value
297 * General Variables:: Environment variables that all versions of Emacs use.
298 * Misc Variables:: Certain system-specific variables.
301 @node General Variables
302 @appendixsubsec General Variables
306 The name of a file used to archive news articles posted with the @sc{gnus}
309 Used by the @code{cd} command to search for the directory you specify,
310 when you specify a relative directory name.
312 The name of the Internet domain that the machine running Emacs is
313 located in. Used by the @sc{gnus} package.
315 @cindex unibyte operation, environment variable
316 Defining this environment variable directs Emacs to do almost everything
317 with single-byte buffers and strings. It is equivalent to using the
318 @samp{--unibyte} command-line option on each invocation. @xref{Initial
321 Used to initialize the variable @code{data-directory} used to locate the
322 architecture-independent files that come with Emacs. Setting this
323 variable overrides the setting in @file{paths.h} when Emacs was built.
325 Used to initialize the variable @code{doc-directory} where Emacs looks
326 for its documentation string file @file{DOC-@var{version}}
327 (@var{version} is the Emacs version). Setting this variable overrides
328 the setting in @file{paths.h} when Emacs was built.
330 A colon-separated list of directories from which to load Emacs Lisp
331 files. Setting this variable overrides the setting in @file{paths.h}
332 when Emacs was built.
334 The directory that Emacs places lock files---files used to protect
335 users from editing the same files simultaneously. Setting this variable
336 overrides the setting in @file{paths.h} when Emacs was built.
338 The location of Emacs-specific binaries. Setting this variable
339 overrides the setting in @file{paths.h} when Emacs was built.
341 Used for shell-mode to override the @env{SHELL} environment variable.
343 The name of the file that shell commands are saved in between logins.
344 This variable defaults to @file{~/.history} if you use (t)csh as shell,
345 to @file{~/.bash_history} if you use bash, to @file{~/.sh_history} if
346 you use ksh, and to @file{~/.history} otherwise.
348 The location of the user's files in the directory tree; used for
349 expansion of file names starting with a tilde (@file{~}). On MS-DOS, it
350 defaults to the directory from which Emacs was started, with @samp{/bin}
351 removed from the end if it was present.
353 The name of the machine that Emacs is running on.
355 A colon-separated list of directories. Used by the @code{complete} package
358 A colon-separated list of directories holding info files. Setting this
359 variable overrides the setting in @file{paths.el} when Emacs was built.
363 @findex set-locale-environment
364 @vindex locale-language-names
365 @vindex locale-charset-language-names
366 @vindex locale-preferred-coding-systems
367 The user's locale, matched by @code{set-locale-environment} against
368 entries in @code{locale-language-names},
369 @code{locale-charset-language-names}, and
370 @code{locale-preferred-coding-systems} to select a default language
371 environment and coding system. The first of these environment variables
372 with a nonempty value specifies the locale.
374 The user's login name. See also @env{USER}.
376 The name of the user's system mail inbox.
378 Name of file containing mail aliases. This defaults to
381 Name of setup file for the mh system. This defaults to
382 @file{~/.mh_profile}.
384 The real-world name of the user.
386 The name of the news server. Used by the mh and @sc{gnus} packages.
388 The name of the organization to which you belong. Used for setting the
389 `Organization:' header in your posts from the @sc{gnus} package.
391 A colon-separated list of directories in which executables reside. (On
392 MS-DOS, it is semicolon-separated instead.) This variable is used to
393 set the Emacs Lisp variable @code{exec-path} which you should consider
396 If set, this should be the default directory when Emacs was started.
398 If set, this specifies an initial value for the variable
399 @code{mail-default-reply-to}. @xref{Mail Headers}.
401 The name of a directory in which news articles are saved by default.
402 Used by the @sc{gnus} package.
404 The name of an interpreter used to parse and execute programs run from
406 @cindex background mode, on @code{xterm}
408 The name of the terminal that Emacs is running on. The variable must be
409 set unless Emacs is run in batch mode. On MS-DOS, it defaults to
410 @samp{internal}, which specifies a built-in terminal emulation that
411 handles the machine's own display. If the value of @env{TERM} indicates
412 that Emacs runs in non-windowed mode from @code{xterm} or a similar
413 terminal emulator, the background mode defaults to @samp{light}, and
414 Emacs will choose colors that are appropriate for a light background.
416 The name of the termcap library file describing how to program the
417 terminal specified by the @env{TERM} variable. This defaults to
420 Used by the Emerge package as a prefix for temporary files.
422 This specifies the current time zone and possibly also daylight savings
423 information. On MS-DOS, the default is based on country code; see the
424 file @file{msdos.c} for details.
426 The user's login name. See also @env{LOGNAME}. On MS-DOS, this
427 defaults to @samp{root}.
428 @item VERSION_CONTROL
429 Used to initialize the @code{version-control} variable (@pxref{Backup
434 @appendixsubsec Miscellaneous Variables
436 These variables are used only on particular configurations:
440 On MS-DOS, the name of the command interpreter to use. This is used to
441 make a default value for the @env{SHELL} environment variable.
444 On MS-DOS, this variable defaults to the value of the @env{USER}
449 On MS-DOS, these specify the name of the directory for storing temporary
453 On MS-DOS, this specifies a file to use to log the operation of the
454 internal terminal emulator. This feature is useful for submitting bug
458 Used on MS-DOS systems to set screen colors early, so that the screen
459 won't momentarily flash the default colors when Emacs starts up. The
460 value of this variable should be two-character encoding of the
461 foreground (the first character) and the background (the second
462 character) colors of the default face. Each character should be the
463 hexadecimal code for the desired color on a standard PC text-mode
466 The PC display usually supports only eight background colors. However,
467 Emacs switches the DOS display to a mode where all 16 colors can be used
468 for the background, so all four bits of the background color are
472 Used when initializing the Sun windows system.
476 @appendixsec Specifying the Display Name
477 @cindex display name (X Window System)
478 @cindex @env{DISPLAY} environment variable
480 The environment variable @env{DISPLAY} tells all X clients, including
481 Emacs, where to display their windows. Its value is set up by default
482 in ordinary circumstances, when you start an X server and run jobs
483 locally. Occasionally you may need to specify the display yourself; for
484 example, if you do a remote login and want to run a client program
485 remotely, displaying on your local screen.
487 With Emacs, the main reason people change the default display is to
488 let them log into another system, run Emacs on that system, but have the
489 window displayed at their local terminal. You might need to use login
490 to another system because the files you want to edit are there, or
491 because the Emacs executable file you want to run is there.
493 The syntax of the @env{DISPLAY} environment variable is
494 @samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the
495 host name of the X Window System server machine, @var{display} is an
496 arbitrarily-assigned number that distinguishes your server (X terminal)
497 from other servers on the same machine, and @var{screen} is a
498 rarely-used field that allows an X server to control multiple terminal
499 screens. The period and the @var{screen} field are optional. If
500 included, @var{screen} is usually zero.
502 For example, if your host is named @samp{glasperle} and your server is
503 the first (or perhaps the only) server listed in the configuration, your
504 @env{DISPLAY} is @samp{glasperle:0.0}.
506 You can specify the display name explicitly when you run Emacs, either
507 by changing the @env{DISPLAY} variable, or with the option @samp{-d
508 @var{display}} or @samp{--display=@var{display}}. Here is an example:
511 emacs --display=glasperle:0 &
514 You can inhibit the direct use of X with the @samp{-nw} option. This
515 is also an initial option. It tells Emacs to display using ordinary
516 ASCII on its controlling terminal.
518 Sometimes, security arrangements prevent a program on a remote system
519 from displaying on your local system. In this case, trying to run Emacs
520 produces messages like this:
523 Xlib: connection to "glasperle:0.0" refused by server
527 You might be able to overcome this problem by using the @code{xhost}
528 command on the local system to give permission for access from your
532 @appendixsec Font Specification Options
533 @cindex font name (X Window System)
535 By default, Emacs displays text in the font named @samp{9x15}, which
536 makes each character nine pixels wide and fifteen pixels high. You can
537 specify a different font on your command line through the option
538 @samp{-fn @var{name}}.
542 Use font @var{name} as the default font.
544 @item --font=@var{name}
545 @samp{--font} is an alias for @samp{-fn}.
548 Under X, each font has a long name which consists of eleven words or
549 numbers, separated by dashes. Some fonts also have shorter
550 nicknames---@samp{9x15} is such a nickname. You can use either kind of
551 name. You can use wildcard patterns for the font name; then Emacs lets
552 X choose one of the fonts that match the pattern. Here is an example,
553 which happens to specify the font whose nickname is @samp{6x13}:
556 emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" &
560 You can also specify the font in your @file{.Xdefaults} file:
563 emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
566 A long font name has the following form:
569 -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
570 @dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset}
575 This is the name of the font family---for example, @samp{courier}.
577 This is normally @samp{bold}, @samp{medium} or @samp{light}. Other
578 words may appear here in some font names.
580 This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique),
581 @samp{ri} (reverse italic), or @samp{ot} (other).
583 This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed}
584 or @samp{normal}. Other words may appear here in some font names.
586 This is an optional additional style name. Usually it is empty---most
587 long font names have two hyphens in a row at this point.
589 This is the font height, in pixels.
591 This is the font height on the screen, measured in tenths of a printer's
592 point---approximately 1/720 of an inch. In other words, it is the point
593 size of the font, times ten. For a given vertical resolution,
594 @var{height} and @var{pixels} are proportional; therefore, it is common
595 to specify just one of them and use @samp{*} for the other.
597 This is the horizontal resolution, in pixels per inch, of the screen for
598 which the font is intended.
600 This is the vertical resolution, in dots per inch, of the screen for
601 which the font is intended. Normally the resolution of the fonts on
602 your system is the right value for your screen; therefore, you normally
603 specify @samp{*} for this and @var{horiz}.
605 This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c}
606 (character cell). Emacs can use @samp{m} and @samp{c} fonts.
608 This is the average character width, in pixels, multiplied by ten.
610 This is the character set that the font depicts.
611 Normally you should use @samp{iso8859-1}.
614 Use only fixed-width fonts---that is, fonts in which all characters
615 have the same width; Emacs cannot yet handle display properly for
616 variable-width fonts. Any font with @samp{m} or @samp{c} in the
617 @var{spacing} field of the long name is a fixed-width font. Here's how
618 to use the @code{xlsfonts} program to list all the fixed-width fonts
619 available on your system:
622 xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"
623 xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
624 xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'
628 To see what a particular font looks like, use the @code{xfd} command.
636 displays the entire font @samp{6x13}.
638 While running Emacs, you can set the font of the current frame
639 (@pxref{Frame Parameters}) or for a specific kind of text
643 @appendixsec Window Color Options
644 @cindex color of window (X Window System)
645 @cindex text colors, from command line
647 @findex list-colors-display
648 @cindex available colors
649 On a color display, you can specify which color to use for various
650 parts of the Emacs display. To find out what colors are available on
651 your system, type @kbd{M-x list-colors-display}, or press
652 @kbd{C-mouse-2} and select @samp{Display Colors} from the pop-up menu.
653 If you do not specify colors, on windowed displays the default for the
654 background is white and the default for all other colors is black. On a
655 monochrome display, the foreground is black, the background is white,
656 and the border is gray if the display supports that. On terminals, the
657 background is usually black and the foreground is white.
659 Here is a list of the command-line options for specifying colors:
662 @item -fg @var{color}
663 @itemx --foreground-color=@var{color}
664 Specify the foreground color.
665 @item -bg @var{color}
666 @itemx --background-color=@var{color}
667 Specify the background color.
668 @item -bd @var{color}
669 @itemx --border-color=@var{color}
670 Specify the color of the border of the X window.
671 @item -cr @var{color}
672 @itemx --cursor-color=@var{color}
673 Specify the color of the Emacs cursor which indicates where point is.
674 @item -ms @var{color}
675 @itemx --mouse-color=@var{color}
676 Specify the color for the mouse cursor when the mouse is in the Emacs window.
678 @itemx --reverse-video
679 Reverse video---swap the foreground and background colors.
682 For example, to use a coral mouse cursor and a slate blue text cursor,
686 emacs -ms coral -cr 'slate blue' &
689 You can reverse the foreground and background colors through the
690 @samp{-r} option or with the X resource @samp{reverseVideo}.
692 When Emacs display is on a character terminal, it supports the
693 @samp{-fg}, @code{-bg}, and @code{-rv} options.
696 @appendixsec Options for Window Geometry
697 @cindex geometry (X Window System)
699 The @samp{-geometry} option controls the size and position of the
700 initial Emacs frame. Here is the format for specifying the window
704 @item -g @var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
705 Specify window size @var{width} and @var{height} (measured in character
706 columns and lines), and positions @var{xoffset} and @var{yoffset}
707 (measured in pixels).
709 @item --geometry=@var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
710 This is another way of writing the same thing.
714 @code{@r{@{}+-@r{@}}} means either a plus sign or a minus sign. A plus
715 sign before @var{xoffset} means it is the distance from the left side of
716 the screen; a minus sign means it counts from the right side. A plus
717 sign before @var{yoffset} means it is the distance from the top of the
718 screen, and a minus sign there indicates the distance from the bottom.
719 The values @var{xoffset} and @var{yoffset} may themselves be positive or
720 negative, but that doesn't change their meaning, only their direction.
722 Emacs uses the same units as @code{xterm} does to interpret the geometry.
723 The @var{width} and @var{height} are measured in characters, so a large font
724 creates a larger frame than a small font. The @var{xoffset} and
725 @var{yoffset} are measured in pixels.
727 Since the mode line and the echo area occupy the last 2 lines of the
728 frame, the height of the initial text window is 2 less than the height
729 specified in your geometry. In non-X-toolkit versions of Emacs,
730 the menu bar also takes one line of the specified number.
732 You do not have to specify all of the fields in the geometry
735 If you omit both @var{xoffset} and @var{yoffset}, the window manager
736 decides where to put the Emacs frame, possibly by letting you place
737 it with the mouse. For example, @samp{164x55} specifies a window 164
738 columns wide, enough for two ordinary width windows side by side, and 55
741 The default width for Emacs is 80 characters and the default height is
742 40 lines. You can omit either the width or the height or both. If
743 you start the geometry with an integer, Emacs interprets it as the
744 width. If you start with an @samp{x} followed by an integer, Emacs
745 interprets it as the height. Thus, @samp{81} specifies just the width;
746 @samp{x45} specifies just the height.
748 If you start with @samp{+} or @samp{-}, that introduces an offset,
749 which means both sizes are omitted. Thus, @samp{-3} specifies the
750 @var{xoffset} only. (If you give just one offset, it is always
751 @var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the
752 @var{yoffset}, placing the frame near the bottom left of the screen.
754 You can specify a default for any or all of the fields in
755 @file{.Xdefaults} file, and then override selected fields with a
756 @samp{--geometry} option.
759 @appendixsec Internal and External Borders
760 @cindex borders (X Window System)
762 An Emacs frame has an internal border and an external border. The
763 internal border is an extra strip of the background color around all
764 four edges of the frame. Emacs itself adds the internal border. The
765 external border is added by the window manager outside the internal
766 border; it may contain various boxes you can click on to move or iconify
770 @item -ib @var{width}
771 @itemx --internal-border=@var{width}
772 Specify @var{width} as the width of the internal border.
774 @item -bw @var{width}
775 @itemx --border-width=@var{width}
776 Specify @var{width} as the width of the main border.
779 When you specify the size of the frame, that does not count the
780 borders. The frame's position is measured from the outside edge of the
783 Use the @samp{-ib @var{n}} option to specify an internal border
784 @var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to
785 specify the width of the external border (though the window manager may
786 not pay attention to what you specify). The default width of the
787 external border is 2.
790 @appendixsec Frame Titles
792 An Emacs frame may or may not have a specified title. The frame
793 title, if specified, appears in window decorations and icons as the name
794 of the frame. If an Emacs frame has no specified title, the default
795 title is the name of the executable program (if there is only one frame)
796 or the selected window's buffer name (if there is more than one frame).
798 You can specify a title for the initial Emacs frame with a command
802 @item -title @var{title}
803 @itemx --title=@var{title}
804 @itemx -T @var{title}
805 Specify @var{title} as the title for the initial Emacs frame.
808 The @samp{--name} option (@pxref{Resources X}) also specifies the title
809 for the initial Emacs frame.
813 @cindex icons (X Window System)
815 Most window managers allow the user to ``iconify'' a frame, removing
816 it from sight, and leaving a small, distinctive ``icon'' window in its
817 place. Clicking on the icon window makes the frame itself appear again.
818 If you have many clients running at once, you can avoid cluttering up
819 the screen by iconifying most of the clients.
824 Use a picture of a gnu as the Emacs icon.
828 Start Emacs in iconified state.
831 The @samp{-i} or @samp{--icon-type} option tells Emacs to use an icon
832 window containing a picture of the GNU gnu. If omitted, Emacs lets the
833 window manager choose what sort of icon to use---usually just a small
834 rectangle containing the frame's title.
836 The @samp{-iconic} option tells Emacs to begin running as an icon,
837 rather than opening a frame right away. In this situation, the icon
838 window provides only indication that Emacs has started; the usual text
839 frame doesn't appear until you deiconify it.
842 @appendixsec X Resources
845 Programs running under the X Window System organize their user options
846 under a hierarchy of classes and resources. You can specify default
847 values for these options in your X resources file, usually named
850 Each line in the file specifies a value for one option or for a
851 collection of related options, for one program or for several programs
852 (optionally even for all programs).
854 Programs define named resources with particular meanings. They also
855 define how to group resources into named classes. For instance, in
856 Emacs, the @samp{internalBorder} resource controls the width of the
857 internal border, and the @samp{borderWidth} resource controls the width
858 of the external border. Both of these resources are part of the
859 @samp{BorderWidth} class. Case distinctions are significant in these
862 In @file{~/.Xdefaults}, you can specify a value for a single resource
863 on one line, like this:
870 Or you can use a class name to specify the same value for all resources
871 in that class. Here's an example:
877 If you specify a value for a class, it becomes the default for all
878 resources in that class. You can specify values for individual
879 resources as well; these override the class value, for those particular
880 resources. Thus, this example specifies 2 as the default width for all
881 borders, but overrides this value with 4 for the external border:
888 The order in which the lines appear in the file does not matter.
889 Also, command-line options always override the X resources file.
891 The string @samp{emacs} in the examples above is also a resource
892 name. It actually represents the name of the executable file that you
893 invoke to run Emacs. If Emacs is installed under a different name, it
894 looks for resources under that name instead of @samp{emacs}.
897 @item -name @var{name}
898 @itemx --name=@var{name}
899 Use @var{name} as the resource name (and the title) for the initial
900 Emacs frame. This option does not affect subsequent frames, but Lisp
901 programs can specify frame names when they create frames.
903 If you don't specify this option, the default is to use the Emacs
904 executable's name as the resource name.
906 @item -xrm @var{resource-values}
907 @itemx --xrm=@var{resource-values}
908 Specify X resource values for this Emacs job (see below).
911 For consistency, @samp{-name} also specifies the name to use for
912 other resource values that do not belong to any particular frame.
914 The resources that name Emacs invocations also belong to a class; its
915 name is @samp{Emacs}. If you write @samp{Emacs} instead of
916 @samp{emacs}, the resource applies to all frames in all Emacs jobs,
917 regardless of frame titles and regardless of the name of the executable
918 file. Here is an example:
925 You can specify a string of additional resource values for Emacs to
926 use with the command line option @samp{-xrm @var{resources}}. The text
927 @var{resources} should have the same format that you would use inside a file
928 of X resources. To include multiple resource specifications in
929 @var{data}, put a newline between them, just as you would in a file.
930 You can also use @samp{#include "@var{filename}"} to include a file full
931 of resource specifications. Resource values specified with @samp{-xrm}
932 take precedence over all other resource specifications.
934 The following table lists the resource names that designate options
935 for Emacs, each with the class that it belongs to:
938 @item @code{background} (class @code{Background})
939 Background color name.
941 @item @code{bitmapIcon} (class @code{BitmapIcon})
942 Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
943 manager choose an icon if @samp{off}.
945 @item @code{borderColor} (class @code{BorderColor})
946 Color name for the external border.
948 @item @code{borderWidth} (class @code{BorderWidth})
949 Width in pixels of the external border.
951 @item @code{cursorColor} (class @code{Foreground})
952 Color name for text cursor (point).
954 @item @code{font} (class @code{Font})
955 Font name for text (or fontset name, @pxref{Fontsets}).
957 @item @code{foreground} (class @code{Foreground})
960 @item @code{geometry} (class @code{Geometry})
961 Window size and position. Be careful not to specify this resource as
962 @samp{emacs*geometry}, because that may affect individual menus as well
963 as the Emacs frame itself.
965 If this resource specifies a position, that position applies only to the
966 initial Emacs frame (or, in the case of a resource for a specific frame
967 name, only that frame). However, the size if specified here applies to
970 @item @code{iconName} (class @code{Title})
971 Name to display in the icon.
973 @item @code{internalBorder} (class @code{BorderWidth})
974 Width in pixels of the internal border.
976 @item @code{lineSpacing} (class LineSpacing)
979 Additional space (@dfn{leading}) between lines in pixels.
981 @item @code{menuBar} (class @code{MenuBar})
982 Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}.
984 @item @code{toolBar} (class @code{ToolBar})
985 Controls how may lines to reserve for the tool bar. A zero value
986 suppresses the tool bar. If the value is non-zero and
987 @code{auto-resize-tool-bars} is non-nil the tool bar's size will be
988 changed automatically so that all tool bar items are visible.
990 @item @code{minibuffer} (class @code{Minibuffer})
991 If @samp{none}, don't make a minibuffer in this frame.
992 It will use a separate minibuffer frame instead.
994 @item @code{paneFont} (class @code{Font})
995 Font name for menu pane titles, in non-toolkit versions of Emacs.
997 @item @code{pointerColor} (class @code{Foreground})
998 Color of the mouse cursor.
1000 @item @code{privateColormap} (class @code{PrivateColormap})
1001 Specify that Emacs should use a private colormap if it is using the
1002 default visual, and that visual is of class PseudoColor. Recognized
1003 resource values are @samp{true} and @samp{on}.
1005 @item @code{reverseVideo} (class @code{ReverseVideo})
1006 Switch foreground and background default colors if @samp{on}, use colors as
1007 specified if @samp{off}.
1009 @item @code{screenGamma} (class @code{ScreenGamma})
1010 @cindex gamma correction
1011 Specify the gamma correction for colors, equivalent to the frame
1012 parameter @code{screen-gamma}.
1014 @item @code{selectionFont} (class @code{Font})
1015 Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
1016 toolkit versions, see @ref{Lucid Resources}, also see @ref{Motif
1019 @item @code{synchronous} (class @code{Synchronous})
1020 Specify whether Emacs should run in synchronous mode if @samp{true}.
1021 Synchronous mode is useful for debugging X problems.
1023 @item @code{title} (class @code{Title})
1024 Name to display in the title bar of the initial Emacs frame.
1026 @item @code{verticalScrollBars} (class @code{ScrollBars})
1027 Give frames scroll bars if @samp{on}; don't have scroll bars if
1030 @item @code{visualClass} (class @code{VisualClass})
1031 Specify the visual Emacs should use. The resource's value should be a
1032 string of the form @samp{@var{CLASS}-@var{DEPTH}}, where @var{class} is
1033 the name of the visual class, and @var{depth} is the requested color
1034 depth as a decimal number. Valid visual class names are
1035 @samp{TrueColor}, @samp{PseudoColor}, @samp{DirectColor},
1036 @samp{StaticColor}, @samp{GrayScale} and @samp{StaticGray}.
1038 Visual class names specified as X resource are case-insensitive, i.e.@:
1039 @samp{pseudocolor}, @samp{Pseudocolor} and @samp{PseudoColor} all have
1043 The program @command{xdpyinfo} can be used to list the visual classes
1044 supported on your display, and which depths they have. If
1045 @code{visualClass} is not specified, Emacs uses the display's default
1049 Here are resources for controlling the appearance of particular faces
1053 @item @var{face}.attributeFont
1054 Font for face @var{face}.
1055 @item @var{face}.attributeForeground
1056 Foreground color for face @var{face}.
1057 @item @var{face}.attributeBackground
1058 Background color for face @var{face}.
1059 @item @var{face}.attributeUnderline
1060 Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
1064 @node Lucid Resources
1065 @section Lucid Menu X Resources
1066 @cindex Menu X Resources (Lucid widgets)
1067 @cindex Lucid Widget X Resources
1069 If the Emacs installed at your site was built to use the X toolkit
1070 with the Lucid menu widgets, then the menu bar is a separate widget and
1071 has its own resources. The resource names contain @samp{pane.menubar}
1072 (following, as always, the name of the Emacs invocation or @samp{Emacs}
1073 which stands for all Emacs invocations). Specify them like this:
1076 Emacs.pane.menubar.@var{resource}: @var{value}
1080 For example, to specify the font @samp{8x16} for the menu-bar items,
1084 Emacs.pane.menubar.font: 8x16
1088 Resources for @emph{non-menubar} toolkit pop-up menus have
1089 @samp{menu*}, in like fashion. For example, to specify the font
1090 @samp{8x16} for the pop-up menu items, write this:
1093 Emacs.menu*.font: 8x16
1097 For dialog boxes, use @samp{dialog} instead of @samp{menu}:
1100 Emacs.dialog*.font: 8x16
1104 Experience shows that on some systems you may need to add
1105 @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
1106 some other systems, you must not add @samp{shell.}.
1108 Here is a list of the specific resources for menu bars and pop-up menus:
1112 Font for menu item text.
1114 Color of the foreground.
1116 Color of the background.
1117 @item buttonForeground
1118 In the menu bar, the color of the foreground for a selected item.
1119 @item horizontalSpacing
1120 Horizontal spacing in pixels between items. Default is 3.
1121 @item verticalSpacing
1122 Vertical spacing in pixels between items. Default is 1.
1124 Horizontal spacing between the arrow (which indicates a submenu) and
1125 the associated text. Default is 10.
1126 @item shadowThickness
1127 Thickness of shadow line around the widget.
1129 The margin of the menu bar in character widths. The default of 4 makes
1130 the menu bar appear like the LessTif/Motif one.
1133 @node Motif Resources
1134 @section Motif Menu X Resources
1135 @cindex Menu X Resources (Motif widgets)
1136 @cindex Motif Widget X Resources
1138 If the Emacs installed at your site was built to use the X toolkit
1139 with the Motif widgets, then the menu bar is a separate widget and has
1140 its own resources. The resource names contain @samp{pane.menubar}
1141 (following, as always, the name of the Emacs invocation or @samp{Emacs}
1142 which stands for all Emacs invocations). Specify them like this:
1145 Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value}
1148 Each individual string in the menu bar is a subwidget; the subwidget's
1149 name is the same as the menu item string. For example, the word
1150 @samp{Files} in the menu bar is part of a subwidget named
1151 @samp{emacs.pane.menubar.Files}. Most likely, you want to specify the
1152 same resources for the whole menu bar. To do this, use @samp{*} instead
1153 of a specific subwidget name. For example, to specify the font
1154 @samp{8x16} for the menu-bar items, write this:
1157 Emacs.pane.menubar.*.fontList: 8x16
1161 This also specifies the resource value for submenus.
1163 Each item in a submenu in the menu bar also has its own name for X
1164 resources; for example, the @samp{Files} submenu has an item named
1165 @samp{Save Buffer}. A resource specification for a submenu item looks
1169 Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
1173 For example, here's how to specify the font for the @samp{Save Buffer}
1177 Emacs.pane.menubar.popup_*.Files.Save Buffer.fontList: 8x16
1181 For an item in a second-level submenu, such as @samp{Check Message}
1182 under @samp{Spell} under @samp{Edit}, the resource fits this template:
1185 Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
1192 Emacs.pane.menubar.popup_*.popup_*.Spell.Check Message: @var{value}
1195 It's impossible to specify a resource for all the menu-bar items
1196 without also specifying it for the submenus as well. So if you want the
1197 submenu items to look different from the menu bar itself, you must ask
1198 for that in two steps. First, specify the resource for all of them;
1199 then, override the value for submenus alone. Here is an example:
1202 Emacs.pane.menubar.*.fontList: 8x16
1203 Emacs.pane.menubar.popup_*.fontList: 8x16
1207 For toolkit pop-up menus, use @samp{menu*} instead of
1208 @samp{pane.menubar}. For example, to specify the font @samp{8x16} for
1209 the pop-up menu items, write this:
1212 Emacs.menu*.fontList: 8x16
1218 Here is a list of the specific resources for menu bars and pop-up menus:
1222 The color to show in an armed button.
1231 Amount of space to leave around the item, within the border.
1233 The width of border around the menu item, on all sides.
1234 @item shadowThickness
1235 The width of the border shadow.
1236 @item bottomShadowColor
1237 The color for the border shadow, on the bottom and the right.
1238 @item topShadowColor
1239 The color for the border shadow, on the top and the left.