Ubuntu Manpage: sg_map26 - map SCSI generic (sg) device to corresponding device names

Provided by: sg3-utils_1.36-1ubuntu1_amd64

NAME

       sg_map26 - map SCSI generic (sg) device to corresponding device names

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 (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.

       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-2012 Douglas Gilbert
       This software is distributed under a FreeBSD license. There is NO warranty; not  even  for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.