1SG_MAP26(8)                        SG3_UTILS                       SG_MAP26(8)
2
3
4

NAME

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

SYNOPSIS

9       sg_map26  [--dev_dir=DIR]  [--given_is=0|1] [--help] [--result=0|1|2|3]
10       [--symlink] [--verbose] [--version] DEVICE
11

DESCRIPTION

13       Maps a special file (block or char) associated with a  SCSI  device  to
14       the corresponding SCSI generic (sg) device, or vice versa.  Can also be
15       given   a    sysfs    file,    for    example    '/sys/block/sda'    or
16       '/sys/block/sda/dev'.
17
18       Rather  than map to or from a sg device, the sysfs file name matching a
19       given device special file (or vice versa) can  be  requested.  This  is
20       done  with  '--result=2'  and  '--result=3'.  This feature works on ATA
21       devices (e.g. 'dev/hdc') as well as SCSI devices.
22
23       In this utility, "mapped" refers to finding the relationship between  a
24       SCSI  generic  (sg) node and the higher level SCSI device name; or vice
25       versa. For example '/dev/sg0' may "map" to  '/dev/sda'.   Mappings  may
26       not  exist, if a relevant module is not loaded, for example. Also there
27       are SCSI devices that can only be accessed via a sg node  (e.g.  SAF-TE
28       and some SES devices).
29
30       In  this utility, "matching" refers to different representations of the
31       same device accessed via the same driver. For example,  '/dev/hdc'  and
32       '/sys/block/hdc'  usually  refer  to  the same device and thus would be
33       considered  matching.  A  related  example  is  that  '/dev/cdrom'  and
34       '/dev/hdc' are also considered matching if '/dev/cdrom' is a symlink to
35       '/dev/hdc'.
36

OPTIONS

38       Arguments to long options are mandatory for short options as well.
39
40       -d, --dev_dir=DIR
41              where DIR is the directory to search for resultant  device  spe‐
42              cial   files   in  (or  symlinks  to  same).  Only  active  when
43              '--result=0' (the default) or '--result=2'. If  this  option  is
44              not given and DEVICE is a device special file then the directory
45              part of DEVICE is assumed.  If this  option  is  not  given  and
46              DEVICE  is  a sysfs name, then if necessary '/dev' is assumed as
47              the directory.
48
49       -g, --given_is=0 | 1
50              specifies the DEVICE is either a device special file  (when  the
51              argument  is 0), or a sysfs 'dev' file (when the argument is 1).
52              The parent directory of a sysfs  'dev'  file  is  also  accepted
53              (e.g.    either  '/sys/block/sda/dev'  or  '/sys/block/sda'  are
54              accepted). Usually there is no need to give  this  option  since
55              this utility first checks for special files (or symlinks to spe‐
56              cial files) and if not, assumes it has been given a sysfs  'dev'
57              file  (or its parent). Generates an error if given and disagrees
58              with variety of DEVICE.
59
60       -h, --help
61              output the usage message then exit.
62
63       -r, --result=0 | 1 | 2 | 3
64              specifies what variety of file  (or  files)  that  this  utility
65              tries  to  find.  The default is a "mapped" device special file,
66              when the argument is 0.  When the argument is  1,  this  utility
67              tries to find the "mapped" sysfs node name. When the argument is
68              2, this utility tries to  find  the  "matching"  device  special
69              file.  When  the  argument  is 3, this utility tries to find the
70              "matching" sysfs node name.
71
72       -s, --symlink
73              when  a  device  special  file  is  being  sought   (i.e.   when
74              '--result=0'  (the  default) or '--result=2') then also look for
75              symlinks to that device special file in the same directory.
76
77       -v, --verbose
78              increase the level of verbosity, (i.e. debug output).
79
80       -V, --version
81              print the version string and then exit.
82

NOTES

84       This utility is designed for the Linux 2.6 (and later)  kernel  series.
85       It  uses  special file major and minor numbers (and whether the special
86       is block or character) together with sysfs to do its mapping or  match‐
87       ing.  In the absence of any other information, device special files are
88       assumed to be in the '/dev' directory while  sysfs  is  assumed  to  be
89       mounted  at  '/sys'.  Device  names in sysfs are predictable, given the
90       corresponding major and minor number of the  device.  However,  due  to
91       udev  rules,  the name of device special files can be anything the user
92       desires (e.g. '/dev/sda' could be named '/dev/my_boot_disk'). When try‐
93       ing  to  find  a  resultant  device special file, this utility uses the
94       major and minor numbers (and whether a block or char device is  sought)
95       to search the device directory.
96
97       This  utility only shows one relationship at a time. To get an overview
98       of all SCSI  devices,  with  special  file  names  and  optionally  the
99       "mapped" sg device name, see the lsscsi utility.
100

EXAMPLES

102       Assume sg2 maps to sdb while dvd, cdrom and hdc are all matching.
103
104         # sg_map26 /dev/sg2
105         /dev/sdb
106
107         # sg_map26 /dev/sdb
108         /dev/sg2
109
110         # sg_map26 --result=0 /dev/sdb
111         /dev/sg2
112
113         # sg_map26 --result=3 /dev/sdb
114         /sys/block/sda
115
116         # sg_map26 --result=1 /dev/sdb
117         /sys/class/scsi_generic/sg0
118
119       Now look at '/dev/hdc' and friends
120
121         # sg_map26 /dev/hdc
122         <error: a hd device does not map to a sg device>
123
124         # sg_map26 --result=3 /dev/hdc
125         /sys/block/hdc
126
127         # sg_map26 --result=2 /dev/hdc
128         /dev/hdc
129
130         # sg_map26 --result=2 --symlink /dev/hdc
131         /dev/cdrom
132         /dev/dvd
133         /dev/hdc
134
135         # sg_map26 --result=2 --symlink /sys/block/hdc
136         /dev/cdrom
137         /dev/dvd
138         /dev/hdc
139

EXIT STATUS

141       The  exit  status of sg_map26 is 0 when it is successful. Otherwise see
142       the sg3_utils(8) man page.
143

AUTHORS

145       Written by Douglas Gilbert.
146

REPORTING BUGS

148       Report bugs to <dgilbert at interlog dot com>.
149
151       Copyright © 2005-2012 Douglas Gilbert
152       This software is distributed under a FreeBSD license. There is NO  war‐
153       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
154       POSE.
155

SEE ALSO

157       udev(7), lsscsi(lsscsi)
158
159
160
161sg3_utils-1.35                   November 2012                     SG_MAP26(8)
Impressum