@c This is part of the Emacs manual.
@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node MS-DOS, Manifesto, Antinews, Top
@appendix Emacs and MS-DOS 
@cindex MS-DOG
@cindex MS-DOS peculiarities

  This section briefly describes the peculiarities of using Emacs under
the MS-DOS ``operating system'' (also known as ``MS-DOG'').  If you
build Emacs for MS-DOS, the binary will also run on Windows 3, Windows
NT, Windows 95, or OS-2 as a DOS application; the information in this
chapter applies for all of those systems, if you use an Emacs that was
built for MS-DOS.

  Note that it is possible to build Emacs specifically for Windows NT or
Windows 95.  If you do that, most of this chapter does not apply;
instead, you get behavior much closer to what is documented in the rest
of the manual, including support for long file names, multiple frames,
scroll bars, mouse menus, and subprocesses.  However, the section on
text files and binary files does still apply.  There are also two
sections at the end of this chapter which apply specifically for Windows
NT and 95.

@menu
* Input: MS-DOS Input.         Keyboard and mouse usage on MS-DOS.
* Display: MS-DOS Display.     Fonts, frames and display size on MS-DOS.
* Files: MS-DOS File Names.    File name conventions on MS-DOS.
* Text and Binary::            Text files on MS-DOS use CRLF to separate lines.
* Printing: MS-DOS Printing.   How to specify the printer on MS-DOS.
* Processes: MS-DOS Processes. Running subprocesses on MS-DOS.
* Windows Processes::          Running subprocesses on Windows.
* Windows System Menu::        Controlling what the ALT key does.
@end menu

@node MS-DOS Input
@section Keyboard and Mouse on MS-DOS

@cindex Meta (under MS-DOS)
@cindex Hyper (under MS-DOS)
@cindex Super (under MS-DOS)
@vindex dos-super-key
@vindex dos-hyper-key
  The PC keyboard maps use the left @key{ALT} key as the @key{META} key.
You have two choices for emulating the @key{SUPER} and @key{HYPER} keys:
choose either the right @key{CTRL} key or the right @key{ALT} key by
setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1
or 2 respectively.  If neither @code{dos-super-key} nor
@code{dos-hyper-key} is 1, then by default the right @key{ALT} key is
also mapped to the @key{META} key.  However, if the MS-DOS international
keyboard support program @file{KEYB.COM} is installed, Emacs will
@emph{not} map the right @key{ALT} to @key{META}, since it is used for
accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard
layouts; in this case, you may only use the left @key{ALT} as @key{META}
key.

@kindex C-j @r{(MS-DOS)}
@vindex dos-keypad-mode
  The variable @code{dos-keypad-mode} is a flag variable that controls
what key codes are returned by keys in the numeric keypad.  You can also
define the keypad @key{ENTER} key to act like @kbd{C-j}, by putting the
following line into your @file{_emacs} file:

@smallexample
;; Make the Enter key from the Numeric keypad act as C-j.
(define-key function-key-map [kp-enter] [?\C-j])
@end smallexample

@kindex DEL @r{(MS-DOS)}
@kindex BS @r{(MS-DOS)}
  The key that is called @key{DEL} in Emacs (because that's how it is
designated on most workstations) is known as @key{BS} (backspace) on a
PC.  That is why the PC-specific terminal initialization remaps the
@key{BS} key to act as @key{DEL}; the @key{DEL} key is remapped to act
as @kbd{C-d} for the same reasons.

@kindex C-g @r{(MS-DOS)}
@kindex C-BREAK @r{(MS-DOS)}
@cindex quitting on MS-DOS
  Emacs built for MS-DOS recognizes @kbd{C-@key{BREAK}} as a quit
character, just like @kbd{C-g}.  This is because Emacs cannot detect
that you have typed @kbd{C-g} until it is ready for more input.  As a
consequence, you cannot use @kbd{C-g} to stop a running command
(@pxref{Quitting}).  By contrast, @kbd{C-@key{BREAK}} @emph{is} detected
as soon as you type it (as @kbd{C-g} is on other systems), so it can be
used to stop a running command and for emergency escape
(@pxref{Emergency Escape}).

@cindex mouse support under MS-DOS
  Emacs on MS-DOS supports a mouse (on the default terminal only).
The mouse commands work as documented, including those that use menus
and the menu bar (@pxref{Menu Bar}).  Scroll bars don't work in
MS-DOS Emacs.  PC mice usually have only two buttons; these act as
@kbd{Mouse-1} and @kbd{Mouse-2}, but if you press both of them
together, that has the effect of @kbd{Mouse-3}.

@cindex Windows clipboard support
  Emacs built for MS-DOS supports clipboard operations when it runs on
Windows.  Commands that put text on the kill ring, or yank text from the
ring, check the Windows clipboard first, just as Emacs does on X Windows
(@pxref{Mouse Commands}).  Only the primary selection and the cut buffer
are supported by MS-DOS Emacs on Windows; the secondary selection always
appears as empty.

  Due to the way clipboard access is implemented by Windows, the
length of text you can put into the clipboard is limited by the amount
of free DOS memory that is available to Emacs.  Usually, up to 620KB of
text can be put into the clipboard, but this limit depends on the system
configuration and is lower if you run Emacs as a subprocess of
another program.  If the killed text does not fit, Emacs prints a
message saying so, and does not put the text into the clipboard.

@vindex dos-display-scancodes
  The variable @code{dos-display-scancodes}, when non-@code{nil},
directs Emacs to display the ASCII value and the keyboard scan code of
each keystroke; this feature serves as a complement to the
@code{view-lossage} command, for debugging.

@node MS-DOS Display
@section Display on MS-DOS
@cindex faces under MS-DOS
@cindex fonts, emulating under MS-DOS

  Display on MS-DOS cannot use multiple fonts, but it does support
multiple faces, each of which can specify a foreground and a background
color.  Therefore, you can get the full functionality of Emacs packages
that use fonts (such as @code{font-lock}, Enriched Text mode, and
others) by defining the relevant faces to use different colors.  Use the
@code{list-colors-display} command (@pxref{Frame Parameters}) and the
@code{list-faces-display} command (@pxref{Faces}) to see what colors and
faces are available and what they look like.

@cindex frames on MS-DOS
  Multiple frames (@pxref{Frames}) are supported on MS-DOS, but they all
overlap, so you only see a single frame at any given moment.  That
single visible frame occupies the entire screen.  When you run Emacs
from MS-Windows DOS box, you can make the visible frame smaller than
the full screen, but Emacs still cannot display more than a single
frame at a time.

@cindex frame size under MS-DOS
@findex mode4350
@findex mode25
  The @code{mode4350} command switches the display to 43 or 50
lines, depending on your hardware; the @code{mode25} command switches
to the default 80x25 screen size.

  By default, Emacs only knows how to set screen sizes of 80 columns by
25, 28, 35, 40, 43 or 50 rows.  However, if your video adapter has
special video modes that will switch the display to other sizes, you can
have Emacs support those too.  When you ask Emacs to switch the frame to
@var{n} rows by @var{m} columns dimensions, it checks if there is a
variable called @code{screen-dimensions-@var{n}x@var{m}}, and if so,
uses its value (which must be an integer) as the video mode to switch
to.  (Emacs switches to that video mode by calling the BIOS @code{Set
Video Mode} function with the value of
@code{screen-dimensions-@var{n}x@var{m}} in the @code{AL} register.)
For example, suppose your adapter will switch to 66x80 dimensions when
put into video mode 85.  Then you can make Emacs support this screen
size by putting the following into your @file{_emacs} file:

@example
(setq screen-dimensions-66x80 85)
@end example

  Since Emacs on MS-DOS can only set the frame size to specific
supported dimensions, it cannot honor every possible frame resizing
request.  When an unsupported size is requested, Emacs chooses the next
larger supported size beyond the specified size.  For example, if you
ask for 36x80 frame, you will get 40x80 instead.

  The variables @code{screen-dimensions-@var{n}x@var{m}} are used only
when they exactly match the specified size; the search for the next
larger supported size ignores them.  In the above example, even if your
VGA supports 38x80 dimensions and you define a variable
@code{screen-dimensions-38x80} with a suitable value, you will still get
40x80 screen when you ask for a 36x80 frame.  If you want to get the
38x80 size in this case, you can do it by setting the variable named
@code{screen-dimensions-36x80} with the same video mode value as
@code{screen-dimensions-38x80}.

  Changing frame dimensions on MS-DOS has the effect of changing all the
other frames to the new dimensions.

@node MS-DOS File Names
@section File Names on MS-DOS
@cindex file names under MS-DOS
@cindex init file, default name under MS-DOS

  MS-DOS normally uses a backslash, @samp{\}, to separate name units
within a file name, instead of the slash used on other systems.  Emacs
on MS-DOS permits use of either slash or backslash, and also knows
about drive letters in file names.

  On MS-DOS, file names are case-insensitive and limited to eight
characters, plus optionally a period and three more characters.  Emacs
knows enough about these limitations to handle file names that were
meant for other operating systems.  For instance, leading dots @samp{.}
in file names are invalid in MS-DOS, so Emacs transparently converts
them to underscores @samp{_}; thus your default init file (@pxref{Init
File}) is called @file{_emacs} on MS-DOS.  Excess characters before or
after the period are generally ignored by MS-DOS itself; thus, if you
visit the file @file{LongFileName.EvenLongerExtension}, you will
silently get @file{longfile.eve}, but Emacs will still display the long
file name on the mode line.  Other than that, it's up to you to specify
file names which are valid under MS-DOS; the transparent conversion as
described above only works on file names built into Emacs.

@cindex backup file names on MS-DOS
  The above restrictions on the file names on MS-DOS make it almost
impossible to construct the name of a backup file (@pxref{Backup
Names}) without losing some of the original file name characters.  For
example, the name of a backup file for @file{docs.txt} is
@file{docs.tx~} even if single backup is used.

@cindex file names under Windows 95/NT
@cindex long file names in DOS box under Windows 95/NT
  If you run Emacs as a DOS application under Windows 9X, you can
turn on support for long file names.  If you do that, Emacs doesn't
truncate file names or convert them to lower case; instead, it uses the
file names that you specify, verbatim.  To enable long file name
support, set the environment variable @code{LFN} to @samp{y} before
starting Emacs.  Unfortunately, Windows NT doesn't allow DOS programs to
access long file names, so Emacs built for MS-DOS will only see their
short 8+3 aliases.

@cindex @code{HOME} directory under MS-DOS
  MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends
that the directory where it is installed is the value of @code{HOME}
environment variable.  That is, if your Emacs binary,
@file{emacs.exe}, is in the directory @file{c:/utils/emacs/bin}, then
Emacs acts as if @code{HOME} were set to @samp{c:/utils/emacs}.  In
particular, that is where Emacs looks for the init file @file{_emacs}.
With this in mind, you can use @samp{~} in file names as an alias for
the home directory, as you would in Unix.  You can also set @code{HOME}
variable in the environment before starting Emacs; its value will then
override the above default behavior.

  Emacs on MS-DOS handles the directory name @file{/dev} specially,
because of a feature in the emulator libraries of DJGPP that pretends
I/O devices have names in that directory.  We recommend that you avoid
using an actual directory named @file{/dev} on any disk.

@node Text and Binary
@section Text Files and Binary Files
@cindex text and binary files on MS-DOS/MS-Windows

  GNU Emacs uses newline characters to separate text lines.  This is the
convention used on Unix, on which GNU Emacs was developed, and on GNU
systems since they are modeled on Unix.

@cindex end-of-line conversion on MS-DOS/MS-Windows
  MS-DOS and MS-Windows normally use carriage-return linefeed, a
two-character sequence, to separate text lines.  (Linefeed is the same
character as newline.)  Therefore, convenient editing of typical files
with Emacs requires conversion of these end-of-line (EOL) sequences.
And that is what Emacs normally does: it converts carriage-return
linefeed into newline when reading files, and converts newline into
carriage-return linefeed when writing files.  The same mechanism that
handles conversion of international character codes does this conversion
also (@pxref{Coding Systems}).

@cindex cursor location, under MS-DOS
@cindex point location, under MS-DOS
  One consequence of this special format-conversion of most files is
that character positions as reported by Emacs (@pxref{Position Info}) do
not agree with the file size information known to the operating system.

@vindex file-name-buffer-file-type-alist
  Some kinds of files should not be converted, because their contents
are not really text.  Therefore, Emacs on MS-DOS distinguishes certain
files as @dfn{binary files}, and reads and writes them verbatim.  (This
distinction is not part of MS-DOS; it is made by Emacs only.)  These
include executable programs, compressed archives, etc.  Emacs uses the
file name to decide whether to treat a file as binary: the variable
@code{file-name-buffer-file-type-alist} defines the file-name patterns
that indicate binary files.  Note that if a file name matches one of the
patterns for binary files in @code{file-name-buffer-file-type-alist},
Emacs uses the @code{no-conversion} coding system (@pxref{Coding
Systems}) which turns off @emph{all} coding-system conversions, not only
the EOL conversion.

  In addition, if Emacs recognizes from a file's contents that it uses
newline rather than carriage-return linefeed as its line separator, it
does not perform conversion when reading or writing that file.  Thus,
you can read and edit files from Unix or GNU systems on MS-DOS with no
special effort, and they will be left with their Unix-style EOLs.

@findex find-file-text
@findex find-file-binary
  You can visit a file and specify whether to treat a file as text or
binary using the commands @code{find-file-text} and
@code{find-file-binary}.  End-of-line conversion is part of the general
coding system conversion mechanism, so another way to control whether to
treat a file as text or binary is with the commands for specifying a
coding system (@pxref{Specify Coding}).  For example,
@kbd{C-x @key{RET} c undecided-unix @key{RET} C-x C-f foobar.txt}
visits the file @file{foobar.txt} without converting the EOLs.

  The mode line indicates whether end-of-line translation was used for
the current buffer.  Normally a colon appears after the coding system
letter near the beginning of the mode line.  If MS-DOS end-of-line
translation is in use for the buffer, this character changes to a
backslash.

@cindex untranslated file system
@findex add-untranslated-filesystem
  When you use NFS or Samba to access file systems that reside on
computers using Unix or GNU systems, Emacs should not perform
end-of-line translation on any files in these file systems--not even
when you create a new file.  To request this, designate these file
systems as @dfn{untranslated} file systems by calling the function
@code{add-untranslated-filesystem}.  It takes one argument: the file
system name, including a drive letter and optionally a directory.  For
example,

@example
(add-untranslated-filesystem "Z:")
@end example

@noindent
designates drive Z as an untranslated file system, and

@example
(add-untranslated-filesystem "Z:\\foo")
@end example

@noindent
designates directory @file{\foo} on drive Z as an untranslated file
system.

  Most often you would use @code{add-untranslated-filesystem} in your
@file{_emacs} file, or in @file{site-start.el} so that all the users at
your site get the benefit of it.

@findex remove-untranslated-filesystem
  To countermand the effect of @code{add-untranslated-filesystem}, use
the function @code{remove-untranslated-filesystem}.  This function takes
one argument, which should be a string just like the one that was used
previously with @code{add-untranslated-filesystem}.

@node MS-DOS Printing
@section Printing and MS-DOS

  Printing commands, such as @code{lpr-buffer} (@pxref{Hardcopy}) and
@code{ps-print-buffer} (@pxref{Postscript}) can work in MS-DOS by
sending the output to one of the printer ports, if a Unix-style @code{lpr}
program is unavailable.  A few DOS-specific variables control how this
works.

@vindex dos-printer
  If you want to use your local printer, printing on it in the usual DOS
manner, then set the Lisp variable @code{dos-printer} to the name of the
printer port---for example, @code{"PRN"}, the usual local printer port
(that's the default), or @code{"LPT2"} or @code{"COM1"} for a serial
printer.  You can also set @code{dos-printer} to a file name, in which
case ``printed'' output is actually appended to that file.  If you set
@code{dos-printer} to @code{"NUL"}, printed output is silently
discarded (sent to the system null device).

  If you set @code{dos-printer} to a file name, it's best to use an
absolute file name.  Emacs changes the working directory according to
the default directory of the current buffer, so if the file name in
@code{dos-printer} is relative, you will end up with several such files,
each one in the directory of the buffer from which the printing was
done.

@findex print-buffer @r{(MS-DOS)}
@findex print-region @r{(MS-DOS)}
@vindex lpr-headers-switches @r{(MS-DOS)}
  The commands @code{print-buffer} and @code{print-region} call the
@code{pr} program, or use special switches to the @code{lpr} program, to
produce headers on each printed page.  MS-DOS doesn't normally have
these programs, so by default, the variable @code{lpr-headers-switches}
is set so that the requests to print page headers are silently ignored.
Thus, @code{print-buffer} and @code{print-region} produce the same
output as @code{lpr-buffer} and @code{lpr-region}, respectively.  If you
do have a suitable @code{pr} program (for example, from GNU Textutils),
set @code{lpr-headers-switches} to @code{nil}; Emacs will then call
@code{pr} to produce the page headers, and print the resulting output as
specified by @code{dos-printer}.

@vindex print-region-function @r{(MS-DOS)}
@cindex lpr usage under MS-DOS
@vindex lpr-command @r{(MS-DOS)}
@vindex lpr-switches @r{(MS-DOS)}
  Finally, if you do have an @code{lpr} work-alike, you can set
@code{print-region-function} to @code{nil}.  Then Emacs uses @code{lpr}
for printing, as on other systems.  (If the name of the program isn't
@code{lpr}, set the @code{lpr-command} variable to specify where to find
it.)

@findex ps-print-buffer @r{(MS-DOS)}
@findex ps-spool-buffer @r{(MS-DOS)}
@vindex dos-ps-printer
@vindex ps-lpr-command @r{(MS-DOS)}
@vindex ps-lpr-switches @r{(MS-DOS)}
  A separate variable, @code{dos-ps-printer}, defines how PostScript
files should be printed.  If its value is a string, it is used as the
name of the device (or file) to which PostScript output is sent, just as
@code{dos-printer} is used for non-PostScript printing.  (These are two
distinct variables in case you have two printers attached to two
different ports, and only one of them is a PostScript printer.)  If the
value of @code{dos-ps-printer} is not a string, then the variables
@code{ps-lpr-command} and @code{ps-lpr-switches} (@pxref{Postscript})
control how to print PostScript files.  Thus, if you have a
non-PostScript printer, you can set these variables to the name and the
switches appropriate for a PostScript interpreter program (such as
Ghostscript).

  For example, to use Ghostscript for printing on an Epson printer
connected to @samp{LPT2} port, put this on your @file{.emacs} file:

@example
(setq dos-ps-printer t)  ; @r{Anything but a string.}
(setq ps-lpr-command "c:/gs/gs386")
(setq ps-lpr-switches '("-q" "-dNOPAUSE"
			"-sDEVICE=epson"
			"-r240x72"
			"-sOutputFile=LPT2"
			"-Ic:/gs"
			"-"))
@end example

@noindent
(This assumes that Ghostscript is installed in the @file{"c:/gs"}
directory.)

@node MS-DOS Processes
@section Subprocesses on MS-DOS

@cindex compilation under MS-DOS
@cindex inferior processes under MS-DOS
@findex compile @r{(MS-DOS)}
@findex grep @r{(MS-DOS)}
  Because MS-DOS is a single-process ``operating system,''
asynchronous subprocesses are not available.  In particular, Shell
mode and its variants do not work.  Most Emacs features that use
asynchronous subprocesses also don't work on MS-DOS, including
spelling correction and GUD.  When in doubt, try and see; commands that
don't work print an error message saying that asynchronous processes
aren't supported.

  Compilation under Emacs with @kbd{M-x compile}, searching files with
@kbd{M-x grep} and displaying differences between files with @kbd{M-x
diff} do work, by running the inferior processes synchronously.  This
means you cannot do any more editing until the inferior process
finishes.

  By contrast, Emacs compiled as native Windows application
@strong{does} support asynchronous subprocesses.  @xref{Windows
Processes}.

@cindex printing under MS-DOS
  Printing commands, such as @code{lpr-buffer} (@pxref{Hardcopy}) and
@code{ps-print-buffer} (@pxref{Postscript}), work in MS-DOS by sending
the output to one of the printer ports.  @xref{MS-DOS Printing}.

  When you run a subprocess synchronously on MS-DOS, make sure the
program terminates and does not try to read keyboard input.  If the
program does not terminate on its own, you will be unable to terminate
it, because MS-DOS provides no general way to terminate a process.
Pressing @kbd{C-c} or @kbd{C-@key{BREAK}} might sometimes help in these
cases.

  Accessing files on other machines is not supported on MS-DOS.  Other
network-oriented commands such as sending mail, Web browsing, remote
login, etc., don't work either, unless network access is built into
MS-DOS with some network redirector.

@cindex directory listing on MS-DOS
@vindex dired-listing-switches @r{(MS-DOS)}
  Dired on MS-DOS uses the @code{ls-lisp} package where other
platforms use the system @code{ls} command.  Therefore, Dired on
MS-DOS supports only some of the possible options you can mention in
the @code{dired-listing-switches} variable.  The options that work are
@samp{-A}, @samp{-a}, @samp{-c}, @samp{-i}, @samp{-r}, @samp{-S},
@samp{-s}, @samp{-t}, and @samp{-u}.

@node Windows Processes
@section Subprocesses on Windows 95 and NT

Emacs compiled as a native Windows application (as opposed to the DOS
version) includes full support for asynchronous subprocesses.
In the Windows version, synchronous and asynchronous subprocesses work
fine on both
Windows 95 and Windows NT as long as you run only 32-bit Windows
applications.  However, when you run a DOS application in a subprocess,
you may encounter problems or be unable to run the application at all;
and if you run two DOS applications at the same time in two
subprocesses, you may have to reboot your system.

Since the standard command interpreter (and most command line utilities)
on Windows 95 are DOS applications, these problems are significant when
using that system.  But there's nothing we can do about them; only
Microsoft can fix them.

If you run just one DOS application subprocess, the subprocess should
work as expected as long as it is ``well-behaved'' and does not perform
direct screen access or other unusual actions.  If you have a CPU
monitor application, your machine will appear to be 100% busy even when
the DOS application is idle, but this is only an artifact of the way CPU
monitors measure processor load.

You must terminate the DOS application before you start any other DOS
application in a different subprocess.  Emacs is unable to interrupt or
terminate a DOS subprocess.  The only way you can terminate such a
subprocess is by giving it a command that tells its program to exit.

If you attempt to run two DOS applications at the same time in separate
subprocesses, the second one that is started will be suspended until the
first one finishes, even if either or both of them are asynchronous.

If you can go to the first subprocess, and tell it to exit, the second
subprocess should continue normally.  However, if the second subprocess
is synchronous, Emacs itself will be hung until the first subprocess
finishes.  If it will not finish without user input, then you have no
choice but to reboot if you are running on Windows 95.  If you are
running on Windows NT, you can use a process viewer application to kill
the appropriate instance of ntvdm instead (this will terminate both DOS
subprocesses).

If you have to reboot Windows 95 in this situation, do not use the
@code{Shutdown} command on the @code{Start} menu; that usually hangs the
system.  Instead, type @kbd{CTL-ALT-@key{DEL}} and then choose
@code{Shutdown}.  That usually works, although it may take a few minutes
to do its job.

@node Windows System Menu
@section Using the System Menu on Windows

Emacs compiled as a native Windows application normally turns off the
Windows feature that tapping the @key{ALT}
key invokes the Windows menu.  The reason is that the @key{ALT} also
serves as @key{META} in Emacs.  When using Emacs, users often press the
@key{META} key temporarily and then change their minds; if this has the
effect of bringing up the Windows menu, it alters the meaning of
subsequent commands.  Many users find this frustrating. 

@vindex w32-pass-alt-to-system
You can reenable Windows's default handling of tapping the @key{ALT} key
by setting @code{w32-pass-alt-to-system} to a non-@code{nil} value.

