GNU Emacs supports command line arguments to request various actions when invoking Emacs. These are for compatibility with other editors and for sophisticated activities. We don't recommend using them for ordinary editing.
Arguments starting with - are options. Other arguments specify files to visit. Emacs visits the specified files while it starts up. The last file name on your command line becomes the current buffer; the other files are also present in other buffers.
You can use options to specify various other things, such as the size and position of the X window Emacs uses, its colors, and so on. A few options support advanced usage, such as running Lisp functions on files in batch mode. The sections of this chapter describe the available options, arranged according to their purpose.
There are two ways of writing options: the short forms that start with a single -, and the long forms that start with --. For example, -d is a short form and --display is the corresponding long form.
The long forms with -- are easier to remember, but longer to type. However, you don't have to spell out the whole option name; any unambiguous abbreviation is enough. When a long option takes an argument, you can use either a space or an equal sign to separate the option name and the argument. Thus, you can write either --display sugar-bombs:0.0 or --display=sugar-bombs:0.0. We recommend an equal sign because it makes the relationship clearer, and the tables below always show an equal sign.
Most options specify how to initialize Emacs, or set parameters for the Emacs session. We call them initial options. A few options specify things to do: for example, load libraries, call functions, or exit Emacs. These are called action options. These and file names together are called action arguments. Emacs processes all the action arguments in the order they are written.
Here is a table of the action arguments and options:
The init file can access the values of the action arguments as
the elements of a list in the variable
The initial options specify parameter for the Emacs session. This section describes the more general initial options; some other options specifically related to X Windows appear in the following sections.
Some initial options affect the loading of init files. The normal actions of Emacs are to first load site-start.el if it exists, then your own init file ~/.emacs if it exists, and finally default.el if it exists; certain options prevent loading of some of these files or substitute other files for them.
Here is an example of using Emacs with arguments and options. It assumes you have a Lisp program file called hack-c.el which, when loaded, performs some useful operation on current buffer, expected to be a C program.
emacs -batch foo.c -l hack-c -f save-buffer >& log
This says to visit foo.c, load hack-c.el
(which makes changes in the visited file), save foo.c
You can specify action arguments for Emacs when you resume it after a suspension. To prepare for this, put the following code in your .emacs file (see section Hooks):
(add-hook 'suspend-hook 'resume-suspend-hook)
As further preparation, you must execute the shell script emacs.csh
(if you use csh as your shell) or emacs.bash (if you use
bash as your shell). These scripts define an alias named
Only action arguments work properly when you resume Emacs. Initial arguments are not recognized---it's too late to execute them anyway.
Note that resuming Emacs (with or without arguments) must be
done from within the shell that is the parent of the Emacs job.
This is why
The aliases use the Emacs Server feature if you appear to have a server Emacs running. However, they cannot determine this with complete accuracy. They may think that a server is still running when in actuality you have killed that Emacs, because the file /tmp/.esrv... still exists. If this happens, find that file and delete it.
This appendix describes how Emacs uses environment variables. An environment variable is a string passed from the operating system to Emacs, and the collection of environment variables is known as the environment. Environment variable names are case sensitive and it is conventional to use upper case letters only.
Because environment variables come from the operating system
there is no general way to set them; it depends on the operating
system and especially the shell that you are using. For example,
here's how to set the environment variable
export ORGANIZATION="not very much"
and here's how to do it in csh or tcsh:
setenv ORGANIZATION "not very much"
When Emacs is set-up to use the X windowing system, it inherits the use of a large number of environment variables from the X library. See the X documentation for more information.
These variables are used only on particular configurations:
The environment variable
With Emacs, the main reason people change the default display is to let them log into another system, run Emacs on that system, but have the window displayed at their local terminal. You might need to use login to another system because the files you want to edit are there, or because the Emacs executable file you want to run is there.
The syntax of the
For example, if your host is named glasperle and
your server is the first (or perhaps the only) server listed in
the configuration, your
emacs --display=glasperle:0 &
Sometimes, security arrangements prevent a program on a remote system from displaying on your local system. In this case, trying to run Emacs produces messages like this:
Xlib: connection to "glasperle:0.0" refused by server
By default, Emacs displays text in the font named 9x15, which makes each character nine pixels wide and fifteen pixels high. You can specify a different font on your command line through the option -fn name.
Under X, each font has a long name which consists of eleven words or numbers, separated by dashes. Some fonts also have shorter nicknames---9x15 is such a nickname. You can use either kind of name. You can use wild card patterns for the font name; then Emacs lets X choose one of the fonts that match the pattern. Here is an example, which happens to specify the font whose nickname is 6x13:
emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" &
You can also specify the font in your .Xdefaults file:
A long font name has the following form:
Use only fixed width fonts---that is, fonts in which all
characters have the same width; Emacs cannot yet handle display
properly for variable width
fonts. Any font with m or c in the spacing
field of the long name is a fixed width font. Here's how to use
xlsfonts -fn '*x*' xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'
To see what a particular font looks like, use the
xfd -fn 6x13
displays the entire font 6x13.
On a color display, you can specify which color to use for various parts of the Emacs display. To find out what colors are available on your system, look at the /usr/lib/X11/rgb.txt file. If you do not specify colors, the default for the background is white and the default for all other colors is black. On a monochrome display, the foreground is black, the background is white, and the border is gray if the display supports that.
Here is a list of the options for specifying colors:
emacs -ms coral -cr 'slate blue' &
You can reverse the foreground and background colors through the -r option or with the X resource reverseVideo.
Emacs uses the same units as
Since the mode line and the echo area occupy the last 2 lines of the frame, the height of the initial text window is 2 less than the height specified in your geometry. In non-X-toolkit versions of Emacs, the menu bar also takes one line of the specified number.
You do not have to specify all of the fields in the geometry specification.
If you omit both xoffset and yoffset, the window manager decides where to put the Emacs frame, possibly by letting you place it with the mouse. For example, 164x55 specifies a window 164 columns wide, enough for two ordinary width windows side by side, and 55 lines tall.
The default width for Emacs is 80 characters and the default height is 40 lines. You can omit either the width or the height or both. If you start the geometry with an integer, Emacs interprets it as the width. If you start with an x followed by an integer, Emacs interprets it as the height. Thus, 81 specifies just the width; x45 specifies just the height.
If you start with + or -, that introduces an offset, which means both sizes are omitted. Thus, -3 specifies the xoffset only. (If you give just one offset, it is always xoffset.) +3-3 specifies both the xoffset and the yoffset, placing the frame near the bottom left of the screen.
You can specify a default for any or all of the fields in .Xdefaults file, and then override selected fields with a --geometry option.
An Emacs frame has an internal border and an external border. The internal border is an extra strip of the background color around all four edges of the frame. Emacs itself adds the internal border. The external border is added by the window manager outside the internal border; it may contain various boxes you can click on to move or iconify the window.
Use the -ib n option to specify an internal border n pixels wide. The default is 1. Use -bw n to specify the width of the external border (though the window manager may not pay attention to what you specify). The default width of the external border is 2.
Most window managers allow the user to ``iconify'' a frame, removing it from sight, and leaving a small, distinctive ``icon'' window in its place. Clicking on the icon window makes the frame itself appear again. If you have many clients running at once, you can avoid cluttering up the screen by iconifying most of the clients.
The -i or --icon-type option tells Emacs to use an icon window containing a picture of the GNU gnu. If omitted, Emacs lets the window manager choose what sort of icon to use---usually just a small rectangle containing the frame's title.
The -iconic option tells Emacs to begin running as an icon, rather than opening a frame right away. In this situation, the icon window provides only indication that Emacs has started; the usual text frame doesn't appear until you deiconify it.
Programs running under the X Window System organize their user options under a hierarchy of classes and resources. You can specify default values for these options in your X resources file, usually named ~/.Xdefaults.
Each line in the file specifies a value for one option or for a collection of related options, for one program or for several programs (optionally even for all programs).
Programs define named resources with particular meanings. They also define how to group resources into named classes. For instance, in Emacs, the internalBorder resource controls the width of the internal border, and the borderWidth resource controls the width of the external border. Both of these resources are part of the BorderWidth class. Case distinctions are significant in these names.
In ~/.Xdefaults, you can specify a value for a single resource on one line, like this:
Or you can use a class name to specify the same value for all resources in that class. Here's an example:
If you specify a value for a class, it becomes the default for all resources in that class. You can specify values for individual resources as well; these override the class value, for those particular resources. Thus, this example specifies 2 as the default width for all borders, but overrides this value with 4 for the external border:
emacs.Borderwidth: 2 emacs.borderwidth: 4
The order in which the lines appear in the file does not matter. Also, command-line options always override the X resources file.
The string emacs in the examples above is also a resource name. It actually represents the name of the executable file that you invoke to run Emacs. If Emacs is installed under a different name, it looks for resources under that name instead of emacs.
When Emacs creates a new frame, it may or may not have a specified title. The frame title, if specified, appears in window decorations and icons as the name of the frame. It is also used (instead of the Emacs executable's name) to look up all the resources for that frame. The option -name specifies a frame title for the initial frame. Subsequent frames normally have no specified frame title, but Lisp programs can specify a title when they create frames.
For consistency, -name also specifies the name to use for other resource values that do not belong to any particular frame.
The resources that name Emacs invocations also belong to a class; its name is Emacs. If you write Emacs instead of emacs, the resource applies to all frames in all Emacs jobs, regardless of frame titles and regardless of the name of the executable file. Here is an example:
Emacs.BorderWidth: 2 Emacs.borderWidth: 4
You can specify a string of additional resource values for Emacs to use with the command line option -xrm resources. The text resources should have the same format that you would use inside a file of X resources. To include multiple resource specifications in data, put a newline between them, just as you would in a file. You can also use #include "filename" to include a file full of resource specifications. Resource values specified with -xrm take precedence over all other resource specifications.
The following table lists the resource names that designate options for Emacs, each with the class that it belongs to:
Here are resources for controlling the appearance of particular faces (see section Using Multiple Typefaces):
If the Emacs installed at your site was built to use the X toolkit with the Lucid menu widgets, then the menu bar is a separate widget and has its own resources. The resource names contain pane.menubar (following, as always, the name of the Emacs invocation or Emacs which stands for all Emacs invocations). Specify them like this:
For example, to specify the font 8x16 for the menu bar items, write this:
Resources for toolkit popup menus have menu*, in like fashion. For example, to specify the font 8x16 for the popup menu items, write this:
Experience shows that on some systems you may need to add shell. before the pane.menubar or menu*.
Here is a list of the specific resources for menu bars and popup menus:
If the Emacs installed at your site was built to use the X toolkit with the Motif widgets, then the menu bar is a separate widget and has its own resources. The resource names contain pane.menubar (following, as always, the name of the Emacs invocation or Emacs which stands for all Emacs invocations). Specify them like this:
Each individual string in the menu bar is a subwidget; the subwidget's name is the same as the menu item string. For example, the word Files in the menu bar is part of a subwidget named emacs.pane.menubar.Files. Most likely, you want to specify the same resources for the whole menu bar. To do this, use * instead of a specific subwidget name. For example, to specify the font 8x16 for the menu bar items, write this:
This also specifies the resource value for submenus.
Each item in a submenu in the menu bar also has its own name for X resources; for example, the Files submenu has an item named Save Buffer. A resource specification for a submenu item looks like this:
For example, here's how to specify the font for the Save Buffer item:
Emacs.pane.menubar.popup_*.Files.Save Buffer.fontList: 8x16
For an item in a second-level submenu, such as Check Message under Spell under Edit, the resource fits this template:
Emacs.pane.menubar.popup_*.popup_*.Spell.Check Message: value
It's impossible to specify a resource for all the menu bar items without also specifying it for the submenus as well. So if you want the submenu items to look different from the menu bar itself, you must ask for that in two steps. First, specify the resource for all of them; then, override the value for submenus alone. Here is an example:
Emacs.pane.menubar.*.fontList: 8x16 Emacs.pane.menubar.popup_*.fontList: 8x16
For toolkit popup menus, use menu* instead of pane.menubar. For example, to specify the font 8x16 for the popup menu items, write this:
Here is a list of the specific resources for menu bars and popup menus:
To return to the Ready-to-Run Software Super ReadyPak Table of Contents please press here.
Email addresses listed on this site may NOT be used for unsolicited commercial email.
Portions (c)Copyright, 1996-2005 by