1 files changed, 161 insertions, 0 deletions
diff --git a/doc/sg_map26.8 b/doc/sg_map26.8
new file mode 100644
index 00000000..7ad013bf
--- /dev/null
+++ b/doc/sg_map26.8
@@ -0,0 +1,161 @@
+.TH SG_MAP26 "8" "November 2012" "sg3_utils\-1.35" SG3_UTILS
+.SH NAME
+sg_map26 \- map SCSI generic (sg) device to corresponding device names
+.SH SYNOPSIS
+.B sg_map26
+[\fI\-\-dev_dir=DIR\fR] [\fI\-\-given_is=\fR0|1] [\fI\-\-help\fR]
+[\fI\-\-result=\fR0|1|2|3] [\fI\-\-symlink\fR] [\fI\-\-verbose\fR]
+[\fI\-\-version\fR] \fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Maps a special file (block or char) associated with a SCSI device
+to the corresponding SCSI generic (sg) device, or vice versa.
+Can also be given a sysfs file, for example '/sys/block/sda'
+or '/sys/block/sda/dev'.
+.PP
+Rather than map to or from a sg device, the sysfs file name
+matching a given device special file (or vice versa) can be
+requested. This is done with '\-\-result=2' and '\-\-result=3'.
+This feature works on ATA devices (e.g. 'dev/hdc') as well
+as SCSI devices.
+.PP
+In this utility, "mapped" refers to finding the relationship between
+a SCSI generic (sg) node and the higher level SCSI device name; or
+vice versa. For example '/dev/sg0' may "map" to '/dev/sda'.
+Mappings may not exist, if a relevant module is not loaded, for
+example. Also there are SCSI devices that can only be accessed via a sg
+node (e.g. SAF\-TE and some SES devices).
+.PP
+In this utility, "matching" refers to different representations of
+the same device accessed via the same driver. For example, '/dev/hdc'
+and '/sys/block/hdc' usually refer to the same device and thus would
+be considered matching. A related example is that '/dev/cdrom'
+and '/dev/hdc' are also considered matching if '/dev/cdrom' is a
+symlink to '/dev/hdc'.
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-d\fR, \fB\-\-dev_dir\fR=\fIDIR\fR
+where \fIDIR\fR is the directory to search for resultant device special
+files in (or symlinks to same). Only active when '\-\-result=0' (the
+default) or '\-\-result=2'. If this option is not given and \fIDEVICE\fR is
+a device special file then the directory part of \fIDEVICE\fR is assumed.
+If this option is not given and \fIDEVICE\fR is a sysfs name, then if
+necessary '/dev' is assumed as the directory.
+.TP
+\fB\-g\fR, \fB\-\-given_is\fR=0 | 1
+specifies the \fIDEVICE\fR is either a device special file (when the
+argument is 0), or a sysfs 'dev' file (when the argument is 1). The parent
+directory of a sysfs 'dev' file is also accepted (e.g.
+either '/sys/block/sda/dev' or '/sys/block/sda' are accepted). Usually
+there is no need to give this option since this utility first checks for
+special files (or symlinks to special files) and if not, assumes it
+has been given a sysfs 'dev' file (or its parent). Generates an error
+if given and disagrees with variety of \fIDEVICE\fR.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+output the usage message then exit.
+.TP
+\fB\-r\fR, \fB\-\-result\fR=0 | 1 | 2 | 3
+specifies what variety of file (or files) that this utility tries to find.
+The default is a "mapped" device special file, when the argument is 0.
+When the argument is 1, this utility tries to find the "mapped" sysfs node
+name. When the argument is 2, this utility tries to find the "matching"
+device special file. When the argument is 3, this utility tries to find
+the "matching" sysfs node name.
+.TP
+\fB\-s\fR, \fB\-\-symlink\fR
+when a device special file is being sought (i.e. when '\-\-result=0' (the
+default) or '\-\-result=2') then also look for symlinks to that device
+special file in the same directory.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase the level of verbosity, (i.e. debug output).
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print the version string and then exit.
+.SH NOTES
+This utility is designed for the Linux 2.6 (and later) kernel series.
+It uses special file major and minor numbers (and whether the special
+is block or character) together with sysfs to do its mapping or
+matching. In the absence of any other information, device special
+files are assumed to be in the '/dev' directory while sysfs is
+assumed to be mounted at '/sys'. Device names in sysfs are
+predictable, given the corresponding major and minor number of
+the device. However, due to udev rules, the name of device
+special files can be anything the user desires (e.g. '/dev/sda'
+could be named '/dev/my_boot_disk'). When trying to
+find a resultant device special file, this utility uses the major
+and minor numbers (and whether a block or char device is sought)
+to search the device directory.
+.PP
+This utility only shows one relationship at a time. To get an
+overview of all SCSI devices, with special file names and optionally
+the "mapped" sg device name, see the lsscsi utility.
+.SH EXAMPLES
+Assume sg2 maps to sdb while dvd, cdrom and hdc are all matching.
+.PP
+  # sg_map26 /dev/sg2
+.br
+  /dev/sdb
+.PP
+  # sg_map26 /dev/sdb
+.br
+  /dev/sg2
+.PP
+  # sg_map26 \-\-result=0 /dev/sdb
+.br
+  /dev/sg2
+.PP
+  # sg_map26 \-\-result=3 /dev/sdb
+.br
+  /sys/block/sda
+.PP
+  # sg_map26 \-\-result=1 /dev/sdb
+.br
+  /sys/class/scsi_generic/sg0
+.PP
+Now look at '/dev/hdc' and friends
+.PP
+  # sg_map26 /dev/hdc
+.br
+  <error: a hd device does not map to a sg device>
+.PP
+  # sg_map26 \-\-result=3 /dev/hdc
+.br
+  /sys/block/hdc
+.PP
+  # sg_map26 \-\-result=2 /dev/hdc
+.br
+  /dev/hdc
+.PP
+  # sg_map26 \-\-result=2 \-\-symlink /dev/hdc
+.br
+  /dev/cdrom
+.br
+  /dev/dvd
+.br
+  /dev/hdc
+.PP
+  # sg_map26 \-\-result=2 \-\-symlink /sys/block/hdc
+.br
+  /dev/cdrom
+.br
+  /dev/dvd
+.br
+  /dev/hdc
+.SH EXIT STATUS
+The exit status of sg_map26 is 0 when it is successful. Otherwise see
+the sg3_utils(8) man page.
+.SH AUTHORS
+Written by Douglas Gilbert.
+.SH "REPORTING BUGS"
+Report bugs to <dgilbert at interlog dot com>.
+.SH COPYRIGHT
+Copyright \(co 2005\-2012 Douglas Gilbert
+.br
+This software is distributed under a BSD\-2\-Clause license. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+.B udev(7), lsscsi(lsscsi)