Provided by: dosemu_1.4.0+svn.2010-1_amd64 bug

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)