kernel: Use hashdestroy() to free hash tables allocated with hashinit().

[dragonfly.git] / usr.bin / doscmd / doscmd.1

.\"
.\" Copyright (c) 1992, 1993, 1996
.\"     Berkeley Software Design, Inc.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"     This product includes software developed by Berkeley Software
.\"     Design, Inc.
.\"
.\" THIS SOFTWARE IS PROVIDED BY Berkeley Software Design, Inc. ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL Berkeley Software Design, Inc. BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     BSDI doscmd.1,v 2.3 1996/04/08 19:32:29 bostic Exp
.\" $FreeBSD: src/usr.bin/doscmd/doscmd.1,v 1.12.2.11 2002/06/20 23:45:41 charnier Exp $
.\"
.Dd January 30, 1995
.Dt DOSCMD 1
.Os
.Sh NAME
.Nm doscmd
.Nd run a subset of real-mode DOS programs
.Sh SYNOPSIS
.Nm
.Fl 23AbDEfGHIMOPRrtVvXxYz
.Fl c Ar file
.Fl d Ar file
.Fl i Ar port Ns Xo
.Op : Ns Ar cnt
.Xc
.Fl o Ar port Ns Xo
.Op : Ns Ar cnt
.Xc
.Fl S Ar int
.Fl U Ar int
.Op Ar cmd Op Ar args ...
.Sh DESCRIPTION
The
.Nm
utility can either emulate a subset of DOS and run the
single command
.Ar cmd
.Ar args ,
or it can be used to emulate a PC and boot DOS,
which allows it to run a larger variety of DOS applications.
It should be noted that MS-DOS 6.2 and higher appear
to cause difficulties for
.Nm .
To boot DOS, either provide the
.Fl b
flag or omit the
.Ar cmd
argument.
If
.Fl b
is specified,
.Ar cmd
and
.Ar args
are ignored.
.Pp
Although
.Nm
only provides a subset of DOS, it is sufficient to run a variety of
programs, including, but not limited to, compilers, assemblers and
linker-loaders.
.Pp
The various flags available to
.Nm
are:
.Bl -tag -width indent
.It Fl 2
Enable debugging traces of every trap to the
.Nm
emulator from the DOS program.
Note that some traps are handled in the kernel and hence will not
be traced.
.It Fl 3
Enable debugging of several lower level functions, such
as changing of interrupt vectors and initializing paths to logical drives.
.\"
.\"
.\"
.It Fl A
Enable tracing of all interrupts that pass into the emulator.
This is the same as using the
.Fl S
option with all 256 possible interrupt values.
.\"
.\"
.\"
.It Fl b
Attempt to boot DOS rather than emulate it.
.\"
.\"
.\"
.It Fl c Ar file
Capture all output directed at the screen into
.Ar file .
Note that direct screen writes will not be captured.
.\"
.\"
.\"
.It Fl C
List MS-DOS calls emulated and their return values.
.\"
.\"
.\"
.It Fl D
Enable debugging of the disk and file operations.
.\"
.\"
.\"
.It Fl d Ar file
Send the debug output to
.Ar file
instead of stderr.
.\"
.\"
.\"
.It Fl E
Enable debugging of the exec routines.
.\"
.\"
.\"
.It Fl G
Enable debugging of the video (graphics) routines.
.\"
.\"
.\"
.It Fl H
Enable tracing of half implemented calls.
.\"
.\"
.\"
.It Fl I
Enable tracing of all interrupts.  Almost the same as
.Fl A
except a few less traces are turned on.
.\"
.\"
.\"
.It Fl i Ar port Ns Xo
.Op : Ns Ar cnt
.Xc
Enable tracing of all inputs requested from the io
.Ar port .
If
.Ar cnt
is present, trace from
.Ar port
to
.Ar port+cnt Ns No -1 .
.\"
.\"
.\"
.It Fl M
Enable debugging of the memory operations.
.\"
.\"
.\"
.It Fl O
Direct the debugging output to stdout rather than stderr.
.\"
.\"
.\"
.It Fl o Ar port Ns Xo
.Op : Ns Ar cnt
.Xc
Enable tracing of all outputs requested from the io
.Ar port .
If
.Ar cnt
is present, trace from
.Ar port
to
.Ar port+cnt Ns No -1 .
.\"
.\"
.\"
.It Fl p Ar port Ns Xo
.Op : Ns Ar cnt
.Xc
Map the requested io
.Ar port
(with optional range up to to
.Ar port+cnt Ns No -1 )
to the real hardware I/O port(s).
This will likely require root privs to access them.
.\"
.\"
.\"
.It Fl P
Enable tracing of io port calls (such as
.Li inb ,
.Li outb ,
etc).
.\"
.\"
.\"
.It Fl R
Enable debugging of the file redirect code.
.\"
.\"
.\"
.It Fl r
Use the raw keyboard and display.  Pressing <CTRL-ALT-DEL> will
cause doscmd to exit.  This allows use of VGA graphics.
.\"
.\"
.\"
.It Fl S Ar int
Enable tracing of the interrupt
.Ar int .
.\"
.\"
.\"
.It Fl t
Attempt to do instruction level tracing.
Some instructions confuse the trace.
Pressing
.Li <CTRL-ALT-T>
attempts to toggle the trace mode on and off.
.\"
.\"
.\"
.It Fl U Ar int
Disable tracing of the interrupt
.Ar int .
Useful after
.Fl A
or
.Fl I .
.\"
.\"
.\"
.It Fl V
Include register dumps when reporting unknown interrupts.
.\"
.\"
.\"
.It Fl v
Same as
.Fl AH
.\"
.\"
.\"
.It Fl X
Enable debugging of the XMS operations.
.\"
.\"
.\"
.It Fl x
Open an X11 window to display output.  This enables a
variety interrupts not available otherwise.  This
can be used with or without
.Fl b .
.\"
.\"
.\"
.It Fl Y
Enable debugging of the EMS operations.
.\"
.\"
.\"
.It Fl z
Cause
.Nm
to pause just prior to jumping to the DOS program.
Very little use except for developing
.Nm .
.El
.Pp
When starting up,
.Nm
attempts to read a configuration file.  First the file
.Cm .doscmdrc
in the current directory.  If not found there, the
.Cm $HOME
directory is searched.  If still not found, the file
.Cm /etc/doscmdrc
is used.
.Pp
In the configuration file, a comment is started with the \fB#\fP character.
Blank lines are ignored.
Non empty lines either are environment variables
or commands which configure devices.
Any line which has an \fB=\fP before any white space is considered to be
an environment variable assignment and is added to the DOS environment.
The rest of the lines are one of the following
.Bl -tag -width XXXXX
.\"
.\"
.\"
.It Cm boot Op Cm A: | C:
Set the device to boot from.
By default
.Cm A:
is first tried, if it is defined, and if that fails,
.Cm C:
is tried.
.\"
.\"
.\"
.It Cm assign Xo
.Op Cm A-Z :
.Op Fl ro
.Ar path
.Xc
Assigns the
.Bsx
directory
.Ar path
to be assigned as the specified drive.  If the
.Fl ro
flag is specified, it is a read only file system.
These assignments will not take place when booting DOS until the
.Pa /usr/libdata/doscmd/redir.com
binary is run.
.\"
.\"
.\"
.It Cm assign Xo
.Cm lpt Ns Op Cm 0-4 :
.Op Cm direct
.Ar path
.Op Ar timeout
.Xc
Attempt to assign the specified printer to
.Ar path .
If
.Ar timeout
is specified then use it as the length of time for no
activity (in seconds) to indicate that the printer
should be flushed.  The default is 30 seconds.
The
.Cm direct
option should be set when
.Ar path
refers to a real printer.
.\"
.\"
.\"
.It Cm assign Xo
.Op Cm A: | B:
.Op Fl ro
.Ar path
.Ar density
.Xc
.It Cm assign Xo
.Cm flop Ns Op Cm 01
.Op Fl ro
.Ar path
.Ar density
.Xc
Assign the file
.Ar path
to be used as either the next available floppy or
to the specified floppy.
If
.Fl ro
is specified the floppy will be read only.
The
.Ar density
may be one of:
.Pp
.Bl -tag -compact -width 1440x
.It 180
9 head 40 track single sided floppy
.It 360
9 head 40 track double sided floppy
.It 720
9 head 80 track double sided floppy
.It 1200
15 head 80 track double sided floppy
.It 1440
18 head 80 track double sided floppy
.It 2880
36 head 80 track double sided floppy
.El
.\"
.\"
.\"
.It Cm assign Xo
.Op Cm C-Z  :
.Op Fl ro
.Ar path
.Op Ar type | cyl head sec
.Op Ar fdisk_tab
.Xc
.It Cm assign Xo
.Cm hard Ns Op Cm 01
.Op Fl ro
.Ar path
.Op Ar type | cyl head sec
.Op Ar fdisk_tab
.Xc
Assign the file
.Ar path
to be used as either the next available hard disk or
to the specified hard disk.
A disk's geometry can either be directly specified with
.Ar cyl
being the number of cylinders,
.Ar head
the number of heads and
.Ar sec
the number of sectors per track,
or it can be one of the standard types specified by
.Ar type
(see below).
The option
.Ar fdisk_tab
argument specifies file to use as the first sector
of this disk.  This can be useful for inserting a
false fdisk table when
.Ar path
only refers to part of a disk.
.\"
.\"
.\"
.It Cm assign Xo
.Cm com Ns Op Cm 1-4 :
.Ar path
.Ar port
.Ar irq
.Xc
Assign the tty or pty specified by
.Ar path
to be used as the specified com port.
Its base address will be emulated at
.Ar port
at interrupt specified by
.Ar irq .
This code is lightly tested and may not suit all needs.
.\"
.\"
.\"
.It Cm portmap Xo
.Ar port
.Op Ar count
.Xc
Map the requested io
.Ar port
(with optional range up to to
.Ar port+count Ns No -1 )
to the real hardware I/O port(s).
This will likely require root privs to access them.
.\"
.\"
.\"
.It Cm "setver command version"
Cause doscmd, when emulating DOS, to report
.Cm version
as the version number of DOS when called from the program named
.Cm command .
The format of
.Cm version
is the same as of the
.Cm MS_VERSION
variable described below.
.El
.Pp
If not already assigned,
.Cm C:
will be assigned to the root directory (/) and the current directory
for
.Cm C:
will be set to the actual current directory.
Note that this means that invocations such as:
.Pp
.Dl "doscmd ../foo"
.Pp
will not work as the
.Cm C:
directory will start with the current path.
Also, the following environment variables will be defined if not
already defined:
.Bd -literal
.Cm "COMSPEC=C:\eCOMMAND.COM"
.Cm "PATH=C:\e"
.Cm "PROMPT=DOS>"
.Ed
.Pp
The
.Cm PATH
variable is also used to find
.Ar cmd .
Like DOS, first
.Ar cmd.com
will be looked for and then
.Ar cmd.exe .
.Sh "CONFIGURATION VARIABLES"
There are several variables in the
.Cm .doscmdrc
file which are internal to doscmd and do not actually get inserted into
the DOS environment.  These are:
.Bl -tag -width MS_VERSION
.It Cm MS_VERSION
The value of this variable is used to determine the version of DOS that
should be reported by
.Nm .
Note that
.Nm
will not change the way
it works, just the way it reports.  By default this value is
.Cm 410 ,
which corresponds to
.Tn "MS-DOS"
version 4.1.
To change it to version 3.2 (the default in previous versions of
.Nm )
use the value of
.Cm 320 .
.It Cm X11_FONT
The value of this variable determines the font used in an X window.
The default font is
.Cm vga ,
which is installed in
.Pa /usr/libdata/doscmd/fonts .
Add the line
.Ql xset fp+ /usr/libdata/doscmd/fonts
to your
.Pa ${HOME}/.xsession
or
.Pa ${HOME}/.xinitrc
to let the X server find it.
.El
.Sh FILE TRANSLATION
The
.Nm
utility translates
.Bsx
file names into
.Tn DOS
file names by converting to all upper case and eliminating any invalid
character.  It does not make any attempt to convert ASCII files into
the
.Cm <CR><LF>
format favored in the DOS world.  Use
.Xr unix2dos 1
(part of the
.Xr pkgsrc 7
collection) or similar tools to convert ASCII files.
.bp
.Sh DISK TYPES
.TS H
expand, box;
r | r | r | r | r.
Type    Cylinders       Heads   Sectors Size
=
01      306     4       17      10MB
02      615     4       17      20MB
03      615     6       17      30MB
04      940     8       17      62MB
05      940     6       17      46MB
_
06      615     4       17      20MB
07      462     8       17      30MB
08      733     5       17      30MB
09      900     15      17      112MB
10      820     3       17      20MB
_
11      855     5       17      35MB
12      855     7       17      49MB
13      306     8       17      20MB
14      733     7       17      42MB
15      976     15      17      121MB
_
16      612     4       17      20MB
17      977     5       17      40MB
18      977     7       17      56MB
19      1024    7       17      59MB
20      733     5       17      30MB
_
21      733     7       17      42MB
22      733     5       17      30MB
23      306     4       17      10MB
24      925     7       17      53MB
25      925     9       17      69MB
_
26      754     7       17      43MB
27      754     11      17      68MB
28      699     7       17      40MB
29      823     10      17      68MB
30      918     7       17      53MB
_
31      1024    11      17      93MB
32      1024    15      17      127MB
33      1024    5       17      42MB
34      612     2       17      10MB
35      1024    9       17      76MB
_
36      1024    8       17      68MB
37      615     8       17      40MB
38      987     3       17      24MB
39      987     7       17      57MB
40      820     6       17      40MB
_
41      977     5       17      40MB
42      981     5       17      40MB
43      830     7       17      48MB
44      830     10      17      68MB
45      917     15      17      114MB
_
46      1224    15      17      152MB
.TE
.bp
.Sh INSTALLING DOS ON A PSEUDO DISK
To install DOS on a pseudo hard disk under doscmd, do the following:
.Bl -tag -width XXXX
.It 1
Create a
.Pa .doscmdrc
with at least the following:
.Bd -literal -offset indent
assign A: /dev/fd0.1440 1440
assign A: /dev/fd0.720 720
assign hard boot_drive 80 2 2
.Ed
.Pp
You may need to adjust the raw files for the A: drive to match
your system.  This example will cause the HD drive to be tried
first and the DD drive second.
.Pp
Note that you should only use raw devices or files at this point,
do not use a cooked device!  (Well, it would probably be okay
for a hard disk, but certainly not the floppy)
.Pp
.Li boot_drive
should be the file name of where you want your bootable
image to be.  The three numbers which follow
.Li 80 2 2
say that the drive will have 80 cylinders, 2 heads and 2 sectors per track.
This is the smallest drive possible which still can have MS-DOS
5.0 installed on it along with a
.Pa config.sys
and
.Pa autoexec.bat
file.
.Pp
You might want to create a larger boot drive.
.Pp
The file
.Pa boot_drive
must exist, so use the command touch to create it.
.It 2
Insert a floppy disk into the A: drive which is bootable to MS-DOS
and has the commands fdisk, format and sys on it.  You should also
copy the file redir.com onto the floppy by either mounting it
with the msdos file system type or by using mtools
(e.g.,
.Dq Li mwrite redir.com a: ) .
.It 3
run doscmd.
.It 4
At the > prompt type
.Li fdisk .
.It 5
Select
.Li Create DOS partition or Logical Drive .
.It 6
Select
.Li Create Primary DOS Partition .
.It 7
Tell it how big to make it
(Typically the whole drive.  It is pretty tiny after all.)
.It 8
Get out of FDISK by hitting
.Li <ESC>
a few times.
.It 9
doscmd may abort, if it does, start up doscmd again.
.It 10
At the > prompt, type
.Li format c:
and follow the instructions.
.It 11
At the > prompt type
.Li sys c: .
.It 12
Get out of doscmd.
.It 13
Either remove the floppy from the drive or add the line
.Bd -literal -offset indent
boot C:
.Ed
to your
.Pa .doscmdrc .
.It 14
You should now be running DOS off of your new disk.  You will
probably want both config.sys and an autoexec.bat file.  To
start with, you can say:
.Bd -literal -offset indent
> copy con: config.sys
LASTDRIVE=Z
^Z
> copy con: autoexec.bat
@echo off
redir.com
^Z
.Ed
.It 15
Quit doscmd.
.It 16
You know have a bootable pseudo disk which will automatically call
the magic
.Li redir
program, which installs
.Dx
disks.  To use
them add lines to your .doscmdrc such as:
.Bd -literal -offset indent
assign D: /usr/dos
assign P: -ro /usr/prb
.Ed
Note that you will not always be able to access every file due to
naming problems.
.El
.Sh DIAGNOSTICS
If
.Nm
encounters an interrupt which is unimplemented, it will print a message
such as:
.Pp
.Dl Unknown interrupt 21 function 99
.Pp
and exit.
.Pp
If
.Nm
emits the message
.Ic X11 support not compiled in
when supplied the
.Fl x
switch, this support can be added by defining an environment variable
.Ev X11BASE
which points to the installed X Window System (normally
.Pa /usr/X11R6 )
and then typing
.Ic make install
in the source directory (normally
.Pa /usr/src/usr.bin/doscmd ) .
For this to work, the X programmer's kit must have been installed.
.Sh HISTORY
The
.Nm
program first appeared in
.Tn BSD/386 .
.Sh AUTHORS
.An Pace Willisson ,
.An Paul Borman