Provided by: dosemu_1.4.0+svn.1828-2ubuntu2_i386 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  taggs  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  DOSEMUs  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 DOSEMUs 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)