Penguin
Recent Changes
Annotated edit history of dosdebug(1) version 3, including all changes. View license author blame.
Rev Author # Line
1 perry 1 DOSEMU.BIN
2 !!!DOSEMU.BIN
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 KERNEL REQUIREMENTS
7 OPTIONS
8 HARD DISKS
9 FLOPPY DISKS
10 VIDEO
11 KEYBOARD
12 PRINTING
13 DEBUG MESSAGES
14 SPECIAL KEYS
15 MEMORY
16 AUTHOR
17 BUGS
18 AVAILABILITY
19 FILES
20 SEE ALSO
21 ----
22 !!NAME
23
24
25 dosemu.bin, dosdebug - run DOS and DOS programs under Linux
26 !!SYNOPSIS
27
28
29 __dosemu.bin__ [[ __-ABCcdkVNXtsgKm234OU__ ] [[
30 __-h__ ''level'' ] [[ __-F__ ''file'' ] [[
31 __--Fusers__ ''file'' ] [[ __--Flibdir__
32 ''directory'' ] [[ __--Fimagedir__ ''directory'' ] [[
33 __-f__ ''file'' ] [[ __-L__ ''dexefile'' ] [[
34 __-u__ ''confvar'' ] [[ __-D__ ''flags'' ] [[
35 __-M__ ''size'' ] [[ __-e__ ''size'' ] [[
36 __-x__ ''size'' ] [[ __-P__ ''file'' ] [[
37 __-o__ ''file'' ] [[ 2''debugfile'' ] [[
38 __-I__ ''config-options'' ] [[ __-U__
39 ''inpipe[[:outpipe]'' ]
40
41
42 __dosdebug__
43 !!DESCRIPTION
44
45
46 __dosemu.bin__ is the binary wrapped by the script
47 __dosemu__ (1) which invokes the Linux dos emulator, also
48 known as __DOSEMU__.''
49 debugfile'' is an optional file into which all debugging
50 output will be redirected.
51
52
53 __dosdebug__ is used to control or debug an already
54 running __DOSEMU__.
55
56
57 Although this program is known as the DOS ''emulator,''
58 it is actually a virtual machine for DOS, allowing DOS and
59 programs written for DOS to operate in an environment
60 similar to a standard IBM PC/AT or compatible with an Intel
61 80x86 processor in real mode. __DOSEMU__ provides
62 emulation of such services as BIOS video, disk, keyboard,
63 serial, and printer; CMOS memory for configuration
64 information; a real time clock; memory allocation through
65 the XMS 3.0 specification, EMS 4.0 and DPMI
66 0.9.
67
68
69 Because __DOSEMU__ is not really a DOS emulator, a copy
2 perry 70 of !FreeDos is required, which now is preconfigured and part
1 perry 71 of the official DOSEMU binary distribution. In addition any
72 currently available proprietary DOS (such as MS-DOS, PC-DOS,
73 DR-DOS) can be booted, when properly
74 configured.
75 !!KERNEL REQUIREMENTS
76
77
78 At present, you will need Linux 2.0.28 or above with the
2 perry 79 SYSV IPC option (System V !InterProcess Communication
1 perry 80 facilities, see ipc(2)) compiled. SYSV IPC is an
81 option in the configuration setup during a Linux kernel
82 compile.
83 !!OPTIONS
84
85
86 ''-A''
87
88
89 boot from floppy disk A (does not need to be a real floppy
90 disk, see below)
91
92
93 ''-B''
94
95
96 boot from floppy disk B (does not need to be a real floppy
97 disk, see below)
98
99
100 ''-C''
101
102
103 boot from hard disk C (does not need to be a real hard disk
104 or even a msdos filesystem, see below)
105
106
107 ''-c''
108
109
110 use direct Console video (must be at the console, requires
111 that __dos__ is suid root)
112
113
114 ''-d''
115
116
117 detach from current virtual console or tty and attach to the
118 first free virtual console
119
120
121 ''-V''
122
123
124 use VGA specific video optimizations
125
126
127 ''-k''
128
129
130 use RAW console Keyboard (must be at the
131 console)
132
133
134 ''-F''
135
136
137 Parse this config-script instead of
138 DOSEMU_LIB_DIR/global.conf (you need to run as root on suid
139 DOSEMU for this)
140
141
142 ''--Fusers''
143
144
145 Bypass /etc/dosemu.users and take this file instead (only
146 accepted when __dosemu.bin__ is ''not''
147 suid-root).
148
149
150 ''--Flibdir''
151
152
153 Bypass the default DOSEMU_LIB_DIR (as maybe defined in
154 /etc/dosemu.users) and use this directory instead (only
155 accepted when __dosemu.bin__ is ''not''
156 suid-root).
157
158
159 ''--Fimagedir''
160
161
162 Bypass the default directory for bootdirectory and hdimages
163 (DOSEMU_LIB_DIR) and use this directory instead (only
164 accepted when __dosemu.bin__ is ''not''
165 suid-root).
166
167
168 ''-f''
169
170
171 Parse this config-file instead of .dosemurc
172
173
174 ''-u''
175
176
177 set a user configuration variable. An __u___ is prefixed
178 to the name to avoid name clashes. This variable then can be
179 checked in dosemu.conf or DOSEMU_LIB_DIR/global.conf to do
180 some special configuration.
181
182
183 ''-L''
184
185
186 Load and start a DEXE file (special preconfigured bootable
187 hdimage containing just one DOS application)
188
189
190 ''-I''
191
192
193 Parse the string behind ''-I'' with the same syntax as
194 global.conf or .dosemurc such as
195
196
197 dos ... -I 'video { mda }'
198
199
200 This is usefull if you just want to override a given
201 configuration parameter temporary. You also may have a
202 generic configuration by executing a script such
203 as
204
205
206 dos ... -I
207
208
209 where ''myconf.sh'' is a script writing the configuration
210 to stdout. If you have an alternate configuration file
211 besides .dosrc,
212
213
214 dos ... -I
215
216
217 will do the job. Note however, that you have to quote the
218 parameter behind ''-I'' because it is expected to be
219 ''one'' argument.
220
221
222 ''-D''
223
224
225 specify which Debugging messages to
226 allow/suppress
227
228
229 ''-h''
230
231
232 dump configuration to stderr and exit (implicit sets -D+c).
233 This is useful for debugging configuration files, you should
234 use ''-O'' too to direct the +c type messages to stderr.
235 `level' can be 0, 1 or 2 and controls the amount of
236 configuration parser debug output: No parser debug (0),
237 parser loop debug (1), if_else_endif debug (2).
238
239
240 ''-H''
241
242
243 specify the dosdebug support flags, currently only `1' is is
244 reasonable. with ''-H1'' you force dosemu to wait until
245 the dosdebug terminal has connected. Hence to debug a DOS
246 session from the very beginning you first start dosemu with
247 -H1 and then start dosdebug. DOSEMU will then lock before
248 jumping into the loaded bootsector waiting for dosdebug to
249 connect. Once connected you are in `stopped' state and can
250 set breakpoints or singlestep through the bootstrap
251 code.
252
253
254 ''-O''
255
256
257 use stderr for output of Debugging messages
258
259
260 ''-o''
261
262
263 use this file for output of Debugging messages
264
265
266 ''-M''
267
268
269 set base memory to SIZE Kilobytes
270
271
272 ''-m''
273
274
275 enable internal mouse-support
276
277
278 ''-P''
279
280
281 copy debugging output to FILE
282
283
284 ''-2,3,4''
285
286
287 choose 286, 386, or 486 processor (BE CAREFUL! __DOSEMU__
288 is not yet 32-bit clean, so if your program detects a 386 or
289 486 processor and uses 32-bit registers, it might be
290 confused by BIOS functions. If you think this is happening,
291 use -2 to force __DOSEMU__ into 286-mode.)
292
293
294 ''-U''
295
296
297 define inpipe and outpipe for asynchronous control of
298 __DOSEMU__ from an other process. The format is (whithout
299 white spaces between)
300
301
302 inpipe:outpipe
303
304
305 where `:outpipe' can be omitted. In the latter case no
306 feedback from __DOSEMU__ can be expected.
307
308
309 For security reasons __DOSEMU__ does not create the named
310 pipes itself, so the user is responsible to set the
311 permissions of the pipes correctly. Note that when using
312 this options, the foreign process can control your
313 __DOSEMU__ session (such as entering keystrokes). This
314 option should therefor only used by frontends (such as
315 kdos), which first create the proper named pipes and then
316 launch __DOSEMU.__ A special control command ( ''ack
317 on'' ) can be used to force __DOSEMU__ returning
318 handshake taggs via `outpipe' such that the frontend knows
319 when the control command has started or finished and wether
320 it was successful. The format of this tagging
321 is
322
323
324 SYN:
325
326
327
328
329 ACK: code=n
330
331
332 where ''n'' is 0 for success. A tiny control terminal,
333 which can serve as example, is the supplied ''dosctrl''
334 programm. It takes just the two pipes as arguments and you
335 may then enter control commands, which of them `help' is the
336 most important one;-) Note that ''dosctrl'' does not
337 launch __DOSEMU,__ you have to do it
338 yourself.
339 !!HARD DISKS
340
341
342 __DOSEMU__ supports four methods of supplying DOS with
343 hard disks:
344
345
346 1.
347
348
349 a virtual disk file residing on a Linux filesystem which
350 emulates a hard drive.
351
352
353 2.
354
355
356 direct access to a DOS partition through a raw disk device
357 (i.e. /dev/hda, /dev/hdb, /dev/sdX).
358
359
360 3.
361
362
363 direct access to an DOS partition through single partition
364 access (i.e. /dev/hda1, /dev/hdb2, /dev/sdxx). You need to
365 run the program __mkpartition__ to enable __DOSEMU__
366 to access your DOS-partitions with SPA.
367
368
369 4.
370
371
372 access to a Linux filesystem as a
373 DOSEMU__ in
374 commands/emufs.sys.
375
376
377 This is explained more thoroughly in
2 perry 378 __!QuickStart.__
1 perry 379
380
381 Configuration of __DOSEMU's__ hard disk resources is done
382 by editing __dosemu.conf__ before running __DOSEMU__.
383 Look at doc/README.txt.
384 !!FLOPPY DISKS
385
386
387 __DOSEMU__ supports two methods of supplying DOS with
388 floppy disks:
389
390
391 1.
392
393
394 a virtual disk file residing on a Linux filesystem which
395 emulates a floppy drive
396
397
398 2.
399
400
401 direct access to a physical floppy through a raw disk device
402 (i.e. /dev/fd0, /dev/fd1).
403
404
405 This is also explained more thoroughly in
2 perry 406 __!QuickStart.__
1 perry 407
408
409 Configuration of __DOSEMU's__ floppy disk resources is
410 done by editing the __dosemu.conf__ before running
411 __DOSEMU__.
412 !!VIDEO
413
414
415 __DOSEMU__ may be run on any tty device. However,
416 increased performance and functionality may be had by taking
417 advantage of special features of the Linux console. Those
418 running __DOSEMU__ on the console may wish to investigate
419 the ''-c, -k,'' and ''-V'' switches, explained more
2 perry 420 thoroughly in __!QuickStart.__ There is also some very
1 perry 421 brief documentation in the file dosemu.conf, which can be
422 edited for your needs.
423
424
425 In brief, proper use of the console device and the
426 corresponding switches allows the user to view a DOS program
427 in its original color and font, with none of the periodic
428 screen update problems with the generic tty output
429 code.
430 !!KEYBOARD
431
432
433 Those using __DOSEMU__ on the Linux console may also wish
434 to use the RAW keyboard support. This mode of operation,
435 selected by the ''-k'' switch, provides the user with
436 access to the entire keyboard accessible under DOS. Any
437 combination of ALT, CTRL, and SHIFT keys may be used to
438 generate the odd keycodes expected by many DOS
439 programs.
440 !!PRINTING
441
442
443 The BIOS printer services are emulated through standard UNIX
444 file I/O to a set of files, ''dosemulpt1, dosemulpt2,''
445 and ''dosemulpt3,'' corresponding to the DOS printer
446 devices LPT1, LPT2, and LPT3. All characters sent to LPTx
447 will be redirected to the file dosemulptx in the current
448 directory.
449
450
451 __WARNING! DOSEMU__ does not keep the file buffers
452 flushed; therefore, the state of these files is undefined
453 until you actually exit the DOS emulator. Please excuse the
454 inconvenience.
455 !!DEBUG MESSAGES
456
457
458 Debug messages can be controlled either at the command line
459 or in the configuration file. Take a look at the
460 documentation inside the config.dist file included with
461 __DOSEMU__ in the examples subdirectory, for debugging
462 options. At the command line, you may specify which classes
463 of messages you wish __dos__ to allow. The syntax of this
464 is __DOSEMU__ takes an option
465 __DOSEMU__ parses this string from
466 left to right.
467
468
469 + turns the following options on (initial state) - turns the
470 following options off a turns all the options on/off,
471 depending on flag 0 turns all options off 1-9 sets the debug
472 level, the higher, the more output # where # is a letter
473 from the valid class list, turns that option off/on
474 depending on the +/- state.
475
476
477 ''Message Classes:''
478
479
480 d disk R disk read W disk write D int 21h C cdrom v video X
481 X support k keyboard i port I/O s serial m mouse # default
482 ints p printer g general c configuration w warning h
483 hardware I IPC E EMS x XMS M DPMI n IPX network P Pkt-driver
484 S SOUND r PIC T IO-tracing Z PCI-BIOS A ASPI driver Q
485 mapping driver
486
487
488 Any debugging classes following a ''+'' character, up to
489 a ''-'' character, will be turned on (non-suppressed).
490 Any after a ''-'' character, up to a ''+'' character,
491 will be suppressed. The character ''a'' acts like a
492 string of all possible debugging classes, so ''+a'' turns
493 on all debugging messages, and ''-a'' turns off all
494 debugging messages. The characters ''0'' and ''1-9''
495 are also special: ''0'' turns off all debugging messages,
496 and ''1-9'' turns on all debugging messages, but set the
497 debug level too.
498
499
500 There is an assumed ''+'' at the beginning of the FLAGS
501 string. Some classes, such as error, can not be turned off.
502 In case you didn't redirect stderr, nearly all output to
503 stderr goes to __/dev/null.__
504
505
506 Some examples:
507
508
509 Any option letter can occur in any place. Even pointless
510 combinations, such as ''-D01-a-1+0,'' will be parsed
511 without error, so be careful. Some options are set by
512 default, some are clear. This is subject to my whim, and
513 will probably change between releases. You can ensure which
514 are set by always explicitly specifying them.
515 !!SPECIAL KEYS
516
517
518 In RAW keyboard mode (see the __-k__ option),
519 __DOSEMU__ responds to certain key sequences as control
520 functions.
521
522
523 ctrl-scrlock = show 0x32 int vectors
524
525
526 alt-scrlock = show the vm86 registers
527
528
529 rshift-scrlock = generate an int8 (timer)
530
531
532 lshift-scrlock = generate an int9 (keyboard)
533
534
535 ctrl-break = ctrl-break as under DOS.
536
537
538 ctrl-alt-pgup = reboot DOS. Don't trust this!
539
540
541 ctrl-alt-pgdn = exit the emulator
542
543
544 Use
545 !!MEMORY
546
547
548 The XMS memory support in __DOSEMU__ conforms to
549 Lotus/Intel/Microsoft/AST extended memory specification 3.0.
550 I have implemented all XMS functions except function 0x12
551 (Reallocate Upper Memory Block).
552
553
554 While I have implemented the UMB functions, they are
555 extremely stupid and will almost always act suboptimally.
556 The next release of __DOSEMU__ should have saner UMB
557 support.
558
559
560 __DOSEMU__ also supports EMS 4.0 and implements DPMI 0.9
561 (1.0 partially).
562 !!AUTHOR
563
564
565 __DOSEMU__ (comprised of the files __dosemu.bin__ and
566 __dosemu__ ) is based on version 0.4 of the original
567 program written by Matthias Lautner (no current address that
568 I know of).
569
570
571 Robert Sanders
572 DOSEMU__
573 with which this man page was originally distributed. During
2 perry 574 about 4 years James B. !MacLean
1 perry 575 __
576 !!BUGS
577
578
579 There are too many to count, much less list.
580
581
582 Please report bugs to the author. I'd also like to hear
583 about which programs DO work. Just send me a note detailing
584 what program (and what version) you are using, what works
585 and what doesn't, etc.
586 !!AVAILABILITY
587
588
589 The most recent public version of __DOSEMU__ can be
590 ftp'ed from ftp.dosemu.org in the /pub/dosemu directory, a
591 fast mirror for this is
592 ibiblio.unc.edu:/pub/Linux/system/emulators/dosemu/. If you
593 want to keep up on private developer pre-releases, join the
594 __DOSEMU__ developer team - even just good detailed debug
595 reports are all you need!
596 !!FILES
597
598
599 ''/usr/bin/dosemu.bin''
600
601
602 The binary
603
604
605 ''/usr/bin/dosemu''
606
607
608 The wrapper script, its recommended not to invoke dosemu.bin
609 directly.
610
611
612 ''/usr/bin/xdosemu''
613
614
615 Same, but invoking DOS in an X window.
616
617
618 ''$HOME/.dosemu''
619
620
621 Per user __DOSEMU__ local directory. This will be created
622 silently, if not existing.
623
624
625 ''$HOME/.dosemu/tmp''
626
627
628 All temporary file creation happens here, we do not use /tmp
629 anymore.
630
631
632 ''/var/run/dosemu.*''
633
634
635 or
636
637
638 ''$HOME/.dosemu/run''
639
640
641 Various files used by __DOSEMU__ including debugger
642 pipes.
643
644
645 ''$HOME/dosemu/conf''
646
647
648 ''$HOME/dosemu/bin''
649
650
651 Various files used by the __DOSEMU__ per-user instance.
652 This directory also holds the global,conf configuration
653 script ''global.conf'' for __DOSEMU__ which then
654 includes ''dosemu.conf''
655
656
657 ''$HOME/dosemu/freedos''
658
659
2 perry 660 Bootdirectory containig the !FreeDos part.
1 perry 661
662
663 ''dosemu.conf''
664
665
666 Main configuration file for __DOSEMU__. which is included
667 by ''global.conf''
668
669
670 ''/etc/dosemu.users''
671
672
673 or
674
675
676 ''/etc/dosemu/dosemu.users''
677
678
679 For suid-root running binaries: Defines the access rights to
680 __DOSEMU__ on a per user basis and sets some vital
681 configuration. This is the only fix-location configuration
682 file, __DOSEMU__ first looks for ''/etc/dosemu.users''
683 and, if this is not found, for ''/etc/dosemu/dosemu.users
684 .'' Via the keyword ''default_lib_dir='' in
685 ''dosemu.users'' the systemwide ''DOSEMU_LIB_DIR''
686 directory may be moved elsewere. For more information see
687 ''./doc/README.txt''
688
689
690 ''/etc/dosemu/dos.ini''
691
692
693 IPX configuration file.
694
695
696 ''doc/DPR''
697
698
699 Dosemu development team: Who is doing which part of the
700 __DOSEMU__ project?
701
702
703 ''doc/DANG''
704
705
706 To help you hack __DOSEMU__ code.
707
708
709 ''doc/README.*''
710
711
712 Various documentation.
713
714
2 perry 715 ''!QuickStart''
1 perry 716
717
718 To set up __DOSEMU__ quickly.
719
720
2 perry 721 ''!ChangeLog''
1 perry 722
723
724 Changes in __DOSEMU__ since the last
725 release.
726
727
728 ''README.bindist''
729
730
2 perry 731 Information on how to use the DOSEMU/!FreeDos ready-to-use
1 perry 732 binary distribution.
733
734
735 ''README.distributors''
736
737
738 Informations for Linux distributors on how to package
739 systemwide installations of __DOSEMU.__
740
741
742 ''MSDOS mailing list''
743
744
745 For more information, mail to
746
747
748 linux-msdos@vger.rutgers.edu
749 !!SEE ALSO
750
751
3 perry 752 dosemu(1), mkfatimage16(1)
1 perry 753 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.