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

NAME

6       sg_map26  -  maps a special file to a SCSI generic (sg) device (or vice
7       versa)
8

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

NOTES

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

EXAMPLES

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

EXIT STATUS

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

AUTHORS

146       Written by Douglas Gilbert.
147

REPORTING BUGS

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

SEE ALSO

158       udev(8), udevinfo(8), lsscsi(lsscsi)
159
160
161
162sg3_utils-1.23                   January 2007                      SG_MAP26(8)
Impressum