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
preconfigured 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 InterProcess Communication facilities, see
ipc(2))
compiled. SYSV IPC is an option in the configuration setup during a Linux
kernel compile.
OPTIONS
-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 a
msdos filesystem, see below)
-c
use direct Console video (must be at the console, requires that
dos
is suid root)
-d
detach from current virtual console or tty and attach to the first free
virtual console
-V
use VGA specific video optimizations
-k
use RAW console Keyboard (must be at the console)
-F
Parse this config-script instead of DOSEMU_LIB_DIR/global.conf
(you need to run as root on suid DOSEMU for this)
--Fusers
Bypass /etc/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 /etc/dosemu.users)
and use this directory instead (only accepted when
dosemu.bin
is
not
suid-root).
--Fimagedir
Bypass the default directory for bootdirectory and hdimages (DOSEMU_LIB_DIR)
and use this directory instead (only accepted when
dosemu.bin
is
not
suid-root).
-f
Parse this config-file instead of .dosemurc
-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 DOSEMU_LIB_DIR/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 usefull 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.
-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 singlestep through the bootstrap code.
-O
use stderr for output of Debugging messages
-o
use this file for output of Debugging messages
-M
set base memory to SIZE Kilobytes
-m
enable internal mouse-support
-P
copy debugging output to FILE
-2,3,4
choose 286, 386, or 486 processor (BE CAREFUL!
DOSEMU
is not yet 32-bit clean,
so if your program detects a 386 or 486 processor and uses 32-bit registers,
it might be confused by BIOS functions. If you think this is happening, use
-2 to force
DOSEMU
into 286-mode.)
-U
define inpipe and outpipe for asynchronous control of
DOSEMU
from an other process. The format is (whithout white spaces 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 taggs via `outpipe' such that the frontend knows
when the control command has started or finished and wether 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
programm. 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.
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). You need to run the program
mkpartition
to enable
DOSEMU
to access your DOS-partitions with SPA.
4.
access to a Linux filesystem as a "network" drive using the driver emufs.sys
supplied with
DOSEMU
in commands/emufs.sys.
This is explained more thoroughly in
QuickStart.
Configuration of
DOSEMU's
hard disk resources is done by editing
dosemu.conf
before running
DOSEMU.
Look at doc/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
QuickStart.
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
QuickStart.
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
to a set of files,
dosemulpt1, dosemulpt2,
and
dosemulpt3,
corresponding to the DOS printer devices LPT1, LPT2, and LPT3.
All characters sent to LPTx will be redirected to the file dosemulptx in
the current directory.
WARNING!DOSEMU
does not keep the file buffers flushed; therefore, the state of these
files is undefined until you actually exit the DOS emulator. Please
excuse the inconvenience.
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 diskR disk readW disk write
D int 21hC cdromv video
X X supportk keyboardi port I/O
s serialm mouse# default ints
p printerg generalc configuration
w warningh hardwareI IPC
E EMSx XMSM DPMI
n IPX networkP Pkt-driverS SOUND
r PICT IO-tracingZ PCI-BIOS
A ASPI driverQ 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).
While I have implemented the UMB functions, they are extremely stupid and
will almost always act suboptimally. The next release of
DOSEMU
should
have saner UMB support.
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,
e.t.c running) happened during his 'governement' and brought the project
near to Beta-state.
Now Hans Lermen <lermen@fgan.de> 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 ftp'ed from ftp.dosemu.org in the /pub/dosemu directory, a fast
mirror for this is 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, its 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/conf
$HOME/dosemu/bin
Various files used by the
DOSEMU
per-user instance. This directory also holds the global,conf configuration script
global.conf
for
DOSEMU
which then includes
dosemu.conf
$HOME/dosemu/freedos
Bootdirectory containig the FreeDos part.
dosemu.conf
Main configuration file for
DOSEMU.
which is included by
global.conf
/etc/dosemu.users
or
/etc/dosemu/dosemu.users
For suid-root 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 elsewere.
For more information see
./doc/README.txt
/etc/dosemu/dos.ini
IPX configuration file.
doc/DPR
Dosemu development team: Who is doing which part of the
DOSEMU
project?
doc/DANG
To help you hack
DOSEMU
code.
doc/README.*
Various documentation.
QuickStart
To set up
DOSEMU
quickly.
ChangeLog
Changes in
DOSEMU
since the last release.
README.bindist
Information on how to use the DOSEMU/FreeDos ready-to-use binary
distribution.
README.distributors
Informations for Linux distributors on how to package systemwide
installations of
DOSEMU.