man > sg_map26(8)

SG_MAP26(8)                                   SG3_UTILS                                  SG_MAP26(8)

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  de‐
       vices).

       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  sym‐
              links  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 DE‐
              VICE is assumed.  If this option is not given and DEVICE is a sysfs name, then if nec‐
              essary '/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  spe‐
              cial  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 vari‐
              ety 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  de‐
              fault 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 di‐
              rectory.

       -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'. De‐
       vice  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 MER‐
       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO
       udev(7), lsscsi(lsscsi)

sg3_utils-1.35                              November 2012                                SG_MAP26(8)