1SG_MAP26(8) SG3_UTILS SG_MAP26(8)
2
3
4
6 sg_map26 - maps a special file to a SCSI generic (sg) device (or vice
7 versa)
8
10 sg_map26 [--dev_dir=DIR] [--given_is=0|1] [--help] [--result=0|1|2|3]
11 [--symlink] [--verbose] [--version] DEVICE
12
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
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
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
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
142 The exit status of sg_map26 is 0 when it is successful. Otherwise see
143 the sg3_utils(8) man page.
144
146 Written by Douglas Gilbert.
147
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
158 udev(8), udevinfo(8), lsscsi(lsscsi)
159
160
161
162sg3_utils-1.23 January 2007 SG_MAP26(8)