dosemu2/man/dosemu.bin.1.in

.\" -*- nroff -*-  (This is for Emacs)
.TH DOSEMU.BIN 1 "@RELEASE_DATE@" "Version @PACKAGE_VERSION@" "DOS Emulation"
.SH NAME
dosemu.bin, dosdebug \- run DOS and DOS programs under Linux
.SH SYNOPSIS
.B dosemu.bin
[
.B \-234ABCcdKkmNnOpSstVwX
]
[
.B \-h
]
[
.B \-F
.I file
]
[
.B \--Fusers
.I file
]
[
.B \--Flibdir
.I directory
]
[
.B \--Fimagedir
.I directory
]
[
.B \-f
.I file
]
[
.B \-u
.I confvar
]
[
.B \-D
.I flags
]
[
.B \-e
.I size
]
[
.B \-x
.I size
]
[
.B \-P
.I file
]
[
.B \-o
.I file
]
[
2\>
.I debugfile
]
[
.B \-I
.I config-options
]
[
.B \-i
.I \h'-1' input_data
]
[
.B \-E
.I dos-command
]
[
.B \-K
.I unix_path[:dos_path]
]
[
.I env1=val1
.I ...
]
[
.I unix_path_to_dos_prog
[
.I --
]
[
.I dos_cmd_args
]
]
.sp
.B dosdebug
.SH DESCRIPTION
.B dosemu.bin
is the binary wrapped by the script
.B dosemu
(1)
which invokes the Linux dos emulator, also known as
.BR DOSEMU .
.br
.I debugfile
is an optional file into which all debugging output will be redirected.
.PP
.B dosdebug
is used to control or debug an already running 
.BR DOSEMU .
.PP
Although this program is known as the DOS
.I 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.
.B 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.
.PP
Because 
.B 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.

.SH 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 
.BR ipc (2))
compiled. SYSV IPC is an option in the configuration setup during a Linux
kernel compile.

.SH OPTIONS
.TP
.I -2,3,4,5
choose 286, 386, 486 or 586 processor to simulate.
.TP
.I -A
boot from floppy disk A (does not need to be a real floppy disk, see below)
.TP
.I -B
boot from floppy disk B (does not need to be a real floppy disk, see below)
.TP
.I -C[num]
boot from hard disk C. If num is specified, the appropriate drive will
become C first. For example, -C1 means rename D to C, then boot from it.
.TP
.I -c[d]
use direct Console video (must be at the console, requires special
privileges, and
.I -s
).
.br
.I -cd
detach from current virtual console or tty and attach to the first free
virtual console
.TP
.I -d path
mount host path as an extra DOS drive. Can be specified multiple times.
.TP
.I -E dos-command
Run DOS command when starting DOSEMU.
The linux path to the command can be given with \-K option.
For example
.nf
dosemu -K /home/joeuser/dosemu/freedos/bin -E "xcopy my_file my_dir"
.fi
will run /home/joeuser/dosemu/freedos/bin/xcopy.exe with 2 arguments.
.br
Note: this only works if your autoexec.bat contains "system \-e"
command.
.TP
.I -K unix_path[:dos_path]
Specify unix path for the program running with \-E.
You can omit \-E and specify the full unix path with \-K, but it is
not recommended and may be removed in the future. You need to specify
a directory path to \-K.
.br
If dos_path is specified, then it is used as a current directory when
invoking the command. If unix_path is empty then the drive letter is
taken from dos_path:
.nf
dosemu -K :C:\\\\games\\\\carma -E carma.exe
.fi
This runs carma.exe from C:\\games\\carma
.TP
.I -T[flags]
Sets flags for -E and -K commands. "flags" is the string of the
following chars:

1: don't terminate DOSEMU after running the command specified either
with -E or -K.

h: try to load the specified command into UMB (loadhigh).

If -T is specified without flags, then "1h" flags string is assumed.
.TP
.I -q
Quiet mode. Suppress all DOS output except that of the command specified
with -E or -K switches.
.br
Note: only works in dumb terminal mode currently.
.TP
.I -k[str]
Set keyboard input type. Plain -k or -kr sets RAW console Keyboard
(must be at the console). Use -kt for TTY and -ks for STDIO inputs.
.TP
.I --Fusers
Bypass dosemu.users and take this file instead (only accepted when
.B dosemu.bin
is
.I not
suid-root).
.TP
.I --Flibdir
Bypass the default DOSEMU_LIB_DIR (as maybe defined in dosemu.users)
and use this directory instead.
.TP
.I --Fimagedir
Bypass the default directory for bootdirectory and hdimages (DOSEMU_IMAGE_DIR)
and use this directory instead.
.TP
.I -f
Parse this config-file instead of .dosemurc. If -n is also specified, then
this config file is parsed instead of the primary dosemu.conf.
.TP
.I -n
Bypass (don't use) default user's config .dosemurc. The config specified
with -f is still parsed, but in that case it replaces the main dosemu.conf.
.TP
.I -L <log_string>
Writes provided <log_string> to a log.
.TP
.I -I
Parse the string behind
.I -I
with the same syntax as global.conf or .dosemurc such as
.TP
		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
.TP
		dos ... \-I "`myconf.sh`"

where
.I myconf.sh
is a script writing the configuration to stdout. If you have an alternate
configuration file besides .dosrc,
.TP
		dos ... \-I "`cat myother.conf`"

will do the job. Note however, that you have to quote the parameter behind
.I -I
because it is expected to be
.I one
argument.
.TP
.I -i input_data
Type
.I input_data
on the emulated keyboard. Use \\r for Enter. Various other special escapes
are available, for example you can insert pauses with "\\p10;" where
10 is a delay in tens of milliseconds.
.TP
.I -D
specify which Debugging messages to allow/suppress
.TP
.I -h
display help.
.TP
.I -H
specify the dosdebug support flags, currently only `1' is is reasonable.
with
.I -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.
.TP
.I -m
toggle internal mouse-support
.TP
.I -O
use stderr for output of Debugging messages
.TP
.I -o
use this file for output of Debugging messages
.TP
.I -P
copy debugging output to FILE
.TP
.I -S
run using SDL
.TP
.I -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
.I -V
and
.I -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.
.TP
.I -t[de[flag]]
terminal mode: run using the S-Lang library by default, or, if 'd'
is specified - use "dumb" terminal mode. If 'de' is specified,
use stderr in dumb terminal mode, except for the output of the
program started with -E that still goes to stdout. If 'de2' is
specified (flag==2), then also the output of -E-started program
goes to stderr.
.TP
.I -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
.I -s
).
.TP
.I -Y
trace DOS boot ([Y/N] prompt for config.sys lines)
.TP
.I -w
toggle windowed/fullscreen mode in X
.TP
.I -X
run in an X Window
.PD 1
.SH HARD DISKS
.B DOSEMU
supports four methods of supplying DOS with hard disks:
.IP 1.
a virtual disk file residing on a Linux filesystem which emulates a hard 
drive.
.IP 2.
direct access to a DOS partition through a raw disk device (i.e. /dev/hda,
/dev/hdb, /dev/sdX).
.IP 3.
direct access to an DOS partition through single partition access 
(i.e. /dev/hda1, /dev/hdb2, /dev/sdxx).
.IP 4.
access to a Linux filesystem as a "network" drive using the driver emufs.sys
supplied with
.B DOSEMU
in commands/emufs.sys or lredir.exe.
.PP
Configuration of
.B DOSEMU's
hard disk resources is done by editing 
.B dosemu.conf
or
.B .dosemurc
before running
.BR DOSEMU .
Look at @docdir@/README.txt.

.SH FLOPPY DISKS
.B DOSEMU
supports two methods of supplying DOS with floppy disks:
.IP 1.
a virtual disk file residing on a Linux filesystem which emulates a floppy
drive
.IP 2.
direct access to a physical floppy through a raw disk device (i.e. /dev/fd0,
/dev/fd1).
.PP
This is also explained more thoroughly in
.B README.txt.
.PP
Configuration of
.B DOSEMU's
floppy disk resources is done by editing the
.B dosemu.conf
before running
.BR DOSEMU .

.SH VIDEO
.B 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
.B DOSEMU
on the console may wish to investigate the 
.I \-c,
.I \-k,
and
.I \-V
switches, explained more thoroughly in
.B README.txt.
There is also some very brief documentation in the file dosemu.conf,
which can be edited for your needs.
.PP
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.

.SH KEYBOARD
Those using 
.B DOSEMU
on the Linux console may also wish to use the RAW
keyboard support.  This mode of operation, selected by the
.I \-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.

.SH 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.

.SH 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
.B DOSEMU
in the examples subdirectory, for debugging 
options.  At the command line, you may specify which classes of messages 
you wish 
.B dos
to allow. The syntax of this is 
.B DOSEMU
takes an option "\-D FLAGS", where FLAGS is a string of letters
which specify which options to print or suppress.
.B 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.

.I 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	F  MMIO

Any debugging classes following a 
.I \+ 
character, up to a 
.I \- 
character, will be turned on (non-suppressed).  Any after a 
.I \-
character, up to a 
.I \+
character, will be suppressed.  The character 
.I a
acts like a string of all possible debugging classes, so 
.I \+a
turns on all debugging messages, and 
.I \-a
turns off all debugging messages.  The characters 
.I 0 
and 
.I 1-9
are also special: 
.I 0
turns off all debugging messages, and 
.I 1-9
turns on all debugging messages, but set the debug level too.

There is an assumed 
.I \+
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
.B /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 
.I -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.

.SH SPECIAL KEYS
In RAW keyboard mode (see the
.BR \-k
option),
.B DOSEMU
responds to certain key sequences as control functions.
.PP
.PD 0
.IP 
ctrl-scrlock   =  show 0x32 int vectors
.IP 
alt-scrlock    =  show the vm86 registers
.IP
rshift-scrlock =  generate an int8 (timer)
.IP
lshift-scrlock =  generate an int9 (keyboard)
.IP
ctrl-break     =  ctrl-break as under DOS.
.IP
ctrl-alt-pgup  =  reboot DOS. Don't trust this!
.IP
ctrl-alt-pgdn  =  exit the emulator
.PD 1
.PP
Use  <LEFT CTRL>-<LEFT ALT>-<Function key> to switch to another virtual
console.

.SH MEMORY
The XMS memory support in
.B 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).
.PP
.B DOSEMU
also supports EMS 4.0 and implements DPMI 0.9 (1.0 partially).


.SH AUTHOR
.B DOSEMU
(comprised of the files
.B dosemu.bin
and 
.B dosemu
) is based on version 0.4 of the original program written by Matthias Lautner
(no current address that I know of).
.PP
Robert Sanders <gt8134b@prism.gatech.edu> was maintaining and enhancing 
the incarnation of 
.B 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.

.SH BUGS
There are too many to count, much less list.  
.PP
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.

.SH AVAILABILITY
The most recent public version of 
.B 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
.B DOSEMU
developer team - even just good detailed debug reports are all you need!

.SH FILES
.PD 0
.TP
.I @bindir@/dosemu.bin
The binary
.TP
.I @bindir@/dosemu
The wrapper script, it is recommended not to invoke dosemu.bin directly.
.TP
.I @bindir@/xdosemu
Same, but invoking DOS in an X window.
.TP
.I $HOME/.dosemu
Per user
.B DOSEMU
local directory. This will be created silently, if not
existing.
.TP
.I $HOME/.dosemu/tmp
All temporary file creation happens here, we do not use /tmp anymore.
.TP
.I /var/run/dosemu.*
or
.TP
.I $HOME/.dosemu/run
Various files used by
.B DOSEMU
including debugger pipes.
.TP
.TP
.I $HOME/dosemu/freedos
Bootdirectory containing the FreeDos part.
.TP
.I @sysconfdir@/dosemu.conf
or (only if /etc/dosemu.users exists)
.I /etc/dosemu.conf
Main configuration file for
.BR DOSEMU .
which is included by
.I global.conf
(global.conf is included in dosemu.bin by default).
.TP
.I $HOME/.dosemurc
Per-user configuration file.
.TP
.I /etc/dosemu.users
or
.TP
.I @sysconfdir@/dosemu.users
For suid-root or sudo running binaries: Defines the access rights to
.BR DOSEMU
on a per user basis and sets some vital configuration. This is the only
fix-location configuration file,
.BR DOSEMU
first looks for
.I /etc/dosemu.users
and, if this is not found, for
.I @sysconfdir@/dosemu.users .
Via the keyword
.I default_lib_dir=
in
.I dosemu.users
the systemwide
.I DOSEMU_LIB_DIR
directory may be moved elsewhere.
For more information see
.I @docdir@/README.txt
.TP
.I @sysconfdir@/dos.ini
IPX configuration file.

.TP
.I doc/DANG.txt
To help you hack
.B DOSEMU
code.
.TP
.I @docdir@/README.*
Various documentation.
.TP
.I README and INSTALL
To set up
.B DOSEMU
quickly.
.TP
.I ChangeLog
Changes in
.B DOSEMU
since the last release.
.TP
.I @docdir@/README.bindist
Information on how to use the DOSEMU/FreeDos ready-to-use binary
distribution.
.TP
.I MSDOS mailing list
For more information, mail to
.IP linux-msdos@vger.kernel.org



.SH "SEE ALSO"
.BR dosemu "(1), " mkfatimage16 "(1)"