xenial (1) dosdebug.1.gz

Provided by: dosemu_1.4.0.7+20130105+b028d3f-2_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)