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:
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 Emacs
191 always loads Lisp files in multibyte mode, even if @samp{--unibyte} is
192 specified; see @ref{Enabling Multibyte}.) Setting the environment
193 variable @env{EMACS_UNIBYTE} has the same effect.
196 Inhibit the effect of @env{EMACS_UNIBYTE}, so that Emacs
197 uses multibyte characters by default, as usual.
200 @node Command Example
201 @appendixsec Command Argument Example
203 Here is an example of using Emacs with arguments and options. It
204 assumes you have a Lisp program file called @file{hack-c.el} which, when
205 loaded, performs some useful operation on the current buffer, expected
209 emacs -batch foo.c -l hack-c -f save-buffer >& log
213 This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
214 changes in the visited file), save @file{foo.c} (note that
215 @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
216 then exit back to the shell (because of @samp{-batch}). @samp{-batch}
217 also guarantees there will be no problem redirecting output to
218 @file{log}, because Emacs will not assume that it has a display terminal
221 @node Resume Arguments
222 @appendixsec Resuming Emacs with Arguments
224 You can specify action arguments for Emacs when you resume it after
225 a suspension. To prepare for this, put the following code in your
226 @file{.emacs} file (@pxref{Hooks}):
229 (add-hook 'suspend-hook 'resume-suspend-hook)
230 (add-hook 'suspend-resume-hook 'resume-process-args)
233 As further preparation, you must execute the shell script
234 @file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash} (if
235 you use bash as your shell). These scripts define an alias named
236 @code{edit}, which will resume Emacs giving it new command line
237 arguments such as files to visit.
239 Only action arguments work properly when you resume Emacs. Initial
240 arguments are not recognized---it's too late to execute them anyway.
242 Note that resuming Emacs (with or without arguments) must be done from
243 within the shell that is the parent of the Emacs job. This is why
244 @code{edit} is an alias rather than a program or a shell script. It is
245 not possible to implement a resumption command that could be run from
246 other subjobs of the shell; no way to define a command that could be
247 made the value of @env{EDITOR}, for example. Therefore, this feature
248 does not take the place of the Emacs Server feature (@pxref{Emacs
251 The aliases use the Emacs Server feature if you appear to have a
252 server Emacs running. However, they cannot determine this with complete
253 accuracy. They may think that a server is still running when in
254 actuality you have killed that Emacs, because the file
255 @file{/tmp/.esrv@dots{}} still exists. If this happens, find that
259 @appendixsec Environment Variables
260 @cindex environment variables
262 The @dfn{environment} is a feature of the operating system; it
263 consists of a collection of variables with names and values. Each
264 variable is called an @dfn{environment variable}; environment variable
265 names are case-sensitive, and it is conventional to use upper case
266 letters only. The values are all text strings.
268 What makes the environment useful is that subprocesses inherit the
269 environment automatically from their parent process. This means you
270 can set up an environment variable in your login shell, and all the
271 programs you run (including Emacs) will automatically see it.
272 Subprocesses of Emacs (such as shells, compilers, and version-control
273 software) inherit the environment from Emacs, too.
277 Inside Emacs, the command @kbd{M-x getenv} gets the value of an
278 environment variable. @kbd{M-x setenv} sets a variable in the Emacs
279 environment. The way to set environment variables outside of Emacs
280 depends on the operating system, and especially the shell that you are
281 using. For example, here's how to set the environment variable
282 @env{ORGANIZATION} to @samp{not very much} using Bash:
285 export ORGANIZATION="not very much"
289 and here's how to do it in csh or tcsh:
292 setenv ORGANIZATION "not very much"
295 When Emacs is set-up to use the X Window System, it inherits the use
296 of a large number of environment variables from the X libraries. See
297 the X documentation for more information.
300 * General Variables:: Environment variables that all versions of Emacs use.
301 * Misc Variables:: Certain system-specific variables.
304 @node General Variables
305 @appendixsubsec General Variables
307 Here is an alphabetical list of specific environment variables that
308 have special meanings in Emacs, giving the name of each variable and
309 its meaning. Most of these variables are also used by some other
310 programs. Emacs does not require any of these environment variables
311 to be set, but it uses their values if they are set.
315 Used by the @code{cd} command to search for the directory you specify,
316 when you specify a relative directory name.
318 The name of the Internet domain that the machine running Emacs is
319 located in. Used by the Gnus package.
321 @cindex unibyte operation, environment variable
322 Defining this environment variable with a nonempty value directs Emacs
323 to do almost everything with single-byte buffers and strings. It is
324 equivalent to using the @samp{--unibyte} command-line option on each
325 invocation. @xref{Initial Options}.
327 Directory for the architecture-independent files that come with Emacs.
328 This is used to initialize the Lisp variable @code{data-directory}.
330 Directory for the documentation string file,
331 @file{DOC-@var{emacsversion}}. This is used to initialize the Lisp
332 variable @code{doc-directory}.
334 A colon-separated list of directories@footnote{
335 Here and below, whenever we say ``colon-separated list of directories'',
336 it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows,
337 the directories are separated by semi-colons instead, since DOS/Windows
338 file names might include a colon after a drive letter.}
339 to search for Emacs Lisp files---used to initialize @code{load-path}.
341 A colon-separated list of directories to search for executable
342 files---used to initialize @code{exec-path}.
344 Used for shell-mode to override the @env{SHELL} environment variable.
346 The name of the file that shell commands are saved in between logins.
347 This variable defaults to @file{~/.bash_history} if you use Bash, to
348 @file{~/.sh_history} if you use ksh, and to @file{~/.history}
351 The location of the user's files in the directory tree; used for
352 expansion of file names starting with a tilde (@file{~}). On MS-DOS, it
353 defaults to the directory from which Emacs was started, with @samp{/bin}
354 removed from the end if it was present. On Windows, the default value
355 of @code{HOME} is @file{C:/}, the root directory of drive @file{C:}.
357 The name of the machine that Emacs is running on.
359 A colon-separated list of directories. Used by the @code{complete} package
362 A colon-separated list of directories in which to search for Info files.
366 The user's preferred locale. (The first of these environment
367 variables with a nonempty value specifies the locale.) A locale name
368 which contains @samp{8859-@var{n}}, @samp{8859_@var{n}} or
369 @samp{8859@var{n}}, where @var{n} is between 1 and 4, automatically
370 specifies the @samp{Latin-@var{n}} language environment when Emacs
371 starts up. There are a few extensions: if @var{n} is 9, that specifies
372 @samp{Latin-5}, and if @var{n} is 14 or 15, that specifies
373 @samp{Latin-8} and @samp{Latin-9}, respectively.
375 The locale value you specify with one of these three variables is
376 matched against entries in @code{locale-language-names},
377 @code{locale-charset-language-names}, and
378 @code{locale-preferred-coding-systems}, to select a default language
379 environment and coding system. @xref{Language Environments}.
381 The user's login name. See also @env{USER}.
383 The name of the user's system mail inbox.
385 Name of file containing mail aliases. (The default is
388 Name of setup file for the mh system. (The default is @file{~/.mh_profile}.)
390 The real-world name of the user.
392 The name of the news server. Used by the mh and Gnus packages.
394 The name of the organization to which you belong. Used for setting the
395 `Organization:' header in your posts from the Gnus package.
397 A colon-separated list of directories in which executables reside. This
398 is used to initialize the Emacs Lisp variable @code{exec-path}.
400 If set, this should be the default directory when Emacs was started.
402 If set, this specifies an initial value for the variable
403 @code{mail-default-reply-to}. @xref{Mail Headers}.
405 The name of a directory in which news articles are saved by default.
406 Used by the Gnus package.
408 The name of an interpreter used to parse and execute programs run from
410 @cindex background mode, on @code{xterm}
412 The name of the terminal that Emacs is running on. The variable must be
413 set unless Emacs is run in batch mode. On MS-DOS, it defaults to
414 @samp{internal}, which specifies a built-in terminal emulation that
415 handles the machine's own display. If the value of @env{TERM} indicates
416 that Emacs runs in non-windowed mode from @code{xterm} or a similar
417 terminal emulator, the background mode defaults to @samp{light}, and
418 Emacs will choose colors that are appropriate for a light background.
420 The name of the termcap library file describing how to program the
421 terminal specified by the @env{TERM} variable. This defaults to
424 Used by the Emerge package as a prefix for temporary files.
426 This specifies the current time zone and possibly also daylight
427 savings information. On MS-DOS, if @code{TZ} is not set in the
428 environment when Emacs starts, Emacs defines a default value as
429 appropriate for the country code returned by DOS. On MS-Windows, Emacs
430 does not use @code{TZ} at all.
432 The user's login name. See also @env{LOGNAME}. On MS-DOS, this
433 defaults to @samp{root}.
434 @item VERSION_CONTROL
435 Used to initialize the @code{version-control} variable (@pxref{Backup
440 @appendixsubsec Miscellaneous Variables
442 These variables are used only on particular configurations:
446 On MS-DOS and MS-Windows, the name of the command interpreter to use
447 when invoking batch files and commands internal to the shell. On MS-DOS
448 this is also used to make a default value for the @env{SHELL} environment
452 On MS-DOS, this variable defaults to the value of the @env{USER}
457 On MS-DOS and MS-Windows, these specify the name of the directory for
458 storing temporary files in.
461 On MS-DOS, this specifies a file to use to log the operation of the
462 internal terminal emulator. This feature is useful for submitting bug
466 On MS-DOS, this specifies the screen colors. It is useful to set them
467 this way, since otherwise Emacs would display the default colors
468 momentarily when it starts up.
470 The value of this variable should be the two-character encoding of the
471 foreground (the first character) and the background (the second
472 character) colors of the default face. Each character should be the
473 hexadecimal code for the desired color on a standard PC text-mode
474 display. For example, to get blue text on a lightgray backgraound,
475 specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and
476 7 is the code of the lightgray color.
478 The PC display usually supports only eight background colors. However,
479 Emacs switches the DOS display to a mode where all 16 colors can be used
480 for the background, so all four bits of the background color are
484 Used when initializing the Sun windows system.
488 @appendixsec Specifying the Display Name
489 @cindex display name (X Window System)
490 @cindex @env{DISPLAY} environment variable
492 The environment variable @env{DISPLAY} tells all X clients, including
493 Emacs, where to display their windows. Its value is set up by default
494 in ordinary circumstances, when you start an X server and run jobs
495 locally. Occasionally you may need to specify the display yourself; for
496 example, if you do a remote login and want to run a client program
497 remotely, displaying on your local screen.
499 With Emacs, the main reason people change the default display is to
500 let them log into another system, run Emacs on that system, but have the
501 window displayed at their local terminal. You might need to log in
502 to another system because the files you want to edit are there, or
503 because the Emacs executable file you want to run is there.
505 The syntax of the @env{DISPLAY} environment variable is
506 @samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the
507 host name of the X Window System server machine, @var{display} is an
508 arbitrarily-assigned number that distinguishes your server (X terminal)
509 from other servers on the same machine, and @var{screen} is a
510 rarely-used field that allows an X server to control multiple terminal
511 screens. The period and the @var{screen} field are optional. If
512 included, @var{screen} is usually zero.
514 For example, if your host is named @samp{glasperle} and your server is
515 the first (or perhaps the only) server listed in the configuration, your
516 @env{DISPLAY} is @samp{glasperle:0.0}.
518 You can specify the display name explicitly when you run Emacs, either
519 by changing the @env{DISPLAY} variable, or with the option @samp{-d
520 @var{display}} or @samp{--display=@var{display}}. Here is an example:
523 emacs --display=glasperle:0 &
526 You can inhibit the direct use of the window system and GUI with the
527 @samp{-nw} option. It tells Emacs to display using ordinary ASCII on
528 its controlling terminal. This is also an initial option.
530 Sometimes, security arrangements prevent a program on a remote system
531 from displaying on your local system. In this case, trying to run Emacs
532 produces messages like this:
535 Xlib: connection to "glasperle:0.0" refused by server
539 You might be able to overcome this problem by using the @code{xhost}
540 command on the local system to give permission for access from your
544 @appendixsec Font Specification Options
545 @cindex font name (X Window System)
547 By default, Emacs displays text in the font named @samp{9x15}, which
548 makes each character nine pixels wide and fifteen pixels high. You can
549 specify a different font on your command line through the option
550 @samp{-fn @var{name}} (or @samp{--font}, which is an alias for
555 @itemx --font=@var{name}
556 Use font @var{name} as the default font.
559 Under X, each font has a long name which consists of eleven words or
560 numbers, separated by dashes. Some fonts also have shorter
561 nicknames---@samp{9x15} is such a nickname. You can use either kind of
562 name. You can use wildcard patterns for the font name; then Emacs lets
563 X choose one of the fonts that match the pattern. Here is an example,
564 which happens to specify the font whose nickname is @samp{6x13}:
567 emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" &
571 You can also specify the font in your @file{.Xdefaults} file:
574 emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
577 A long font name has the following form:
580 -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
581 @dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset}
586 This is the name of the font manufacturer.
588 This is the name of the font family---for example, @samp{courier}.
590 This is normally @samp{bold}, @samp{medium} or @samp{light}. Other
591 words may appear here in some font names.
593 This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique),
594 @samp{ri} (reverse italic), or @samp{ot} (other).
596 This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed}
597 or @samp{normal}. Other words may appear here in some font names.
599 This is an optional additional style name. Usually it is empty---most
600 long font names have two hyphens in a row at this point.
602 This is the font height, in pixels.
604 This is the font height on the screen, measured in tenths of a printer's
605 point---approximately 1/720 of an inch. In other words, it is the point
606 size of the font, times ten. For a given vertical resolution,
607 @var{height} and @var{pixels} are proportional; therefore, it is common
608 to specify just one of them and use @samp{*} for the other.
610 This is the horizontal resolution, in pixels per inch, of the screen for
611 which the font is intended.
613 This is the vertical resolution, in pixels per inch, of the screen for
614 which the font is intended. Normally the resolution of the fonts on
615 your system is the right value for your screen; therefore, you normally
616 specify @samp{*} for this and @var{horiz}.
618 This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c}
621 This is the average character width, in pixels, multiplied by ten.
623 This is the character set that the font depicts.
624 Normally you should use @samp{iso8859-1}.
627 You will probably want to use a fixed-width default font---that is,
628 a font in which all characters have the same width. Any font with
629 @samp{m} or @samp{c} in the @var{spacing} field of the long name is a
630 fixed-width font. Here's how to use the @code{xlsfonts} program to
631 list all the fixed-width fonts available on your system:
634 xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"
635 xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
636 xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'
640 To see what a particular font looks like, use the @code{xfd} command.
648 displays the entire font @samp{6x13}.
650 While running Emacs, you can set the font of the current frame
651 (@pxref{Frame Parameters}) or for a specific kind of text
655 @appendixsec Window Color Options
656 @cindex color of window (X Window System)
657 @cindex text colors, from command line
659 @findex list-colors-display
660 @cindex available colors
661 On a color display, you can specify which color to use for various
662 parts of the Emacs display. To find out what colors are available on
663 your system, type @kbd{M-x list-colors-display}, or press
664 @kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu.
665 If you do not specify colors, on windowed displays the default for the
666 background is white and the default for all other colors is black. On a
667 monochrome display, the foreground is black, the background is white,
668 and the border is gray if the display supports that. On terminals, the
669 background is usually black and the foreground is white.
671 Here is a list of the command-line options for specifying colors:
674 @item -fg @var{color}
675 @itemx --foreground-color=@var{color}
676 Specify the foreground color. @var{color} should be a standard color
677 name, or a numeric specification of the color's red, green, and blue
678 components as in @samp{#4682B4} or @samp{RGB:46/82/B4}.
679 @item -bg @var{color}
680 @itemx --background-color=@var{color}
681 Specify the background color.
682 @item -bd @var{color}
683 @itemx --border-color=@var{color}
684 Specify the color of the border of the X window.
685 @item -cr @var{color}
686 @itemx --cursor-color=@var{color}
687 Specify the color of the Emacs cursor which indicates where point is.
688 @item -ms @var{color}
689 @itemx --mouse-color=@var{color}
690 Specify the color for the mouse cursor when the mouse is in the Emacs window.
692 @itemx --reverse-video
693 Reverse video---swap the foreground and background colors.
696 For example, to use a coral mouse cursor and a slate blue text cursor,
700 emacs -ms coral -cr 'slate blue' &
703 You can reverse the foreground and background colors through the
704 @samp{-r} option or with the X resource @samp{reverseVideo}.
706 The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on
707 character terminals as well as on window systems.
710 @appendixsec Options for Window Geometry
711 @cindex geometry (X Window System)
713 The @samp{-geometry} option controls the size and position of the
714 initial Emacs frame. Here is the format for specifying the window
718 @item -g @var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
719 Specify window size @var{width} and @var{height} (measured in character
720 columns and lines), and positions @var{xoffset} and @var{yoffset}
721 (measured in pixels).
723 @item --geometry=@var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
724 This is another way of writing the same thing.
728 @code{@r{@{}+-@r{@}}} means either a plus sign or a minus sign. A plus
729 sign before @var{xoffset} means it is the distance from the left side of
730 the screen; a minus sign means it counts from the right side. A plus
731 sign before @var{yoffset} means it is the distance from the top of the
732 screen, and a minus sign there indicates the distance from the bottom.
733 The values @var{xoffset} and @var{yoffset} may themselves be positive or
734 negative, but that doesn't change their meaning, only their direction.
736 Emacs uses the same units as @code{xterm} does to interpret the geometry.
737 The @var{width} and @var{height} are measured in characters, so a large font
738 creates a larger frame than a small font. The @var{xoffset}
739 and @var{yoffset} are measured in pixels.
741 Since the mode line and the echo area occupy the last 2 lines of the
742 frame, the height of the initial text window is 2 less than the height
743 specified in your geometry. In non-X-toolkit versions of Emacs, the
744 menu bar also takes one line of the specified number. But in the X
745 toolkit version, the menu bar is additional and does not count against
746 the specified height. The tool bar, if present, is also additional.
748 You do not have to specify all of the fields in the geometry
751 If you omit both @var{xoffset} and @var{yoffset}, the window manager
752 decides where to put the Emacs frame, possibly by letting you place
753 it with the mouse. For example, @samp{164x55} specifies a window 164
754 columns wide, enough for two ordinary width windows side by side, and 55
757 The default width for Emacs is 80 characters and the default height is
758 40 lines. You can omit either the width or the height or both. If
759 you start the geometry with an integer, Emacs interprets it as the
760 width. If you start with an @samp{x} followed by an integer, Emacs
761 interprets it as the height. Thus, @samp{81} specifies just the width;
762 @samp{x45} specifies just the height.
764 If you start with @samp{+} or @samp{-}, that introduces an offset,
765 which means both sizes are omitted. Thus, @samp{-3} specifies the
766 @var{xoffset} only. (If you give just one offset, it is always
767 @var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the
768 @var{yoffset}, placing the frame near the bottom left of the screen.
770 You can specify a default for any or all of the fields in
771 @file{.Xdefaults} file, and then override selected fields with a
772 @samp{--geometry} option.
775 @appendixsec Internal and External Borders
776 @cindex borders (X Window System)
778 An Emacs frame has an internal border and an external border. The
779 internal border is an extra strip of the background color around all
780 four edges of the frame. Emacs itself adds the internal border. The
781 external border is added by the window manager outside the internal
782 border; it may contain various boxes you can click on to move or iconify
786 @item -ib @var{width}
787 @itemx --internal-border=@var{width}
788 Specify @var{width} as the width of the internal border, in pixels.
790 @item -bw @var{width}
791 @itemx --border-width=@var{width}
792 Specify @var{width} as the width of the main border, in pixels.
795 When you specify the size of the frame, that does not count the
796 borders. The frame's position is measured from the outside edge of the
799 Use the @samp{-ib @var{n}} option to specify an internal border
800 @var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to
801 specify the width of the external border (though the window manager may
802 not pay attention to what you specify). The default width of the
803 external border is 2.
806 @appendixsec Frame Titles
808 An Emacs frame may or may not have a specified title. The frame
809 title, if specified, appears in window decorations and icons as the name
810 of the frame. If an Emacs frame has no specified title, the default
811 title is the name of the executable program (if there is only one frame)
812 or the selected window's buffer name (if there is more than one frame).
814 You can specify a title for the initial Emacs frame with a command
818 @item -title @var{title}
819 @itemx --title=@var{title}
820 @itemx -T @var{title}
821 Specify @var{title} as the title for the initial Emacs frame.
824 The @samp{--name} option (@pxref{Resources X}) also specifies the title
825 for the initial Emacs frame.
829 @cindex icons (X Window System)
831 Most window managers allow the user to ``iconify'' a frame, removing
832 it from sight, and leaving a small, distinctive ``icon'' window in its
833 place. Clicking on the icon window makes the frame itself appear again.
834 If you have many clients running at once, you can avoid cluttering up
835 the screen by iconifying most of the clients.
840 Use a picture of a gnu as the Emacs icon.
844 Start Emacs in iconified state.
847 The @samp{-i} or @samp{--icon-type} option tells Emacs to use an icon
848 window containing a picture of the GNU gnu. If omitted, Emacs lets the
849 window manager choose what sort of icon to use---usually just a small
850 rectangle containing the frame's title.
852 The @samp{-iconic} option tells Emacs to begin running as an icon,
853 rather than showing a frame right away. In this situation, the icon
854 is the only indication that Emacs has started; the text frame doesn't
855 appear until you deiconify it.
858 @appendixsec X Resources
861 Programs running under the X Window System organize their user options
862 under a hierarchy of classes and resources. You can specify default
863 values for these options in your X resources file, usually named
866 Each line in the file specifies a value for one option or for a
867 collection of related options, for one program or for several programs
868 (optionally even for all programs).
870 Programs define named resources with particular meanings. They also
871 define how to group resources into named classes. For instance, in
872 Emacs, the @samp{internalBorder} resource controls the width of the
873 internal border, and the @samp{borderWidth} resource controls the width
874 of the external border. Both of these resources are part of the
875 @samp{BorderWidth} class. Case distinctions are significant in these
878 In @file{~/.Xdefaults}, you can specify a value for a single resource
879 on one line, like this:
886 Or you can use a class name to specify the same value for all resources
887 in that class. Here's an example:
893 If you specify a value for a class, it becomes the default for all
894 resources in that class. You can specify values for individual
895 resources as well; these override the class value, for those particular
896 resources. Thus, this example specifies 2 as the default width for all
897 borders, but overrides this value with 4 for the external border:
904 The order in which the lines appear in the file does not matter.
905 Also, command-line options always override the X resources file.
907 The string @samp{emacs} in the examples above is also a resource
908 name. It actually represents the name of the executable file that you
909 invoke to run Emacs. If Emacs is installed under a different name, it
910 looks for resources under that name instead of @samp{emacs}.
913 @item -name @var{name}
914 @itemx --name=@var{name}
915 Use @var{name} as the resource name (and the title) for the initial
916 Emacs frame. This option does not affect subsequent frames, but Lisp
917 programs can specify frame names when they create frames.
919 If you don't specify this option, the default is to use the Emacs
920 executable's name as the resource name.
922 @item -xrm @var{resource-values}
923 @itemx --xrm=@var{resource-values}
924 Specify X resource values for this Emacs job (see below).
927 For consistency, @samp{-name} also specifies the name to use for
928 other resource values that do not belong to any particular frame.
930 The resources that name Emacs invocations also belong to a class; its
931 name is @samp{Emacs}. If you write @samp{Emacs} instead of
932 @samp{emacs}, the resource applies to all frames in all Emacs jobs,
933 regardless of frame titles and regardless of the name of the executable
934 file. Here is an example:
941 You can specify a string of additional resource values for Emacs to
942 use with the command line option @samp{-xrm @var{resources}}. The text
943 @var{resources} should have the same format that you would use inside a file
944 of X resources. To include multiple resource specifications in
945 @var{resources}, put a newline between them, just as you would in a file.
946 You can also use @samp{#include "@var{filename}"} to include a file full
947 of resource specifications. Resource values specified with @samp{-xrm}
948 take precedence over all other resource specifications.
950 The following table lists the resource names that designate options
951 for Emacs, each with the class that it belongs to:
954 @item @code{background} (class @code{Background})
955 Background color name.
957 @item @code{bitmapIcon} (class @code{BitmapIcon})
958 Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
959 manager choose an icon if @samp{off}.
961 @item @code{borderColor} (class @code{BorderColor})
962 Color name for the external border.
964 @item @code{borderWidth} (class @code{BorderWidth})
965 Width in pixels of the external border.
967 @item @code{cursorColor} (class @code{Foreground})
968 Color name for text cursor (point).
970 @item @code{font} (class @code{Font})
971 Font name for text (or fontset name, @pxref{Fontsets}).
973 @item @code{foreground} (class @code{Foreground})
976 @item @code{geometry} (class @code{Geometry})
977 Window size and position. Be careful not to specify this resource as
978 @samp{emacs*geometry}, because that may affect individual menus as well
979 as the Emacs frame itself.
981 If this resource specifies a position, that position applies only to the
982 initial Emacs frame (or, in the case of a resource for a specific frame
983 name, only that frame). However, the size if specified here applies to
986 @item @code{iconName} (class @code{Title})
987 Name to display in the icon.
989 @item @code{internalBorder} (class @code{BorderWidth})
990 Width in pixels of the internal border.
992 @item @code{lineSpacing} (class LineSpacing)
995 Additional space (@dfn{leading}) between lines, in pixels.
997 @item @code{menuBar} (class @code{MenuBar})
998 Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}.
1000 @item @code{toolBar} (class @code{ToolBar})
1001 Number of lines to reserve for the tool bar. A zero value suppresses
1002 the tool bar. If the value is non-zero and
1003 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size
1004 will be changed automatically so that all tool bar items are visible.
1006 @item @code{minibuffer} (class @code{Minibuffer})
1007 If @samp{none}, don't make a minibuffer in this frame.
1008 It will use a separate minibuffer frame instead.
1010 @item @code{paneFont} (class @code{Font})
1011 Font name for menu pane titles, in non-toolkit versions of Emacs.
1013 @item @code{pointerColor} (class @code{Foreground})
1014 Color of the mouse cursor.
1017 @item @code{privateColormap} (class @code{PrivateColormap})
1018 If @samp{on}, use a private colormap, in the case where the ``default
1019 visual'' of class PseudoColor and Emacs is using it.
1022 @item @code{reverseVideo} (class @code{ReverseVideo})
1023 Switch foreground and background default colors if @samp{on}, use colors as
1024 specified if @samp{off}.
1026 @item @code{screenGamma} (class @code{ScreenGamma})
1027 @cindex gamma correction
1028 Gamma correction for colors, equivalent to the frame parameter
1029 @code{screen-gamma}.
1031 @item @code{selectionFont} (class @code{Font})
1032 Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
1033 toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif
1036 @item @code{synchronous} (class @code{Synchronous})
1037 Run Emacs in synchronous mode if @samp{on}. Synchronous mode is
1038 useful for debugging X problems.
1040 @item @code{title} (class @code{Title})
1041 Name to display in the title bar of the initial Emacs frame.
1043 @item @code{verticalScrollBars} (class @code{ScrollBars})
1044 Give frames scroll bars if @samp{on}; don't have scroll bars if
1048 Here are resources for controlling the appearance of particular faces
1052 @item @var{face}.attributeFont
1053 Font for face @var{face}.
1054 @item @var{face}.attributeForeground
1055 Foreground color for face @var{face}.
1056 @item @var{face}.attributeBackground
1057 Background color for face @var{face}.
1058 @item @var{face}.attributeUnderline
1059 Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
1063 @node Lucid Resources
1064 @section Lucid Menu X Resources
1065 @cindex Menu X Resources (Lucid widgets)
1066 @cindex Lucid Widget X Resources
1068 If the Emacs installed at your site was built to use the X toolkit
1069 with the Lucid menu widgets, then the menu bar is a separate widget and
1070 has its own resources. The resource names contain @samp{pane.menubar}
1071 (following, as always, the name of the Emacs invocation or @samp{Emacs}
1072 which stands for all Emacs invocations). Specify them like this:
1075 Emacs.pane.menubar.@var{resource}: @var{value}
1079 For example, to specify the font @samp{8x16} for the menu-bar items,
1083 Emacs.pane.menubar.font: 8x16
1087 Resources for @emph{non-menubar} toolkit pop-up menus have
1088 @samp{menu*}, in like fashion. For example, to specify the font
1089 @samp{8x16} for the pop-up menu items, write this:
1092 Emacs.menu*.font: 8x16
1096 For dialog boxes, use @samp{dialog} instead of @samp{menu}:
1099 Emacs.dialog*.font: 8x16
1103 Experience shows that on some systems you may need to add
1104 @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
1105 some other systems, you must not add @samp{shell.}.
1107 Here is a list of the specific resources for menu bars and pop-up menus:
1111 Font for menu item text.
1113 Color of the foreground.
1115 Color of the background.
1116 @item buttonForeground
1117 In the menu bar, the color of the foreground for a selected item.
1118 @item horizontalSpacing
1119 Horizontal spacing in pixels between items. Default is 3.
1120 @item verticalSpacing
1121 Vertical spacing in pixels between items. Default is 1.
1123 Horizontal spacing between the arrow (which indicates a submenu) and
1124 the associated text. Default is 10.
1125 @item shadowThickness
1126 Thickness of shadow line around the widget.
1128 The margin of the menu bar, in characters. The default of 4 makes the
1129 menu bar appear like the LessTif/Motif one.
1132 @node LessTif Resources
1133 @section LessTif Menu X Resources
1134 @cindex Menu X Resources (LessTif widgets)
1135 @cindex LessTif Widget X Resources
1137 If the Emacs installed at your site was built to use the X toolkit
1138 with the LessTif or Motif widgets, then the menu bar is a separate
1139 widget and has its own resources. The resource names contain
1140 @samp{pane.menubar} (following, as always, the name of the Emacs
1141 invocation or @samp{Emacs} which stands for all Emacs invocations).
1142 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{File} in the menu bar is part of a subwidget named
1151 @samp{emacs.pane.menubar.File}. 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{File} submenu has an item named
1165 @samp{Save (current buffer)}. A resource specification for a submenu
1166 item looks like this:
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 (current
1177 Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16
1181 For an item in a second-level submenu, such as @samp{Spell-Check Message}
1182 under @samp{Spell Checking} under @samp{Tools}, the resource fits this
1186 Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
1193 Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Spell-Check Message: @var{value}
1196 It's impossible to specify a resource for all the menu-bar items
1197 without also specifying it for the submenus as well. So if you want the
1198 submenu items to look different from the menu bar itself, you must ask
1199 for that in two steps. First, specify the resource for all of them;
1200 then, override the value for submenus alone. Here is an example:
1203 Emacs.pane.menubar.*.fontList: 8x16
1204 Emacs.pane.menubar.popup_*.fontList: 8x16
1208 For toolkit pop-up menus, use @samp{menu*} instead of
1209 @samp{pane.menubar}. For example, to specify the font @samp{8x16} for
1210 the pop-up menu items, write this:
1213 Emacs.menu*.fontList: 8x16
1219 Here is a list of the specific resources for menu bars and pop-up menus:
1223 The color to show in an armed button.
1232 Amount of space to leave around the item, within the border.
1234 The width of border around the menu item, on all sides.
1235 @item shadowThickness
1236 The width of the border shadow.
1237 @item bottomShadowColor
1238 The color for the border shadow, on the bottom and the right.
1239 @item topShadowColor
1240 The color for the border shadow, on the top and the left.