NAME
sg_map26 - maps a special file to a SCSI generic (sg) device (or vice
versa)
SYNOPSIS
sg_map26 [--dev_dir=DIR] [--given_is=0|1] [--help] [--result=0|1|2|3]
[--symlink] [--verbose] [--version] DEVICE
DESCRIPTION
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’.
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.
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).
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’.
OPTIONS
Arguments to long options are mandatory for short options as well.
-d, --dev_dir=DIR
where DIR 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 DEVICE is a device special file then the directory
part of DEVICE is assumed. If this option is not given and
DEVICE is a sysfs name, then if necessary ’/dev’ is assumed as
the directory.
-g, --given_is=0 | 1
specifies the DEVICE 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 DEVICE.
-h, --help
output the usage message then exit.
-r, --result=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.
-s, --symlink
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.
-v, --verbose
increase the level of verbosity, (i.e. debug output).
-V, --version
print the version string and then exit.
NOTES
This utility is designed for the linux 2.6 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.
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.
EXAMPLES
Assume sg2 maps to sdb while dvd, cdrom and hdc are all matching.
# sg_map26 /dev/sg2
/dev/sdb
# sg_map26 /dev/sdb
/dev/sg2
# sg_map26 --result=0 /dev/sdb
/dev/sg2
# sg_map26 --result=3 /dev/sdb
/sys/block/sda
# sg_map26 --result=1 /dev/sdb
/sys/class/scsi_generic/sg0
Now look at ’/dev/hdc’ and friends
# sg_map26 /dev/hdc
<error: a hd device does not map to a sg device>
# sg_map26 --result=3 /dev/hdc
/sys/block/hdc
# sg_map26 --result=2 /dev/hdc
/dev/hdc
# sg_map26 --result=2 --symlink /dev/hdc
/dev/cdrom
/dev/dvd
/dev/hdc
# sg_map26 --result=2 --symlink /sys/block/hdc
/dev/cdrom
/dev/dvd
/dev/hdc
EXIT STATUS
The exit status of sg_map26 is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright © 2005-2007 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
SEE ALSO
udev(8), udevinfo(8), lsscsi(lsscsi)