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 X Windows appear in the following sections.
125 Some initial options affect the loading of init files. The normal
126 actions of Emacs are to first load @file{site-start.el} if it exists,
127 then your own init file @file{~/.emacs} if it exists, and finally
128 @file{default.el} if it exists; certain options prevent loading of some
129 of these files or substitute other files for them.
132 @item -t @var{device}
133 @itemx --terminal=@var{device}
134 Use @var{device} as the device for terminal input and output.
136 @item -d @var{display}
137 @itemx --display=@var{display}
138 Use the X Window System and use the display named @var{display} to open
139 the initial Emacs frame.
143 Don't communicate directly with X, disregarding the @env{DISPLAY}
144 environment variable even if it is set.
150 Run Emacs in @dfn{batch mode}, which means that the text being edited is
151 not displayed and the standard terminal interrupt characters such as
152 @kbd{C-z} and @kbd{C-c} continue to have their normal effect. Emacs in
153 batch mode outputs to @code{stderr} only what would normally be printed
154 in the echo area under program control.
156 Batch mode is used for running programs written in Emacs Lisp from
157 shell scripts, makefiles, and so on. Normally the @samp{-l} option
158 or @samp{-f} option will be used as well, to invoke a Lisp program
159 to do the batch processing.
161 @samp{-batch} implies @samp{-q} (do not load an init file). It also causes
162 Emacs to kill itself after all command options have been processed. In
163 addition, auto-saving is not done except in buffers for which it has been
164 explicitly requested.
167 @itemx --no-init-file
168 Do not load your Emacs init file @file{~/.emacs}, or @file{default.el}
172 Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u}
173 and @samp{-batch} have no effect on the loading of this file---this is
174 the only option that blocks it.
177 @itemx --user=@var{user}
178 Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
182 Enable the Emacs Lisp debugger for errors in the init file.
185 @cindex unibyte operation
186 Set up to do almost everything with single-byte buffers and strings.
187 All buffers and strings are unibyte unless you (or a Lisp program)
188 explicitly ask for a multibyte buffer or string. Setting the
189 environment variable @env{EMACS_UNIBYTE} has the same effect.
192 Inhibit the effect of @env{EMACS_UNIBYTE}, so that Emacs
193 uses multibyte characters by default, as usual.
196 @node Command Example
197 @appendixsec Command Argument Example
199 Here is an example of using Emacs with arguments and options. It
200 assumes you have a Lisp program file called @file{hack-c.el} which, when
201 loaded, performs some useful operation on the current buffer, expected
205 emacs -batch foo.c -l hack-c -f save-buffer >& log
209 This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
210 changes in the visited file), save @file{foo.c} (note that
211 @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
212 then exit back to the shell (because of @samp{-batch}). @samp{-batch}
213 also guarantees there will be no problem redirecting output to
214 @file{log}, because Emacs will not assume that it has a display terminal
217 @node Resume Arguments
218 @appendixsec Resuming Emacs with Arguments
220 You can specify action arguments for Emacs when you resume it after
221 a suspension. To prepare for this, put the following code in your
222 @file{.emacs} file (@pxref{Hooks}):
225 (add-hook 'suspend-hook 'resume-suspend-hook)
226 (add-hook 'suspend-resume-hook 'resume-process-args)
229 As further preparation, you must execute the shell script
230 @file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash} (if
231 you use bash as your shell). These scripts define an alias named
232 @code{edit}, which will resume Emacs giving it new command line
233 arguments such as files to visit.
235 Only action arguments work properly when you resume Emacs. Initial
236 arguments are not recognized---it's too late to execute them anyway.
238 Note that resuming Emacs (with or without arguments) must be done from
239 within the shell that is the parent of the Emacs job. This is why
240 @code{edit} is an alias rather than a program or a shell script. It is
241 not possible to implement a resumption command that could be run from
242 other subjobs of the shell; no way to define a command that could be
243 made the value of @env{EDITOR}, for example. Therefore, this feature
244 does not take the place of the Emacs Server feature (@pxref{Emacs
247 The aliases use the Emacs Server feature if you appear to have a
248 server Emacs running. However, they cannot determine this with complete
249 accuracy. They may think that a server is still running when in
250 actuality you have killed that Emacs, because the file
251 @file{/tmp/.esrv@dots{}} still exists. If this happens, find that
255 @appendixsec Environment Variables
256 @cindex environment variables
258 This appendix describes how Emacs uses environment variables. An
259 environment variable is a string passed from the operating system to
260 Emacs, and the collection of environment variables is known as the
261 environment. Environment variable names are case sensitive and it is
262 conventional to use upper case letters only.
264 Because environment variables come from the operating system there is no
265 general way to set them; it depends on the operating system and
266 especially the shell that you are using. For example, here's how to set
267 the environment variable @env{ORGANIZATION} to @samp{not very much}
271 export ORGANIZATION="not very much"
275 and here's how to do it in csh or tcsh:
278 setenv ORGANIZATION "not very much"
281 When Emacs is set-up to use the X windowing system, it inherits the
282 use of a large number of environment variables from the X library. See
283 the X documentation for more information.
285 The command @kbd{M-x setenv} sets a variable in the environment of the
286 Emacs process and its subprocesses and @kbd{M-x getenv} gets the value
290 * General Variables:: Environment variables that all versions of Emacs use.
291 * Misc Variables:: Certain system-specific variables.
294 @node General Variables
295 @appendixsubsec General Variables
299 The name of a file used to archive news articles posted with the @sc{gnus}
302 Used by the @code{cd} command to search for the directory you specify,
303 when you specify a relative directory name.
305 The name of the Internet domain that the machine running Emacs is
306 located in. Used by the @sc{gnus} package.
308 @cindex unibyte operation
309 Defining this environment variable directs Emacs to do almost everything
310 with single-byte buffers and strings. It is equivalent to using the
311 @samp{--unibyte} command-line option on each invocation. @xref{Initial
314 Used to initialize the variable @code{data-directory} used to locate the
315 architecture-independent files that come with Emacs. Setting this
316 variable overrides the setting in @file{paths.h} when Emacs was built.
318 A colon-separated list of directories from which to load Emacs Lisp
319 files. Setting this variable overrides the setting in @file{paths.h}
320 when Emacs was built.
322 The directory that Emacs places lock files---files used to protect
323 users from editing the same files simultaneously. Setting this variable
324 overrides the setting in @file{paths.h} when Emacs was built.
326 The location of Emacs-specific binaries. Setting this variable
327 overrides the setting in @file{paths.h} when Emacs was built.
329 Used for shell-mode to override the @env{SHELL} environment variable.
331 The name of the file that shell commands are saved in between logins.
332 This variable defaults to @file{~/.history} if you use (t)csh as shell,
333 to @file{~/.bash_history} if you use bash, to @file{~/.sh_history} if
334 you use ksh, and to @file{~/.history} otherwise.
336 The location of the user's files in the directory tree; used for
337 expansion of file names starting with a tilde (@file{~}). On MS-DOS, it
338 defaults to the directory from which Emacs was started, with @samp{/bin}
339 removed from the end if it was present.
341 The name of the machine that Emacs is running on.
343 A colon-separated list of directories. Used by the @code{complete} package
346 A colon-separated list of directories holding info files. Setting this
347 variable overrides the setting in @file{paths.el} when Emacs was built.
351 @findex set-locale-environment
352 @vindex locale-language-names
353 @vindex locale-charset-language-names
354 @vindex locale-preferred-coding-systems
355 The user's locale, matched by @code{set-locale-environment} against
356 entries in @code{locale-language-names},
357 @code{locale-charset-language-names}, and
358 @code{locale-preferred-coding-systems} to select a default language
359 environment and coding system. The first of these environment variables
360 with a nonempty value specifies the locale.
362 The user's login name. See also @env{USER}.
364 The name of the user's system mail inbox.
366 Name of file containing mail aliases. This defaults to
369 Name of setup file for the mh system. This defaults to
370 @file{~/.mh_profile}.
372 The real-world name of the user.
374 The name of the news server. Used by the mh and @sc{gnus} packages.
376 The name of the organization to which you belong. Used for setting the
377 `Organization:' header in your posts from the @sc{gnus} package.
379 A colon-separated list of directories in which executables reside. (On
380 MS-DOS, it is semicolon-separated instead.) This variable is used to
381 set the Emacs Lisp variable @code{exec-path} which you should consider
384 If set, this should be the default directory when Emacs was started.
386 If set, this specifies an initial value for the variable
387 @code{mail-default-reply-to}. @xref{Mail Headers}.
389 The name of a directory in which news articles are saved by default.
390 Used by the @sc{gnus} package.
392 The name of an interpreter used to parse and execute programs run from
395 The name of the terminal that Emacs is running on. The variable must be
396 set unless Emacs is run in batch mode. On MS-DOS, it defaults to
397 @samp{internal}, which specifies a built-in terminal emulation that
398 handles the machine's own display.
400 The name of the termcap library file describing how to program the
401 terminal specified by the @env{TERM} variable. This defaults to
404 Used by the Emerge package as a prefix for temporary files.
406 This specifies the current time zone and possibly also daylight savings
407 information. On MS-DOS, the default is based on country code; see the
408 file @file{msdos.c} for details.
410 The user's login name. See also @env{LOGNAME}. On MS-DOS, this
411 defaults to @samp{root}.
412 @item VERSION_CONTROL
413 Used to initialize the @code{version-control} variable (@pxref{Backup
418 @appendixsubsec Miscellaneous Variables
420 These variables are used only on particular configurations:
424 On MS-DOS, the name of the command interpreter to use. This is used to
425 make a default value for the @env{SHELL} environment variable.
428 On MS-DOS, this variable defaults to the value of the @env{USER}
433 On MS-DOS, these specify the name of the directory for storing temporary
437 On MS-DOS, this specifies a file to use to log the operation of the
438 internal terminal emulator. This feature is useful for submitting bug
442 Used on MS-DOS systems to set screen colors early, so that the screen
443 won't momentarily flash the default colors when Emacs starts up. The
444 value of this variable should be two-character encoding of the
445 foreground (the first character) and the background (the second
446 character) colors of the default face. Each character should be the
447 hexadecimal code for the desired color on a standard PC text-mode
450 The PC display usually supports only eight background colors. However,
451 Emacs switches the DOS display to a mode where all 16 colors can be used
452 for the background, so all four bits of the background color are
456 Used when initializing the Sun windows system.
460 @appendixsec Specifying the Display Name
461 @cindex display name (X Windows)
462 @cindex @env{DISPLAY} environment variable
464 The environment variable @env{DISPLAY} tells all X clients, including
465 Emacs, where to display their windows. Its value is set up by default
466 in ordinary circumstances, when you start an X server and run jobs
467 locally. Occasionally you may need to specify the display yourself; for
468 example, if you do a remote login and want to run a client program
469 remotely, displaying on your local screen.
471 With Emacs, the main reason people change the default display is to
472 let them log into another system, run Emacs on that system, but have the
473 window displayed at their local terminal. You might need to use login
474 to another system because the files you want to edit are there, or
475 because the Emacs executable file you want to run is there.
477 The syntax of the @env{DISPLAY} environment variable is
478 @samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the
479 host name of the X Window System server machine, @var{display} is an
480 arbitrarily-assigned number that distinguishes your server (X terminal)
481 from other servers on the same machine, and @var{screen} is a
482 rarely-used field that allows an X server to control multiple terminal
483 screens. The period and the @var{screen} field are optional. If
484 included, @var{screen} is usually zero.
486 For example, if your host is named @samp{glasperle} and your server is
487 the first (or perhaps the only) server listed in the configuration, your
488 @env{DISPLAY} is @samp{glasperle:0.0}.
490 You can specify the display name explicitly when you run Emacs, either
491 by changing the @env{DISPLAY} variable, or with the option @samp{-d
492 @var{display}} or @samp{--display=@var{display}}. Here is an example:
495 emacs --display=glasperle:0 &
498 You can inhibit the direct use of X with the @samp{-nw} option. This
499 is also an initial option. It tells Emacs to display using ordinary
500 ASCII on its controlling terminal.
502 Sometimes, security arrangements prevent a program on a remote system
503 from displaying on your local system. In this case, trying to run Emacs
504 produces messages like this:
507 Xlib: connection to "glasperle:0.0" refused by server
511 You might be able to overcome this problem by using the @code{xhost}
512 command on the local system to give permission for access from your
516 @appendixsec Font Specification Options
517 @cindex font name (X Windows)
519 By default, Emacs displays text in the font named @samp{9x15}, which
520 makes each character nine pixels wide and fifteen pixels high. You can
521 specify a different font on your command line through the option
522 @samp{-fn @var{name}}.
526 Use font @var{name} as the default font.
528 @item --font=@var{name}
529 @samp{--font} is an alias for @samp{-fn}.
532 Under X, each font has a long name which consists of eleven words or
533 numbers, separated by dashes. Some fonts also have shorter
534 nicknames---@samp{9x15} is such a nickname. You can use either kind of
535 name. You can use wildcard patterns for the font name; then Emacs lets
536 X choose one of the fonts that match the pattern. Here is an example,
537 which happens to specify the font whose nickname is @samp{6x13}:
540 emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" &
544 You can also specify the font in your @file{.Xdefaults} file:
547 emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
550 A long font name has the following form:
553 -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
554 @dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset}
559 This is the name of the font family---for example, @samp{courier}.
561 This is normally @samp{bold}, @samp{medium} or @samp{light}. Other
562 words may appear here in some font names.
564 This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique),
565 @samp{ri} (reverse italic), or @samp{ot} (other).
567 This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed}
568 or @samp{normal}. Other words may appear here in some font names.
570 This is an optional additional style name. Usually it is empty---most
571 long font names have two hyphens in a row at this point.
573 This is the font height, in pixels.
575 This is the font height on the screen, measured in tenths of a printer's
576 point---approximately 1/720 of an inch. In other words, it is the point
577 size of the font, times ten. For a given vertical resolution,
578 @var{height} and @var{pixels} are proportional; therefore, it is common
579 to specify just one of them and use @samp{*} for the other.
581 This is the horizontal resolution, in pixels per inch, of the screen for
582 which the font is intended.
584 This is the vertical resolution, in dots per inch, of the screen for
585 which the font is intended. Normally the resolution of the fonts on
586 your system is the right value for your screen; therefore, you normally
587 specify @samp{*} for this and @var{horiz}.
589 This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c}
590 (character cell). Emacs can use @samp{m} and @samp{c} fonts.
592 This is the average character width, in pixels, multiplied by ten.
594 This is the character set that the font depicts.
595 Normally you should use @samp{iso8859-1}.
598 Use only fixed-width fonts---that is, fonts in which all characters
599 have the same width; Emacs cannot yet handle display properly for
600 variable-width fonts. Any font with @samp{m} or @samp{c} in the
601 @var{spacing} field of the long name is a fixed-width font. Here's how
602 to use the @code{xlsfonts} program to list all the fixed-width fonts
603 available on your system:
606 xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"
607 xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
608 xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'
612 To see what a particular font looks like, use the @code{xfd} command.
620 displays the entire font @samp{6x13}.
622 While running Emacs, you can set the font of the current frame
623 (@pxref{Frame Parameters}) or for a specific kind of text
627 @appendixsec Window Color Options
628 @cindex color of window (X Windows)
630 On a color display, you can specify which color to use for various
631 parts of the Emacs display. To find out what colors are available on
632 your system, look at the @file{/usr/lib/X11/rgb.txt} file. If you do
633 not specify colors, the default for the background is white and the
634 default for all other colors is black. On a monochrome display, the
635 foreground is black, the background is white, and the border is gray if
636 the display supports that.
638 Here is a list of the options for specifying colors:
641 @item -fg @var{color}
642 @itemx --foreground-color=@var{color}
643 Specify the foreground color.
644 @item -bg @var{color}
645 @itemx --background-color=@var{color}
646 Specify the background color.
647 @item -bd @var{color}
648 @itemx --border-color=@var{color}
649 Specify the color of the border of the X window.
650 @item -cr @var{color}
651 @itemx --cursor-color=@var{color}
652 Specify the color of the Emacs cursor which indicates where point is.
653 @item -ms @var{color}
654 @itemx --mouse-color=@var{color}
655 Specify the color for the mouse cursor when the mouse is in the Emacs window.
657 @itemx --reverse-video
658 Reverse video---swap the foreground and background colors.
661 For example, to use a coral mouse cursor and a slate blue text cursor,
665 emacs -ms coral -cr 'slate blue' &
668 You can reverse the foreground and background colors through the
669 @samp{-r} option or with the X resource @samp{reverseVideo}.
672 @appendixsec Options for Window Geometry
673 @cindex geometry (X Windows)
675 The @samp{-geometry} option controls the size and position of the
676 initial Emacs frame. Here is the format for specifying the window
680 @item -g @var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
681 Specify window size @var{width} and @var{height} (measured in character
682 columns and lines), and positions @var{xoffset} and @var{yoffset}
683 (measured in pixels).
685 @item --geometry=@var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
686 This is another way of writing the same thing.
690 @code{@r{@{}+-@r{@}}} means either a plus sign or a minus sign. A plus
691 sign before @var{xoffset} means it is the distance from the left side of
692 the screen; a minus sign means it counts from the right side. A plus
693 sign before @var{yoffset} means it is the distance from the top of the
694 screen, and a minus sign there indicates the distance from the bottom.
695 The values @var{xoffset} and @var{yoffset} may themselves be positive or
696 negative, but that doesn't change their meaning, only their direction.
698 Emacs uses the same units as @code{xterm} does to interpret the geometry.
699 The @var{width} and @var{height} are measured in characters, so a large font
700 creates a larger frame than a small font. The @var{xoffset} and
701 @var{yoffset} are measured in pixels.
703 Since the mode line and the echo area occupy the last 2 lines of the
704 frame, the height of the initial text window is 2 less than the height
705 specified in your geometry. In non-X-toolkit versions of Emacs,
706 the menu bar also takes one line of the specified number.
708 You do not have to specify all of the fields in the geometry
711 If you omit both @var{xoffset} and @var{yoffset}, the window manager
712 decides where to put the Emacs frame, possibly by letting you place
713 it with the mouse. For example, @samp{164x55} specifies a window 164
714 columns wide, enough for two ordinary width windows side by side, and 55
717 The default width for Emacs is 80 characters and the default height is
718 40 lines. You can omit either the width or the height or both. If
719 you start the geometry with an integer, Emacs interprets it as the
720 width. If you start with an @samp{x} followed by an integer, Emacs
721 interprets it as the height. Thus, @samp{81} specifies just the width;
722 @samp{x45} specifies just the height.
724 If you start with @samp{+} or @samp{-}, that introduces an offset,
725 which means both sizes are omitted. Thus, @samp{-3} specifies the
726 @var{xoffset} only. (If you give just one offset, it is always
727 @var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the
728 @var{yoffset}, placing the frame near the bottom left of the screen.
730 You can specify a default for any or all of the fields in
731 @file{.Xdefaults} file, and then override selected fields with a
732 @samp{--geometry} option.
735 @appendixsec Internal and External Borders
736 @cindex borders (X Windows)
738 An Emacs frame has an internal border and an external border. The
739 internal border is an extra strip of the background color around all
740 four edges of the frame. Emacs itself adds the internal border. The
741 external border is added by the window manager outside the internal
742 border; it may contain various boxes you can click on to move or iconify
746 @item -ib @var{width}
747 @itemx --internal-border=@var{width}
748 Specify @var{width} as the width of the internal border.
750 @item -bw @var{width}
751 @itemx --border-width=@var{width}
752 Specify @var{width} as the width of the main border.
755 When you specify the size of the frame, that does not count the
756 borders. The frame's position is measured from the outside edge of the
759 Use the @samp{-ib @var{n}} option to specify an internal border
760 @var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to
761 specify the width of the external border (though the window manager may
762 not pay attention to what you specify). The default width of the
763 external border is 2.
766 @appendixsec Frame Titles
768 An Emacs frame may or may not have a specified title. The frame
769 title, if specified, appears in window decorations and icons as the name
770 of the frame. If an Emacs frame has no specified title, the default
771 title is the name of the executable program (if there is only one frame)
772 or the selected window's buffer name (if there is more than one frame).
774 You can specify a title for the initial Emacs frame with a command
778 @item -title @var{title}
779 @itemx --title=@var{title}
780 @itemx -T @var{title}
781 Specify @var{title} as the title for the initial Emacs frame.
784 The @samp{--name} option (@pxref{Resources X}) also specifies the title
785 for the initial Emacs frame.
789 @cindex icons (X Windows)
791 Most window managers allow the user to ``iconify'' a frame, removing
792 it from sight, and leaving a small, distinctive ``icon'' window in its
793 place. Clicking on the icon window makes the frame itself appear again.
794 If you have many clients running at once, you can avoid cluttering up
795 the screen by iconifying most of the clients.
800 Use a picture of a gnu as the Emacs icon.
804 Start Emacs in iconified state.
807 The @samp{-i} or @samp{--icon-type} option tells Emacs to use an icon
808 window containing a picture of the GNU gnu. If omitted, Emacs lets the
809 window manager choose what sort of icon to use---usually just a small
810 rectangle containing the frame's title.
812 The @samp{-iconic} option tells Emacs to begin running as an icon,
813 rather than opening a frame right away. In this situation, the icon
814 window provides only indication that Emacs has started; the usual text
815 frame doesn't appear until you deiconify it.
818 @appendixsec X Resources
821 Programs running under the X Window System organize their user options
822 under a hierarchy of classes and resources. You can specify default
823 values for these options in your X resources file, usually named
826 Each line in the file specifies a value for one option or for a
827 collection of related options, for one program or for several programs
828 (optionally even for all programs).
830 Programs define named resources with particular meanings. They also
831 define how to group resources into named classes. For instance, in
832 Emacs, the @samp{internalBorder} resource controls the width of the
833 internal border, and the @samp{borderWidth} resource controls the width
834 of the external border. Both of these resources are part of the
835 @samp{BorderWidth} class. Case distinctions are significant in these
838 In @file{~/.Xdefaults}, you can specify a value for a single resource
839 on one line, like this:
846 Or you can use a class name to specify the same value for all resources
847 in that class. Here's an example:
853 If you specify a value for a class, it becomes the default for all
854 resources in that class. You can specify values for individual
855 resources as well; these override the class value, for those particular
856 resources. Thus, this example specifies 2 as the default width for all
857 borders, but overrides this value with 4 for the external border:
864 The order in which the lines appear in the file does not matter.
865 Also, command-line options always override the X resources file.
867 The string @samp{emacs} in the examples above is also a resource
868 name. It actually represents the name of the executable file that you
869 invoke to run Emacs. If Emacs is installed under a different name, it
870 looks for resources under that name instead of @samp{emacs}.
873 @item -name @var{name}
874 @itemx --name=@var{name}
875 Use @var{name} as the resource name (and the title) for the initial
876 Emacs frame. This option does not affect subsequent frames, but Lisp
877 programs can specify frame names when they create frames.
879 If you don't specify this option, the default is to use the Emacs
880 executable's name as the resource name.
882 @item -xrm @var{resource-values}
883 @itemx --xrm=@var{resource-values}
884 Specify X resource values for this Emacs job (see below).
887 For consistency, @samp{-name} also specifies the name to use for
888 other resource values that do not belong to any particular frame.
890 The resources that name Emacs invocations also belong to a class; its
891 name is @samp{Emacs}. If you write @samp{Emacs} instead of
892 @samp{emacs}, the resource applies to all frames in all Emacs jobs,
893 regardless of frame titles and regardless of the name of the executable
894 file. Here is an example:
901 You can specify a string of additional resource values for Emacs to
902 use with the command line option @samp{-xrm @var{resources}}. The text
903 @var{resources} should have the same format that you would use inside a file
904 of X resources. To include multiple resource specifications in
905 @var{data}, put a newline between them, just as you would in a file.
906 You can also use @samp{#include "@var{filename}"} to include a file full
907 of resource specifications. Resource values specified with @samp{-xrm}
908 take precedence over all other resource specifications.
910 The following table lists the resource names that designate options
911 for Emacs, each with the class that it belongs to:
914 @item @code{background} (class @code{Background})
915 Background color name.
917 @item @code{bitmapIcon} (class @code{BitmapIcon})
918 Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
919 manager choose an icon if @samp{off}.
921 @item @code{borderColor} (class @code{BorderColor})
922 Color name for the external border.
924 @item @code{borderWidth} (class @code{BorderWidth})
925 Width in pixels of the external border.
927 @item @code{cursorColor} (class @code{Foreground})
928 Color name for text cursor (point).
930 @item @code{font} (class @code{Font})
931 Font name for text (or fontset name, @pxref{Fontsets}).
933 @item @code{foreground} (class @code{Foreground})
936 @item @code{geometry} (class @code{Geometry})
937 Window size and position. Be careful not to specify this resource as
938 @samp{emacs*geometry}, because that may affect individual menus as well
939 as the Emacs frame itself.
941 If this resource specifies a position, that position applies only to the
942 initial Emacs frame (or, in the case of a resource for a specific frame
943 name, only that frame). However, the size if specified here applies to
946 @item @code{iconName} (class @code{Title})
947 Name to display in the icon.
949 @item @code{internalBorder} (class @code{BorderWidth})
950 Width in pixels of the internal border.
952 @item @code{lineSpacing} (class LineSpacing)
955 Additional space (@dfn{leading}) between lines in pixels.
957 @item @code{menuBar} (class @code{MenuBar})
958 Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}.
960 @item @code{minibuffer} (class @code{Minibuffer})
961 If @samp{none}, don't make a minibuffer in this frame.
962 It will use a separate minibuffer frame instead.
964 @item @code{paneFont} (class @code{Font})
965 Font name for menu pane titles, in non-toolkit versions of Emacs.
967 @item @code{pointerColor} (class @code{Foreground})
968 Color of the mouse cursor.
970 @item @code{privateColormap} (class @code{PrivateColormap})
971 Specify that Emacs should use a private colormap if it is using the
972 default visual, and that visual is of class PseudoColor. Recognized
973 resource values are @samp{true} and @samp{on}.
975 @item @code{reverseVideo} (class @code{ReverseVideo})
976 Switch foreground and background default colors if @samp{on}, use colors as
977 specified if @samp{off}.
979 @item @code{screenGamma} (class @code{ScreenGamma})
980 @cindex gamma correction
981 Specify the gamma correction for colors, equivalent to the frame
982 parameter @code{screen-gamma}.
984 @item @code{selectionFont} (class @code{Font})
985 Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
986 toolkit versions, see @ref{Lucid Resources}, also see @ref{Motif
989 @item @code{synchronous} (class @code{Synchronous})
990 Specify whether Emacs should run in synchronous mode if @samp{true}.
991 Synchronous mode is useful for debugging X problems.
993 @item @code{title} (class @code{Title})
994 Name to display in the title bar of the initial Emacs frame.
996 @item @code{verticalScrollBars} (class @code{ScrollBars})
997 Give frames scroll bars if @samp{on}; don't have scroll bars if
1000 @item @code{visualClass} (class @code{VisualClass})
1001 Specify the visual Emacs should use. The resource's value should be a
1002 string of the form @samp{@var{CLASS}-@var{DEPTH}}, where @var{class} is
1003 the name of the visual class, and @var{depth} is the requested color
1004 depth as a decimal number. Valid visual class names are
1005 @samp{TrueColor}, @samp{PseudoColor}, @samp{DirectColor},
1006 @samp{StaticColor}, @samp{GrayScale} and @samp{StaticGray}.
1008 Visual class names specified as X resource are case-insensitive, i.e.@:
1009 @samp{pseudocolor}, @samp{Pseudocolor} and @samp{PseudoColor} all have
1013 The program @command{xdpyinfo} can be used to list the visual classes
1014 supported on your display, and which depths they have. If
1015 @code{visualClass} is not specified, Emacs uses the display's default
1019 Here are resources for controlling the appearance of particular faces
1023 @item @var{face}.attributeFont
1024 Font for face @var{face}.
1025 @item @var{face}.attributeForeground
1026 Foreground color for face @var{face}.
1027 @item @var{face}.attributeBackground
1028 Background color for face @var{face}.
1029 @item @var{face}.attributeUnderline
1030 Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
1034 @node Lucid Resources
1035 @section Lucid Menu X Resources
1036 @cindex Menu X Resources (Lucid widgets)
1037 @cindex Lucid Widget X Resources
1039 If the Emacs installed at your site was built to use the X toolkit
1040 with the Lucid menu widgets, then the menu bar is a separate widget and
1041 has its own resources. The resource names contain @samp{pane.menubar}
1042 (following, as always, the name of the Emacs invocation or @samp{Emacs}
1043 which stands for all Emacs invocations). Specify them like this:
1046 Emacs.pane.menubar.@var{resource}: @var{value}
1050 For example, to specify the font @samp{8x16} for the menu-bar items,
1054 Emacs.pane.menubar.font: 8x16
1058 Resources for @emph{non-menubar} toolkit pop-up menus have
1059 @samp{menu*}, in like fashion. For example, to specify the font
1060 @samp{8x16} for the pop-up menu items, write this:
1063 Emacs.menu*.font: 8x16
1067 For dialog boxes, use @samp{dialog} instead of @samp{menu}:
1070 Emacs.dialog*.font: 8x16
1074 Experience shows that on some systems you may need to add
1075 @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
1076 some other systems, you must not add @samp{shell.}.
1078 Here is a list of the specific resources for menu bars and pop-up menus:
1082 Font for menu item text.
1084 Color of the foreground.
1086 Color of the background.
1087 @item buttonForeground
1088 In the menu bar, the color of the foreground for a selected item.
1089 @item horizontalSpacing
1090 Horizontal spacing in pixels between items. Default is 3.
1091 @item verticalSpacing
1092 Vertical spacing in pixels between items. Default is 1.
1094 Horizontal spacing between the arrow (which indicates a submenu) and
1095 the associated text. Default is 10.
1096 @item shadowThickness
1097 Thickness of shadow line around the widget.
1100 @node Motif Resources
1101 @section Motif Menu X Resources
1102 @cindex Menu X Resources (Motif widgets)
1103 @cindex Motif Widget X Resources
1105 If the Emacs installed at your site was built to use the X toolkit
1106 with the Motif widgets, then the menu bar is a separate widget and has
1107 its own resources. The resource names contain @samp{pane.menubar}
1108 (following, as always, the name of the Emacs invocation or @samp{Emacs}
1109 which stands for all Emacs invocations). Specify them like this:
1112 Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value}
1115 Each individual string in the menu bar is a subwidget; the subwidget's
1116 name is the same as the menu item string. For example, the word
1117 @samp{Files} in the menu bar is part of a subwidget named
1118 @samp{emacs.pane.menubar.Files}. Most likely, you want to specify the
1119 same resources for the whole menu bar. To do this, use @samp{*} instead
1120 of a specific subwidget name. For example, to specify the font
1121 @samp{8x16} for the menu-bar items, write this:
1124 Emacs.pane.menubar.*.fontList: 8x16
1128 This also specifies the resource value for submenus.
1130 Each item in a submenu in the menu bar also has its own name for X
1131 resources; for example, the @samp{Files} submenu has an item named
1132 @samp{Save Buffer}. A resource specification for a submenu item looks
1136 Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
1140 For example, here's how to specify the font for the @samp{Save Buffer}
1144 Emacs.pane.menubar.popup_*.Files.Save Buffer.fontList: 8x16
1148 For an item in a second-level submenu, such as @samp{Check Message}
1149 under @samp{Spell} under @samp{Edit}, the resource fits this template:
1152 Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
1159 Emacs.pane.menubar.popup_*.popup_*.Spell.Check Message: @var{value}
1162 It's impossible to specify a resource for all the menu-bar items
1163 without also specifying it for the submenus as well. So if you want the
1164 submenu items to look different from the menu bar itself, you must ask
1165 for that in two steps. First, specify the resource for all of them;
1166 then, override the value for submenus alone. Here is an example:
1169 Emacs.pane.menubar.*.fontList: 8x16
1170 Emacs.pane.menubar.popup_*.fontList: 8x16
1174 For toolkit pop-up menus, use @samp{menu*} instead of
1175 @samp{pane.menubar}. For example, to specify the font @samp{8x16} for
1176 the pop-up menu items, write this:
1179 Emacs.menu*.fontList: 8x16
1185 Here is a list of the specific resources for menu bars and pop-up menus:
1189 The color to show in an armed button.
1198 Amount of space to leave around the item, within the border.
1200 The width of border around the menu item, on all sides.
1201 @item shadowThickness
1202 The width of the border shadow.
1203 @item bottomShadowColor
1204 The color for the border shadow, on the bottom and the right.
1205 @item topShadowColor
1206 The color for the border shadow, on the top and the left.