diff options
Diffstat (limited to 'doc/sg_map26.8')
-rw-r--r-- | doc/sg_map26.8 | 161 |
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) |