try separating some linux and win32 code and doco

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@214 6180dd3e-e324-4e3e-922d-17de1ae2f315

1 files changed, 119 insertions, 0 deletions

diff --git a/doc/sg_scan.8.win32 b/doc/sg_scan.8.win32
new file mode 100644
index 00000000..1ce68e35
--- /dev/null
+++ b/doc/sg_scan.8.win32
@@ -0,0 +1,119 @@
+.TH SG_SCAN "8" "December 2006" "sg3_utils\-1.23" SG3_UTILS
+.SH NAME
+sg_scan \- scan scsi devices, volume names, physical drives,
+cdrom/dvd drives and tapes and show relationships
+.SH SYNOPSIS
+.B sg_scan
+[\fI\-\-help\fR] [\fI\-\-letter=VL\fR] [\fI\-\-verbose\fR]
+[\fI\-\-version\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+The purpose of this utility is to show which device names the other
+utilities in this package will accept. It scans SCSI and various related
+device types often finding multiple device names. It then attempts to place
+all the device names for a device on a single line.
+.PP
+Storage and related devices can have several device names in Windows.
+Probably the most common in the volume name (e.g. "D:"). There is also
+a "class" device name, and this utility scans for three of
+them: "PhysicalDrive<n>", "CDROM<n>" and "TAPE<n>". <n> is an integer
+starting at 0 allocated in ascending order as devices are discovered (and
+sometimes rediscovered).
+.PP
+Then there is a lower level device name which starts with a SCSI (pseudo)
+adapter name of the form "SCSI<n>:". To this is added sub\-addressing
+in the form of a "bus" number, a "target" identifier and a lun (logical
+unit number). The "bus" number is also known as a "PathId". These
+components are combined by the utility to make a device name of the
+form: "SCSI<n>:<bus>,<target>,<lun>". This utility allows the
+trailing ",<lun>" to be omitted in which case a lun of zero is assumed.
+This lower level device name cannot often be used directly since
+Windows blocks attempts to use it if a class driver has "claimed" the
+device. There are SCSI device types (e.g. processor type) for which
+there is no class driver. At least two transports: USB and IEEE 1394
+do not have a "scsi" device names of this form.
+.PP
+In keeping with DOS file system conventions, the various device names
+can be given in upper, lower or mixed case. Since "PhysicalDrive<n>" is
+tedious to write, a shortened form of "PD<n>" is permitted by this
+utility.
+.PP
+A single device (e.g. a disk) can have many device names! For
+example: "PDO" can also be "C:", "D:" and "SCSI0:0,1,0". The
+two volume names reflect that the disk has two "Windows" partitions
+on it.
+.PP
+So this utility tries to scan the SCSI and related devices, generating one
+line (sometimes more) of output for each device found. First appears
+the "scsi" device name or blanks if there is none. Next follows the volume
+letter (if any) optionally followed by a "+" to indicate more volume letters
+map to this device. Next is one of the class device names or blanks followed
+by a concatenation of the INQUIRY response strings. Windows often
+manufactures INQUIRY response strings for non\-SCSI devices (e.g. a parallel
+ATA disk at "C:") and doesn't quite obey the SCSI\-2 rules for an INQUIRY
+response. If this utility sees that it places a "*" after the INQUIRY
+response strings.
+.PP
+In some cases this utility is unable to distinguish that various
+device names represent the same device (e.g. USB and IEEE 1394
+devices). Rather than guess, they appear as two lines (not always adjacent).
+An educated guess could be made but could be tricked, for example,
+by two USB sticks with the same model and manufacturer.
+.PP
+For more information see the NOTES section below.
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+outputs the usage message summarizing command line options
+then exits.
+.TP
+\fB\-l\fR, \fB\-\-letter\fR=\fIVL\fR
+normally when a device a multiple volume names (e.g. a disk with two
+partitions recognized by Windows) then the lowest letter volume name in
+alphabetical order is output, followed by a "+". Hence subsequent matching
+volume letters are not shown. If the user is interested in a particular
+volume name then its letter can be given as the \fIVL\fR argument and if
+found it will be output rather than the lowest volume name.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increases the level or verbosity.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print out version string
+.SH NOTES
+This utility uses the SCSI Pass Through (direct) [SPT] interface rather
+than Adaptec's ASPI32. ASPI32 requires a dll not distributed with
+Windows. Using the SPT interface requires that a user has administrative
+rights. This utility does not support Windows 95, 98 and ME (and
+earlier Windows operating systems). The target Windows operating systems
+are currently Windows 2000, 2003 and XP (and their variants).
+.PP
+If no class device name is found then "pdt=<num>" is placed at the end
+of the line. This is the SCSI "peripheral device type" (see SPC\-4 at
+http://www.t10.org). Some values are: 0 \-> disks, 1 \-> tapes, 3 \->
+processor, 5 \-> cd/dvds, 8 \-> medium changers, 13 \-> SES devices.
+.PP
+The DOS device names given the the CreateFile() call all start with a "\\.\"
+string. That can be given but if not will be supplied automatically. For
+the SCSI lower level interface the adapter name (e.g. "SCSI2:") is given
+to the CreateFile() call and the sub\-addressing (i.e. bus, target and lun)
+is given to each SCSI pass through command.
+.PP
+Scanning devices that are hot unplugged and replugged often can be
+problematic, especially with the class device names. Each time a device is
+removed and re\-added it gets a larger class device name (e.g. "PD3"
+becomes "PD4" leaving "PD3" unused). This utility stops scanning class
+devices after it find 8 consecutive "holes". If this turns out to be a
+problem then adjustments will be made.
+.SH EXIT STATUS
+The exit status of sg_scan is 0 when it is successful. Otherwise see
+the sg3_utils(8) man page.
+.SH AUTHORS
+Written by D. Gilbert
+.SH COPYRIGHT
+Copyright \(co 2006 Douglas Gilbert
+.br
+This software is distributed under a FreeBSD license. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.