SG_MAP26(8)

📦
version 1.49 · 4 versions
, in arch rolling, nixpkgs unstable

💫 sg_map26 — like, the manual, but make it make sense ✨

okay so bestie, this is sg_map26 from the sg3_utils man pages, section 8 (that's the sysadmin-y section, iykyk). she's a little utility that figures out who's who in your SCSI zoo 🦋

🌸 NAME 🌸

sg_map26 — maps a SCSI generic (sg) device to the corresponding device names 💅

🎀 SYNOPSIS 🎀

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

✨ DESCRIPTION ✨

So basically: you hand her a special file (block or char) that belongs to a SCSI device, and she maps it to the matching SCSI generic (sg) device — or does the whole thing in reverse, iconically. You can also just give her a sysfs file, like /sys/block/sda or /sys/block/sda/dev. 🫶

Instead of mapping to/from an sg device, you can ask her for the sysfs file name that matches a given device special file (or the other way around). That's what --result=2 and --result=3 are for. And bestie, this feature works on ATA devices too (think dev/hdc), not just SCSI ones. slay. 🔥

Some vocabulary, because words matter:

  • "mapped" — in this utility it means 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 simply not exist — like if the relevant module isn't loaded, for example. Also, some SCSI devices can only be reached via a sg node (hi SAF-TE and some SES devices 👋).
  • "matching" — this one is about different representations of the same device accessed through the same driver. For example, /dev/hdc and /sys/block/hdc usually refer to the same device, so they'd be considered matching. Related vibe: /dev/cdrom and /dev/hdc are also considered matching if /dev/cdrom is a symlink to /dev/hdc. 💖
⚠️ heads up bestie: this utility needs root permissions to access the storage device nodes in the /dev directory. The lsscsi utility may be used instead in many cases, and lsscsi does not require root permission because it "data-mines" the sysfs pseudo file system for the info it needs. no cap.

For notes on bsg and nvme device nodes, see the section on BSG and NVME DEVICES below. 👇

💅 OPTIONS 💅

Arguments to long options are mandatory for short options as well. (yes, even the short ones. she's thorough.)

  • -d, --dev_dir=DIR — 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 isn't given and DEVICE is a device special file, then the directory part of DEVICE is assumed. If this option isn't given and DEVICE is a sysfs name, then /dev is assumed as the directory if necessary. 🗂️
  • -g, --given_is=0 | 1 — tells her whether DEVICE is a device special file (argument 0) or a sysfs dev file (argument 1). The parent directory of a sysfs dev file is also accepted — so either /sys/block/sda/dev or /sys/block/sda are accepted, bestie. Usually there's no need to give this option, since this utility first checks for special files (or symlinks to special files), and if it's not that, assumes it's been given a sysfs dev file (or its parent). Generates an error if given and it disagrees with the variety of DEVICE. 😭
  • -h, --help — output the usage message then exit. short & sweet 💫
  • -r, --result=0 | 1 | 2 | 3 — specifies what variety of file (or files) this utility tries to find:
    • argument 0 (the default) → a "mapped" device special file
    • argument 1 → the "mapped" sysfs node name
    • argument 2 → the "matching" device special file
    • argument 3 → 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). she'll tell you everything 🗣️
  • -V, --version — print the version string and then exit. 👑

🦋 BSG and NVME DEVICES 🦋

The bsg driver (Block Scsi Generic) presents alternate Unix character devices of the form: /dev/bsg/<h:c:t:l>. That <h:c:t:l> is a 4 element tuple where h is the host number, c is the controller number, t is the target identifier, and l is the LUN (Logical Unit Number). Other than the bsg device names, each device, once open()-ed, operates in a similar fashion to a sg device: a generic interface at the SCSI command level. 🧚

If a bsg device is given to this utility, she'll first try to map it to a SCSI block device. That'll either be of the form /dev/sd<letter_s> for a disk, or /dev/sr<number> for a BD/DVD or CD drive. If no match is found, then a check is made for a SCSI tape drive with a name of the form /dev/st<number>. If that fails too, the mapping to the corresponding sg device is made. If the --result=2 option is given, the block device and tape davice checks are bypassed and the mapping to the corresponding sg device is made. 💀

ngl, note that this utility makes no mapping to a bsg device. That's pretty easy to establish using the lsscsi utility, since the 4 element <h:c:t:l> tuple is shown at the beginning of each line (by default) and it uniquely identifies each SCSI device. Each line will also show the primary device name and, if the --generic option is given, the sg device node. 🌈

Currently NVMe device nodes come in several varieties — block devices of the form: /dev/nvme<c>n<n>[p<pn>] where <c> is the controller number (starting at 0), <n> is the namespace identifier (starting at 1), and <pn> is the partition number (starting at 1). There are two forms of NVMe character device nodes: one of the form /dev/nvme<c> and the other of the form /dev/ng<c>n<n> where "ng" is newer and termed as nvme-generic in the /proc/devices output. This utility identifies but does not map NVMe devices. Their naming is more consistent so a utility like this is less needed. Udev might be used to remap the kernel's naming scheme for NVMe, removing its inherent naming consistency. 🙈

⭐ NOTES ⭐

This utility is designed for the Linux 2.6 (and later) kernel series. She uses special file major and minor numbers (and whether the special is block or character) together with sysfs to do her 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 — and this is the messy part — 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). So 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. 💖

She 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. 👀

Even though lsscsi is a functional replacement for this utility, it has been reported that this utility runs faster in systems that have a lot of disks connected. Theoretically a Linux system may have up to 16383 SCSI disks connected to it. not me being dramatic about it, that's just the number. 🍓

🔥 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. (ty king 💜)

💌 REPORTING BUGS 💌

Report bugs to <dgilbert at interlog dot com>.

Copyright © 2005-2023 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. like, none. zero. nada. 😭

🎀 SEE ALSO 🎀

and that's the whole page bestie — sg3_utils version sg3_utils-1.48, dated April 2023, which is also the very last line of the original. mwah 💋

📦 where this page comes from