NAME
dosemu.bin, dosdebug - run DOS and DOS programs under Linux
SYNOPSIS
dosemu.bin [ -234ABCcdKkmNnOpSstVwX ] [ -h level ] [ -F file ] [
--Fusers file ] [ --Flibdir directory ] [ --Fimagedir directory ] [ -f
file ] [ -L dexefile ] [ -u confvar ] [ -D flags ] [ -M size ] [ -e
size ] [ -x size ] [ -P file ] [ -o file ] [ 2> debugfile ] [ -I
config-options ] [ -i[bootdir] ] [ -U inpipe[:outpipe] ] [ [-E] dos-
command ]
dosdebug
DESCRIPTION
dosemu.bin is the binary wrapped by the script dosemu (1) which invokes
the Linux dos emulator, also known as DOSEMU.
debugfile is an optional file into which all debugging output will be
redirected.
dosdebug is used to control or debug an already running DOSEMU.
Although this program is known as the DOS emulator, it is actually a
virtual machine for DOS, allowing DOS and programs written for DOS to
operate in an environment similar to a standard IBM PC/AT or compatible
with an Intel 80x86 processor in real mode. DOSEMU provides emulation
of such services as BIOS video, disk, keyboard, serial, and printer;
CMOS memory for configuration information; a real time clock; memory
allocation through the XMS 3.0 specification, EMS 4.0 and DPMI 0.9.
Because DOSEMU is not really a DOS emulator, a copy of FreeDos is
required, which now is pre-configured and part of the official DOSEMU
binary distribution. In addition any currently available proprietary
DOS (such as MS-DOS, PC-DOS, DR-DOS) can be booted, when properly
configured.
KERNEL REQUIREMENTS
At present, you will need Linux 2.0.28 or above with the SYSV IPC
option (System V Inter-Process Communication facilities, see ipc(2))
compiled. SYSV IPC is an option in the configuration setup during a
Linux kernel compile.
OPTIONS
-2,3,4,5
choose 286, 386, 486 or 586 processor to simulate.
-A boot from floppy disk A (does not need to be a real floppy disk,
see below)
-B boot from floppy disk B (does not need to be a real floppy disk,
see below)
-C boot from hard disk C (does not need to be a real hard disk or
even an msdos filesystem, see below)
-c use direct Console video (must be at the console, requires
special privileges, and -s ).
-d detach from current virtual console or tty and attach to the
first free virtual console
[-E] dos-command
Run DOS command when starting DOSEMU, and, if ’-E’ is not given,
exit DOSEMU after running the command. The command can also be
given with a Linux path (for example
/home/joeuser/dosemu/freedos/bin/xcopy.exe). Note: this only
works if your autoexec.bat contains a "unix -e" command.
-k use RAW console Keyboard (must be at the console)
-F Parse this config-script instead of the built-in global.conf
file (you need to run as root on suid DOSEMU for this)
--Fusers
Bypass dosemu.users and take this file instead (only accepted
when dosemu.bin is not suid-root).
--Flibdir
Bypass the default DOSEMU_LIB_DIR (as maybe defined in
dosemu.users) and use this directory instead.
--Fimagedir
Bypass the default directory for bootdirectory and hdimages
(DOSEMU_HDIMAGE_DIR) and use this directory instead.
-f Parse this config-file instead of .dosemurc
-n Bypass (don’t use) dosemu.users and dosemu.conf (only accepted
when dosemu.bin is not suid-root).
-u set a user configuration variable. An u_ is prefixed to the name
to avoid name clashes. This variable then can be checked in
dosemu.conf or global.conf to do some special configuration.
-L Load and start a DEXE file (special preconfigured bootable
hdimage containing just one DOS application)
-I Parse the string behind -I with the same syntax as global.conf
or .dosemurc such as
dos ... -I ’video { mda }’
This is useful if you just want to override a given
configuration parameter temporary. You also may have a generic
configuration by executing a script such as
dos ... -I "‘myconf.sh‘"
where myconf.sh is a script writing the configuration to stdout.
If you have an alternate configuration file besides .dosrc,
dos ... -I "‘cat myother.conf‘"
will do the job. Note however, that you have to quote the
parameter behind -I because it is expected to be one argument.
-i[bootdir]
launched as part of a systemwide installation, this option
(re-)installs a DOS that is used in DOSEMU (this can be the
DOSEMU distributed FreeDOS or any proprietary DOS, which is
bootable via fatfs). bootdir is the base name of a directory.
The symbolic link ~/.dosemu/drives/c will be changed to point to
this directory. Re-installing is only rarely necessary, since
in practise the symbolic link(s) will automatically point to
updated files.
-D specify which Debugging messages to allow/suppress
-h dump configuration to stderr and exit (implicit sets -D+c). This
is useful for debugging configuration files, you should use -O
too to direct the +c type messages to stderr. ‘level’ can be 0,
1 or 2 and controls the amount of configuration parser debug
output: No parser debug (0), parser loop debug (1),
if_else_endif debug (2).
-H specify the dosdebug support flags, currently only ‘1’ is is
reasonable. with -H1 you force dosemu to wait until the
dosdebug terminal has connected. Hence to debug a DOS session
from the very beginning you first start dosemu with -H1 and then
start dosdebug. DOSEMU will then lock before jumping into the
loaded bootsector waiting for dosdebug to connect. Once
connected you are in ‘stopped’ state and can set breakpoints or
single-step through the bootstrap code.
-M set base memory to SIZE Kilobytes
-m toggle internal mouse-support
-O use stderr for output of Debugging messages
-o use this file for output of Debugging messages
-P copy debugging output to FILE
-p stop for prompting if a non-fatal configuration problem is
detected
-S run using SDL
-s super-user/full feature mode: enable direct hardware access.
Use this switch if you wish to use graphics on the console, need
direct port access, hardware interrupts or raw network access.
Implies -V and -k by default.
WARNING: THIS SWITCH NEEDS ROOT, SUID-ROOT, OR SUDO. GIVING
DIRECT HARDWARE ACCESS TO DOS PROGRAMS MAY GIVE THESE THE
ABILITY TO LOCK YOUR COMPUTER, OR (IN RARE CASES) EVEN DAMAGE
HARDWARE. ONLY TRUSTED LOCAL USERS SHOULD BE GIVEN THIS TYPE OF
ACCESS.
-t terminal mode: run using the S-Lang library
-U define inpipe and outpipe for asynchronous control of DOSEMU
from another process. The format is (without whitespace in
between)
inpipe:outpipe
where ‘:outpipe’ can be omitted. In the latter case no feedback
from DOSEMU can be expected.
For security reasons DOSEMU does not create the named pipes
itself, so the user is responsible to set the permissions of the
pipes correctly. Note that when using this options, the foreign
process can control your DOSEMU session (such as entering
keystrokes). This option should therefor only used by frontends
(such as kdos), which first create the proper named pipes and
then launch DOSEMU. A special control command ( ack on ) can be
used to force DOSEMU returning handshake tags via ‘outpipe’ such
that the frontend knows when the control command has started or
finished and whether it was successful. The format of this
tagging is
SYN: <commandname>
<any output from the command>
ACK: code=n
where n is 0 for success. A tiny control terminal, which can
serve as example, is the supplied dosctrl program. It takes just
the two pipes as arguments and you may then enter control
commands, which of them ‘help’ is the most important one;-) Note
that dosctrl does not launch DOSEMU, you have to do it yourself.
-V use direct console video with VGA graphics and use the native
graphics card’s BIOS (must be at the console, requires special
privileges, and -s ).
-w toggle windowed/fullscreen mode in X
-X run in an X Window
HARD DISKS
DOSEMU supports four methods of supplying DOS with hard disks:
1. a virtual disk file residing on a Linux filesystem which
emulates a hard drive.
2. direct access to a DOS partition through a raw disk device (i.e.
/dev/hda, /dev/hdb, /dev/sdX).
3. direct access to an DOS partition through single partition
access (i.e. /dev/hda1, /dev/hdb2, /dev/sdxx).
4. access to a Linux filesystem as a "network" drive using the
driver emufs.sys supplied with DOSEMU in commands/emufs.sys or
lredir.exe.
Configuration of DOSEMU’s hard disk resources is done by editing
dosemu.conf or .dosemurc before running DOSEMU. Look at
/usr/share/doc/dosemu/README.txt.
FLOPPY DISKS
DOSEMU supports two methods of supplying DOS with floppy disks:
1. a virtual disk file residing on a Linux filesystem which
emulates a floppy drive
2. direct access to a physical floppy through a raw disk device
(i.e. /dev/fd0, /dev/fd1).
This is also explained more thoroughly in README.txt.
Configuration of DOSEMU’s floppy disk resources is done by editing the
dosemu.conf before running DOSEMU.
VIDEO
DOSEMU may be run on any tty device. However, increased performance
and functionality may be had by taking advantage of special features of
the Linux console. Those running DOSEMU on the console may wish to
investigate the -c, -k, and -V switches, explained more thoroughly in
README.txt. There is also some very brief documentation in the file
dosemu.conf, which can be edited for your needs.
In brief, proper use of the console device and the corresponding
switches allows the user to view a DOS program in its original color
and font, with none of the periodic screen update problems with the
generic tty output code.
KEYBOARD
Those using DOSEMU on the Linux console may also wish to use the RAW
keyboard support. This mode of operation, selected by the -k switch,
provides the user with access to the entire keyboard accessible under
DOS. Any combination of ALT, CTRL, and SHIFT keys may be used to
generate the odd keycodes expected by many DOS programs.
PRINTING
The BIOS printer services are emulated through standard UNIX file I/O
though temporary files which are then periodically spooled by LPR or a
different print client, as defined by $_printer_commands in
dosemu.conf.
DEBUG MESSAGES
Debug messages can be controlled either at the command line or in the
configuration file. Take a look at the documentation inside the
config.dist file included with DOSEMU in the examples subdirectory, for
debugging options. At the command line, you may specify which classes
of messages you wish dos to allow. The syntax of this is DOSEMU takes
an option "-D FLAGS", where FLAGS is a string of letters which specify
which options to print or suppress. DOSEMU parses this string from
left to right.
+ turns the following options on (initial state)
- turns the following options off
a turns all the options on/off, depending on flag
0 turns all options off
1-9 sets the debug level, the higher, the more output
# where # is a letter from the valid class list,
turns that option off/on depending on the
+/- state.
Message Classes:
d disk R disk read W disk write
D int 21h C cdrom v video
X X support k keyboard i port I/O
s serial m mouse # default ints
p printer g general c configuration
w warning h hardware I IPC
E EMS x XMS M DPMI
n IPX network P Pkt-driver S SOUND
r PIC T IO-tracing Z PCI-BIOS
A ASPI driver Q mapping driver
Any debugging classes following a + character, up to a - character,
will be turned on (non-suppressed). Any after a - character, up to a +
character, will be suppressed. The character a acts like a string of
all possible debugging classes, so +a turns on all debugging messages,
and -a turns off all debugging messages. The characters 0 and 1-9 are
also special: 0 turns off all debugging messages, and 1-9 turns on all
debugging messages, but set the debug level too.
There is an assumed + at the beginning of the FLAGS string. Some
classes, such as error, can not be turned off. In case you didn’t
redirect stderr, nearly all output to stderr goes to /dev/null.
Some examples:
"-D+a-v" or "-D1-v" : all messages but video
"-D+kd" : default + keyboard and disk
"-D0+RW" : only disk READ and WRITE
Any option letter can occur in any place. Even pointless combinations,
such as -D01-a-1+0, will be parsed without error, so be careful. Some
options are set by default, some are clear. This is subject to my whim,
and will probably change between releases. You can ensure which are
set by always explicitly specifying them.
SPECIAL KEYS
In RAW keyboard mode (see the -k option), DOSEMU responds to certain
key sequences as control functions.
ctrl-scrlock = show 0x32 int vectors
alt-scrlock = show the vm86 registers
rshift-scrlock = generate an int8 (timer)
lshift-scrlock = generate an int9 (keyboard)
ctrl-break = ctrl-break as under DOS.
ctrl-alt-pgup = reboot DOS. Don’t trust this!
ctrl-alt-pgdn = exit the emulator
Use <LEFT CTRL>-<LEFT ALT>-<Function key> to switch to another virtual
console.
MEMORY
The XMS memory support in DOSEMU conforms to Lotus/Intel/Microsoft/AST
extended memory specification 3.0. I have implemented all XMS
functions except function 0x12 (Reallocate Upper Memory Block).
DOSEMU also supports EMS 4.0 and implements DPMI 0.9 (1.0 partially).
AUTHOR
DOSEMU (comprised of the files dosemu.bin and dosemu ) is based on
version 0.4 of the original program written by Matthias Lautner (no
current address that I know of).
Robert Sanders <gt8134b@prism.gatech.edu> was maintaining and enhancing
the incarnation of DOSEMU with which this man page was originally
distributed. During about 4 years James B. MacLean
<macleajb@ednet.ns.ca> was the restless leader of the dosemu team,
implementation of DPMI (which made Windows-3.1, dos4gw, djgpp, etc.
running) happened during his ’governement’ and brought the project near
to Beta-state. Hans Lermen <lermen@fgan.de> took over and released the
first 1.0 version. Now Bart Oldeman <bart@dosemu.org> is maintaining
this funny software.
BUGS
There are too many to count, much less list.
Please report bugs to the author. I’d also like to hear about which
programs DO work. Just send me a note detailing what program (and what
version) you are using, what works and what doesn’t, etc.
AVAILABILITY
The most recent public version of DOSEMU can be obtained from
www.dosemu.org; a fast mirror is at
ibiblio.unc.edu:/pub/Linux/system/emulators/dosemu/. If you want to
keep up on private developer pre-releases, join the DOSEMU developer
team - even just good detailed debug reports are all you need!
FILES
/usr/bin/dosemu.bin
The binary
/usr/bin/dosemu
The wrapper script, it is recommended not to invoke dosemu.bin
directly.
/usr/bin/xdosemu
Same, but invoking DOS in an X window.
$HOME/.dosemu
Per user DOSEMU local directory. This will be created silently,
if not existing.
$HOME/.dosemu/tmp
All temporary file creation happens here, we do not use /tmp
anymore.
/var/run/dosemu.*
or
$HOME/.dosemu/run
Various files used by DOSEMU including debugger pipes.
$HOME/dosemu/freedos
Bootdirectory containing the FreeDos part.
/etc/dosemu/dosemu.conf
or (only if /etc/dosemu.users exists) /etc/dosemu.conf
Main configuration file for DOSEMU. which is included by
global.conf (global.conf is included in dosemu.bin by
default).
$HOME/.dosemurc
Per-user configuration file.
/etc/dosemu.users
or
/etc/dosemu/dosemu.users
For suid-root or sudo running binaries: Defines the
access rights to DOSEMU on a per user basis and sets some
vital configuration. This is the only fix-location
configuration file, DOSEMU first looks for
/etc/dosemu.users and, if this is not found, for
/etc/dosemu/dosemu.users . Via the keyword
default_lib_dir= in dosemu.users the systemwide
DOSEMU_LIB_DIR directory may be moved elsewhere. For
more information see /usr/share/doc/dosemu/README.txt
/etc/dosemu/dos.ini
IPX configuration file.
doc/DANG.txt
To help you hack DOSEMU code.
/usr/share/doc/dosemu/README.*
Various documentation.
QuickStart, README and INSTALL
To set up DOSEMU quickly.
ChangeLog
Changes in DOSEMU since the last release.
/usr/share/doc/dosemu/README.bindist
Information on how to use the DOSEMU/FreeDos ready-to-use
binary distribution.
MSDOS mailing list
For more information, mail to
linux-msdos@vger.kernel.org
SEE ALSO
dosemu(1), mkfatimage16(1)