Change some documentation mentioning ports to pkgsrc.
[dragonfly.git] / usr.bin / doscmd / doscmd.1
1 .\"
2 .\" Copyright (c) 1992, 1993, 1996
3 .\"     Berkeley Software Design, Inc.  All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\"    notice, this list of conditions and the following disclaimer in the
12 .\"    documentation and/or other materials provided with the distribution.
13 .\" 3. All advertising materials mentioning features or use of this software
14 .\"    must display the following acknowledgement:
15 .\"     This product includes software developed by Berkeley Software
16 .\"     Design, Inc.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY Berkeley Software Design, Inc. ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL Berkeley Software Design, Inc. BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\"     BSDI doscmd.1,v 2.3 1996/04/08 19:32:29 bostic Exp
31 .\" $FreeBSD: src/usr.bin/doscmd/doscmd.1,v 1.12.2.11 2002/06/20 23:45:41 charnier Exp $
32 .\" $DragonFly: src/usr.bin/doscmd/doscmd.1,v 1.5 2006/04/17 17:40:34 swildner Exp $
33 .\"
34 .Dd January 30, 1995
35 .Dt DOSCMD 1
36 .Os
37 .Sh NAME
38 .Nm doscmd
39 .Nd run a subset of real-mode DOS programs
40 .Sh SYNOPSIS
41 .Nm
42 .Fl 23AbDEfGHIMOPRrtVvXxYz
43 .Fl c Ar file
44 .Fl d Ar file
45 .Fl i Ar port Ns Xo
46 .Op : Ns Ar cnt
47 .Xc
48 .Fl o Ar port Ns Xo
49 .Op : Ns Ar cnt
50 .Xc
51 .Fl S Ar int
52 .Fl U Ar int
53 .Op Ar cmd Op Ar args ...
54 .Sh DESCRIPTION
55 The
56 .Nm
57 utility can either emulate a subset of DOS and run the
58 single command
59 .Ar cmd
60 .Ar args ,
61 or it can be used to emulate a PC and boot DOS,
62 which allows it to run a larger variety of DOS applications.
63 It should be noted that MS DOS 6.2 and higher appear
64 to cause difficulties for
65 .Nm .
66 To boot DOS, either provide the
67 .Fl b
68 flag or omit the
69 .Ar cmd
70 argument.
71 If
72 .Fl b
73 is specified,
74 .Ar cmd
75 and
76 .Ar args
77 are ignored.
78 .Pp
79 Although
80 .Nm
81 only provides a subset of DOS, it is sufficient to run a variety of
82 programs, including, but not limited to, compilers, assemblers and
83 linker-loaders.
84 .Pp
85 The various flags available to
86 .Nm
87 are:
88 .Bl -tag -width indent
89 .It Fl 2
90 Enable debugging traces of every trap to the
91 .Nm
92 emulator from the DOS program.
93 Note that some traps are handled in the kernel and hence will not
94 be traced.
95 .It Fl 3
96 Enable debugging of several lower level functions, such
97 as changing of interrupt vectors and initializing paths to logical drives.
98 .\"
99 .\"
100 .\"
101 .It Fl A
102 Enable tracing of all interrupts that pass into the emulator.
103 This is the same as using the
104 .Fl S
105 option with all 256 possible interrupt values.
106 .\"
107 .\"
108 .\"
109 .It Fl b
110 Attempt to boot DOS rather than emulate it.
111 .\"
112 .\"
113 .\"
114 .It Fl c Ar file
115 Capture all output directed at the screen into
116 .Ar file .
117 Note that direct screen writes will not be captured.
118 .\"
119 .\"
120 .\"
121 .It Fl C
122 List MS-DOS calls emulated and their return values.
123 .\"
124 .\"
125 .\"
126 .It Fl D
127 Enable debugging of the disk and file operations.
128 .\"
129 .\"
130 .\"
131 .It Fl d Ar file
132 Send the debug output to
133 .Ar file
134 instead of stderr.
135 .\"
136 .\"
137 .\"
138 .It Fl E
139 Enable debugging of the exec routines.
140 .\"
141 .\"
142 .\"
143 .It Fl G
144 Enable debugging of the video (graphics) routines.
145 .\"
146 .\"
147 .\"
148 .It Fl H
149 Enable tracing of half implemented calls.
150 .\"
151 .\"
152 .\"
153 .It Fl I
154 Enable tracing of all interrupts.  Almost the same as
155 .Fl A
156 except a few less traces are turned on.
157 .\"
158 .\"
159 .\"
160 .It Fl i Ar port Ns Xo
161 .Op : Ns Ar cnt
162 .Xc
163 Enable tracing of all inputs requested from the io
164 .Ar port .
165 If
166 .Ar cnt
167 is present, trace from
168 .Ar port
169 to
170 .Ar port+cnt Ns No -1 .
171 .\"
172 .\"
173 .\"
174 .It Fl M
175 Enable debugging of the memory operations.
176 .\"
177 .\"
178 .\"
179 .It Fl O
180 Direct the debugging output to stdout rather than stderr.
181 .\"
182 .\"
183 .\"
184 .It Fl o Ar port Ns Xo
185 .Op : Ns Ar cnt
186 .Xc
187 Enable tracing of all outputs requested from the io
188 .Ar port .
189 If
190 .Ar cnt
191 is present, trace from
192 .Ar port
193 to
194 .Ar port+cnt Ns No -1 .
195 .\"
196 .\"
197 .\"
198 .It Fl p Ar port Ns Xo
199 .Op : Ns Ar cnt
200 .Xc
201 Map the requested io
202 .Ar port
203 (with optional range up to to
204 .Ar port+cnt Ns No -1 )
205 to the real hardware I/O port(s).
206 This will likely require root privs to access them.
207 .\"
208 .\"
209 .\"
210 .It Fl P
211 Enable tracing of io port calls (such as
212 .Li inb ,
213 .Li outb ,
214 etc).
215 .\"
216 .\"
217 .\"
218 .It Fl R
219 Enable debugging of the file redirect code.
220 .\"
221 .\"
222 .\"
223 .It Fl r
224 Use the raw keyboard and display.  Pressing <CTRL-ALT-DEL> will
225 cause doscmd to exit.  This allows use of VGA graphics.
226 .\"
227 .\"
228 .\"
229 .It Fl S Ar int
230 Enable tracing of the interrupt
231 .Ar int .
232 .\"
233 .\"
234 .\"
235 .It Fl t
236 Attempt to do instruction level tracing.
237 Some instructions confuse the trace.
238 Pressing
239 .Li <CTRL-ALT-T>
240 attempts to toggle the trace mode on and off.
241 .\"
242 .\"
243 .\"
244 .It Fl U Ar int
245 Disable tracing of the interrupt
246 .Ar int .
247 Useful after
248 .Fl A
249 or
250 .Fl I .
251 .\"
252 .\"
253 .\"
254 .It Fl V
255 Include register dumps when reporting unknown interrupts.
256 .\"
257 .\"
258 .\"
259 .It Fl v
260 Same as
261 .Fl AH
262 .\"
263 .\"
264 .\"
265 .It Fl X
266 Enable debugging of the XMS operations.
267 .\"
268 .\"
269 .\"
270 .It Fl x
271 Open an X11 window to display output.  This enables a
272 variety interrupts not available otherwise.  This
273 can be used with or without
274 .Fl b .
275 .\"
276 .\"
277 .\"
278 .It Fl Y
279 Enable debugging of the EMS operations.
280 .\"
281 .\"
282 .\"
283 .It Fl z
284 Cause
285 .Nm
286 to pause just prior to jumping to the DOS program.
287 Very little use except for developing
288 .Nm .
289 .El
290 .Pp
291 When starting up,
292 .Nm
293 attempts to read a configuration file.  First the file
294 .Cm .doscmdrc
295 in the current directory.  If not found there, the
296 .Cm $HOME
297 directory is searched.  If still not found, the file
298 .Cm /etc/doscmdrc
299 is used.
300 .Pp
301 In the configuration file, a comment is started with the \fB#\fP character.
302 Blank lines are ignored.
303 Non empty lines either are environment variables
304 or commands which configure devices.
305 Any line which has an \fB=\fP before any white space is considered to be
306 an environment variable assignment and is added to the DOS environment.
307 The rest of the lines are one of the following
308 .Bl -tag -width XXXXX
309 .\"
310 .\"
311 .\"
312 .It Cm boot Op Cm A: | C:
313 Set the device to boot from.
314 By default
315 .Cm A:
316 is first tried, if it is defined, and if that fails,
317 .Cm C:
318 is tried.
319 .\"
320 .\"
321 .\"
322 .It Cm assign Xo
323 .Op Cm A-Z :
324 .Op Fl ro
325 .Ar path
326 .Xc
327 Assigns the
328 .Bsx
329 directory
330 .Ar path
331 to be assigned as the specified drive.  If the
332 .Fl ro
333 flag is specified, it is a read only file system.
334 These assignments will not take place when booting DOS until the
335 .Pa /usr/libdata/doscmd/redir.com
336 binary is run.
337 .\"
338 .\"
339 .\"
340 .It Cm assign Xo
341 .Cm lpt Ns Op Cm 0-4 :
342 .Op Cm direct
343 .Ar path
344 .Op Ar timeout
345 .Xc
346 Attempt to assign the specified printer to
347 .Ar path .
348 If
349 .Ar timeout
350 is specified then use it as the length of time for no
351 activity (in seconds) to indicate that the printer
352 should be flushed.  The default is 30 seconds.
353 The
354 .Cm direct
355 option should be set when
356 .Ar path
357 refers to a real printer.
358 .\"
359 .\"
360 .\"
361 .It Cm assign Xo
362 .Op Cm A: | B:
363 .Op Fl ro
364 .Ar path
365 .Ar density
366 .Xc
367 .It Cm assign Xo
368 .Cm flop Ns Op Cm 01
369 .Op Fl ro
370 .Ar path
371 .Ar density
372 .Xc
373 Assign the file
374 .Ar path
375 to be used as either the next available floppy or
376 to the specified floppy.
377 If
378 .Fl ro
379 is specified the floppy will be read only.
380 The
381 .Ar density
382 may be one of:
383 .Pp
384 .Bl -tag -compact -width 1440x
385 .It 180
386 9 head 40 track single sided floppy
387 .It 360
388 9 head 40 track double sided floppy
389 .It 720
390 9 head 80 track double sided floppy
391 .It 1200
392 15 head 80 track double sided floppy
393 .It 1440
394 18 head 80 track double sided floppy
395 .It 2880
396 36 head 80 track double sided floppy
397 .El
398 .\"
399 .\"
400 .\"
401 .It Cm assign Xo
402 .Op Cm C-Z  :
403 .Op Fl ro
404 .Ar path
405 .Op Ar type | cyl head sec
406 .Op Ar fdisk_tab
407 .Xc
408 .It Cm assign Xo
409 .Cm hard Ns Op Cm 01
410 .Op Fl ro
411 .Ar path
412 .Op Ar type | cyl head sec
413 .Op Ar fdisk_tab
414 .Xc
415 Assign the file
416 .Ar path
417 to be used as either the next available hard disk or
418 to the specified hard disk.
419 A disk's geometry can either be directly specified with
420 .Ar cyl
421 being the number of cylinders,
422 .Ar head
423 the number of heads and
424 .Ar sec
425 the number of sectors per track,
426 or it can be one of the standard types specified by
427 .Ar type
428 (see below).
429 The option
430 .Ar fdisk_tab
431 argument specifies file to use as the first sector
432 of this disk.  This can be useful for inserting a
433 false fdisk table when
434 .Ar path
435 only refers to part of a disk.
436 .\"
437 .\"
438 .\"
439 .It Cm assign Xo
440 .Cm com Ns Op Cm 1-4 :
441 .Ar path
442 .Ar port
443 .Ar irq
444 .Xc
445 Assign the tty or pty specified by
446 .Ar path
447 to be used as the specified com port.
448 Its base address will be emulated at
449 .Ar port
450 at interrupt specified by
451 .Ar irq .
452 This code is lightly tested and may not suit all needs.
453 .\"
454 .\"
455 .\"
456 .It Cm portmap Xo
457 .Ar port
458 .Op Ar count
459 .Xc
460 Map the requested io
461 .Ar port
462 (with optional range up to to
463 .Ar port+count Ns No -1 )
464 to the real hardware I/O port(s).
465 This will likely require root privs to access them.
466 .\"
467 .\"
468 .\"
469 .It Cm "setver command version"
470 Cause doscmd, when emulating DOS, to report
471 .Cm version
472 as the version number of DOS when called from the program named
473 .Cm command .
474 The format of
475 .Cm version
476 is the same as of the
477 .Cm MS_VERSION
478 variable described below.
479 .El
480 .Pp
481 If not already assigned,
482 .Cm C:
483 will be assigned to the root directory (/) and the current directory
484 for
485 .Cm C:
486 will be set to the actual current directory.
487 Note that this means that invocations such as:
488 .Pp
489 .Dl "doscmd ../foo
490 .Pp
491 will not work as the
492 .Cm C:
493 directory will start with the current path.
494 Also, the following environment variables will be defined if not
495 already defined:
496 .Bd -literal
497 .Cm "COMSPEC=C:\eCOMMAND.COM
498 .Cm "PATH=C:\e
499 .Cm "PROMPT=DOS>
500 .Ed
501 .Pp
502 The
503 .Cm PATH
504 variable is also used to find
505 .Ar cmd .
506 Like DOS, first
507 .Ar cmd.com
508 will be looked for and then
509 .Ar cmd.exe .
510 .Sh "CONFIGURATION VARIABLES"
511 There are several variables in the
512 .Cm .doscmdrc
513 file which are internal to doscmd and do not actually get inserted into
514 the DOS environment.  These are:
515 .Bl -tag -width MS_VERSION
516 .It Cm MS_VERSION
517 The value of this variable is used to determine the version of DOS that
518 should be reported by
519 .Nm .
520 Note that
521 .Nm
522 will not change the way
523 it works, just the way it reports.  By default this value is
524 .Cm 410 ,
525 which corresponds to
526 .Tn "MS DOS
527 version 4.1.
528 To change it to version 3.2 (the default in previous versions of
529 .Nm )
530 use the value of
531 .Cm 320 .
532 .It Cm X11_FONT
533 The value of this variable determines the font used in an X window.
534 The default font is
535 .Cm vga ,
536 which is installed in
537 .Pa /usr/libdata/doscmd/fonts .
538 Add the line
539 .Ql xset fp+ /usr/libdata/doscmd/fonts
540 to your
541 .Pa ${HOME}/.xsession
542 or
543 .Pa ${HOME}/.xinitrc
544 to let the X server find it.
545 .El
546 .Sh FILE TRANSLATION
547 The
548 .Nm
549 utility translates
550 .Bsx
551 file names into
552 .Tn DOS
553 file names by converting to all upper case and eliminating any invalid
554 character.  It does not make any attempt to convert ASCII files into
555 the
556 .Cm <CR><LF>
557 format favored in the DOS world.  Use
558 .Xr unix2dos 1
559 (part of the pkgsrc collection) or similar tools to convert ASCII files.
560 .bp
561 .Sh DISK TYPES
562 .TS H
563 expand, box;
564 r | r | r | r | r.
565 Type    Cylinders       Heads   Sectors Size
566 =
567 01      306     4       17      10MB
568 02      615     4       17      20MB
569 03      615     6       17      30MB
570 04      940     8       17      62MB
571 05      940     6       17      46MB
572 _
573 06      615     4       17      20MB
574 07      462     8       17      30MB
575 08      733     5       17      30MB
576 09      900     15      17      112MB
577 10      820     3       17      20MB
578 _
579 11      855     5       17      35MB
580 12      855     7       17      49MB
581 13      306     8       17      20MB
582 14      733     7       17      42MB
583 15      976     15      17      121MB
584 _
585 16      612     4       17      20MB
586 17      977     5       17      40MB
587 18      977     7       17      56MB
588 19      1024    7       17      59MB
589 20      733     5       17      30MB
590 _
591 21      733     7       17      42MB
592 22      733     5       17      30MB
593 23      306     4       17      10MB
594 24      925     7       17      53MB
595 25      925     9       17      69MB
596 _
597 26      754     7       17      43MB
598 27      754     11      17      68MB
599 28      699     7       17      40MB
600 29      823     10      17      68MB
601 30      918     7       17      53MB
602 _
603 31      1024    11      17      93MB
604 32      1024    15      17      127MB
605 33      1024    5       17      42MB
606 34      612     2       17      10MB
607 35      1024    9       17      76MB
608 _
609 36      1024    8       17      68MB
610 37      615     8       17      40MB
611 38      987     3       17      24MB
612 39      987     7       17      57MB
613 40      820     6       17      40MB
614 _
615 41      977     5       17      40MB
616 42      981     5       17      40MB
617 43      830     7       17      48MB
618 44      830     10      17      68MB
619 45      917     15      17      114MB
620 _
621 46      1224    15      17      152MB
622 .TE
623 .bp
624 .Sh INSTALLING DOS ON A PSEUDO DISK
625 To install DOS on a pseudo hard disk under doscmd, do the following:
626 .Bl -tag -width XXXX
627 .It 1
628 Create a
629 .Pa .doscmdrc
630 with at least the following:
631 .Bd -literal -offset indent
632 assign A: /dev/fd0.1440 1440
633 assign A: /dev/fd0.720 720
634 assign hard boot_drive 80 2 2
635 .Ed
636 .Pp
637 You may need to adjust the raw files for the A: drive to match
638 your system.  This example will cause the HD drive to be tried
639 first and the DD drive second.
640 .Pp
641 Note that you should only use raw devices or files at this point,
642 do not use a cooked device!  (Well, it would probably be okay
643 for a hard disk, but certainly not the floppy)
644 .Pp
645 .Li boot_drive
646 should be the file name of where you want your bootable
647 image to be.  The three numbers which follow
648 .Li 80 2 2
649 say that the drive will have 80 cylinders, 2 heads and 2 sectors per track.
650 This is the smallest drive possible which still can have MS DOS
651 5.0 installed on it along with a
652 .Pa config.sys
653 and
654 .Pa autoexec.bat
655 file.
656 .Pp
657 You might want to create a larger boot drive.
658 .Pp
659 The file
660 .Pa boot_drive
661 must exist, so use the command touch to create it.
662 .It 2
663 Insert a floppy disk into the A: drive which is bootable to MS-DOS
664 and has the commands fdisk, format and sys on it.  You should also
665 copy the file redir.com onto the floppy by either mounting it
666 with the msdos file system type or by using mtools
667 (e.g.,
668 .Dq Li mwrite redir.com a: ) .
669 .It 3
670 run doscmd.
671 .It 4
672 At the > prompt type
673 .Li fdisk .
674 .It 5
675 Select
676 .Li Create DOS partition or Logical Drive .
677 .It 6
678 Select
679 .Li Create Primary DOS Partition .
680 .It 7
681 Tell it how big to make it
682 (Typically the whole drive.  It is pretty tiny after all.)
683 .It 8
684 Get out of FDISK by hitting
685 .Li <ESC>
686 a few times.
687 .It 9
688 doscmd may abort, if it does, start up doscmd again.
689 .It 10
690 At the > prompt, type
691 .Li format c:
692 and follow the instructions.
693 .It 11
694 At the > prompt type
695 .Li sys c: .
696 .It 12
697 Get out of doscmd.
698 .It 13
699 Either remove the floppy from the drive or add the line
700 .Bd -literal -offset indent
701 boot C:
702 .Ed
703 to your
704 .Pa .doscmdrc .
705 .It 14
706 You should now be running DOS off of your new disk.  You will
707 probably want both config.sys and an autoexec.bat file.  To
708 start with, you can say:
709 .Bd -literal -offset indent
710 > copy con: config.sys
711 LASTDRIVE=Z
712 ^Z
713 > copy con: autoexec.bat
714 @echo off
715 redir.com
716 ^Z
717 .Ed
718 .It 15
719 Quit doscmd.
720 .It 16
721 You know have a bootable pseudo disk which will automatically call
722 the magic
723 .Li redir
724 program, which installs
725 .Dx
726 disks.  To use
727 them add lines to your .doscmdrc such as:
728 .Bd -literal -offset indent
729 assign D: /usr/dos
730 assign P: -ro /usr/prb
731 .Ed
732 Note that you will not always be able to access every file due to
733 naming problems.
734 .El
735 .Sh DIAGNOSTICS
736 If
737 .Nm
738 encounters an interrupt which is unimplemented, it will print a message
739 such as:
740 .Pp
741 .Dl Unknown interrupt 21 function 99
742 .Pp
743 and exit.
744 .Pp
745 If
746 .Nm
747 emits the message
748 .Ic X11 support not compiled in
749 when supplied the
750 .Fl x
751 switch, this support can be added by defining an environment variable
752 .Ev X11BASE
753 which points to the installed X Window System (normally
754 .Pa /usr/X11R6 )
755 and then typing
756 .Ic make install
757 in the source directory (normally
758 .Pa /usr/src/usr.bin/doscmd ) .
759 For this to work, the X programmer's kit must have been installed.
760 .Sh HISTORY
761 The
762 .Nm
763 program first appeared in
764 .Tn BSD/386 .
765 .Sh AUTHORS
766 .An Pace Willisson ,
767 .An Paul Borman