1 files changed, 182 insertions, 0 deletions
diff --git a/doc/sg_map.8 b/doc/sg_map.8
new file mode 100644
index 00000000..abe0935d
--- /dev/null
+++ b/doc/sg_map.8
@@ -0,0 +1,182 @@
+.TH SG_MAP "8" "May 2013" "sg3_utils\-1.36" SG3_UTILS
+.SH NAME
+sg_map \- displays mapping between Linux sg and other SCSI devices
+.SH SYNOPSIS
+.B sg_map
+[\fI\-a\fR] [\fI-h\fR] [\fI\-i\fR] [\fI\-n\fR] [\fI\-scd\fR] [\fI\-sd\fR]
+[\fI\-sr\fR] [\fI\-st\fR] [\fI\-V\fR] [\fI\-x\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Sometimes it is difficult to determine which SCSI device a sg device
+name (e.g. /dev/sg0) refers to. This command loops through the
+sg devices and finds the corresponding SCSI disk, cdrom or tape
+device name (if any). Scanners are an example of SCSI devices
+that have no alternate SCSI device name apart from their sg device
+name.
+.PP
+This utility is deprecated and has not been updated for years, only very
+obvious bugs will be fixed. Unless a very old version of Linux is being
+used (e.g.  2.4 series or earlier), then please use a utility like lsscsi(8)
+or the facilities offered by udev(8).
+.SH OPTIONS
+.TP
+\fB\-a\fR
+assume the sg devices have alphabetical device names and loop
+through /dev/sga, /dev/sgb, etc. Default is numeric scan.
+Note that sg device nodes with an alphabetical index have been
+deprecated since the Linux kernel 2.2 series.
+.TP
+\fB\-h\fR
+print usage message then exit.
+.TP
+\fB\-i\fR
+in addition do a standard INQUIRY and output vendor, product and revision
+strings for devices that are found.
+.TP
+\fB\-n\fR
+assume the sg devices have numeric device names and loop
+through /dev/sg0, /dev/sg1, etc. Default is numeric scan
+.TP
+\fB\-scd\fR
+display mappings to SCSI cdrom device names of the form
+/dev/scd0, /dev/scd1 etc
+.TP
+\fB\-sd\fR
+display mappings to SCSI disk device names
+.TP
+\fB\-sr\fR
+display mappings to SCSI cdrom device names of the form
+/dev/sr0, /dev/sr1 etc
+.TP
+\fB\-st\fR
+display mappings to SCSI tape device names
+.TP
+\fB\-V\fR
+print out version string then exit (without further ado).
+.TP
+\fB\-x\fR
+after each active sg device name is displayed there are
+five digits: <host_number> <bus> <scsi_id> <lun> <scsi_type>
+.SH NOTES
+If no options starting with "\-s" are given then the mapping to
+all SCSI disk, cdrom and tape device names is shown.
+.PP
+If the device file system (devfs) is present a line noting
+this is output. The "native" devfs scsi hierarchy makes the
+relationship between a sg device name and any corresponding
+disk, cdrom or tape device name easy to establish. This
+replaces the need for this command. However many applications
+will continue to look for Linux SCSI device names in their
+traditional places. [Devfs supplies a compatibility daemon
+called devfsd whose default configuration adds back the
+Linux device names in their traditional positions.
+.PP
+Quite often the mapping information can be derived by
+observing the output of the command: "sg_map".
+However if devices have been added since boot this can
+be deceptive.
+.PP
+In the Linux kernel 2.6 series something close to the mapping
+shown by this utility can be found by analysing sysfs. The
+main difference is that sysfs analysis will show the mapping
+between sg nodes and other SCSI device nodes in terms of
+major and minor numbers. While major 8, minor 16 will usually
+be /dev/sdb this is not necessarily so. Facilities associated
+with udev may assign major 8, minor 16 some other device node
+name. This version of sg_map has been extended to cope with
+sparse disk device node names of the form "/dev/sd<str>"
+where <str> can be one of [a\-z,aa\-zz,aaa\-zzz]. See the sg_map26
+utility for a more precise way (i.e. less directory scanning)
+for mapping between sg device names and higher level names;
+including finding user defined names.
+.PP
+This utility was written at a time when hotplugging of SCSI devices
+was not supported in Linux. It used a simple algorithm to scan sg
+device nodes in ascending numeric or alphabetical order, stopping
+after there were 5 consecutive errors.
+.PP
+In the Linux kernel 2.6 series, this utility uses sysfs to find which
+sg device nodes are active and only checks those. Hence there can be
+large "holes" in the numbering of sg device nodes (e.g. after an
+adapter has been removed) and still all active sg device nodes will
+be listed. This utility assumes that sg device nodes are named using
+the normal conventions and searches from /dev/sg0 to /dev/sg4095
+inclusive.
+.SH EXAMPLES
+.PP
+My system has a SCSI disk, a cd writer and a dvd player:
+.br
+   $ sg_map
+.br
+   # Note: the devfs pseudo file system is present
+.br
+   /dev/sg0  /dev/sda
+.br
+   /dev/sg1  /dev/sr0
+.br
+   /dev/sg2  /dev/sr1
+.PP
+In order to find which sg device name corresponds to the disk:
+.br
+   $ sg_map \-sd
+.br
+   # Note: the devfs pseudo file system is present
+.br
+   /dev/sg0  /dev/sda
+.br
+   /dev/sg1
+.br
+   /dev/sg2
+.PP
+The "\-x" option gives the following output:
+.br
+   sg_map \-x
+.br
+   # Note: the devfs pseudo file system is present
+.br
+   /dev/sg0  1 0 1 0  0  /dev/sda
+.br
+   /dev/sg1  2 0 4 0  5  /dev/sr0
+.br
+   /dev/sg2  2 0 6 0  5  /dev/sr1
+.PP
+When a SCSI scanner is added the output becomes:
+.br
+   $ sg_map
+.br
+   # Note: the devfs pseudo file system is present
+.br
+   /dev/sg0  /dev/sda
+.br
+   /dev/sg1  /dev/sr0
+.br
+   /dev/sg2  /dev/sr1
+.br
+   /dev/sg3
+.PP
+By process of elimination /dev/sg3 must be the scanner.
+.SH EXIT STATUS
+The exit status of sg_map is 0 when it is successful. Otherwise see
+the sg3_utils(8) man page.
+.SH AUTHOR
+Written by Douglas Gilbert
+.SH "REPORTING BUGS"
+Report bugs to <dgilbert at interlog dot com>.
+.SH COPYRIGHT
+Copyright \(co 2000\-2013 Douglas Gilbert
+.br
+This software is distributed under the GPL version 2. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+.B sg_map26(8)
+,
+.B scsi_info(8)
+,
+.B scsidev(8)
+,
+.B devfsd(8)
+,
+.B lsscsi(8)
+,
+.B udev(7)