SG_READ_ATTR(8)

🌸 sg_read_attr 🌸

okay bestie, this is the manual page for SG_READ_ATTR(8) (the SG3_UTILS one) and it's about a tool that sends the SCSI READ ATTRIBUTE command 💅 let's get into it

💖 NAME 💖

okay so the name is sg_read_attr, and its whole job is to send a SCSI READ ATTRIBUTE command ✨

🧚 SYNOPSIS 🧚

sg_read_attr [--cache] [--enumerate] [--ea=EA] [--filter=FL]
[--first=FAI] [--help] [--hex] [--in=FN] [--lvn=LVN] [--maxlen=LEN]
[--pn=PN] [--quiet] [--raw] [--readonly] [--sa=SA] [--verbose]
[--version] DEVICE

🦋 DESCRIPTION 🦋

okay so this sends a SCSI READ ATTRIBUTE command to DEVICE and then spits out whatever data comes back 🫶 the command was introduced in SPC-3 revision 1, so it's technically applicable to all SCSI devices, which is so iconic. in practice though, it's mainly used for tape systems 📼 this utility is based on the SPC-5 draft standard, revision 17 (spc5r17.pdf).

🎀 OPTIONS 🎀

Arguments to long options are mandatory for short options as well. no cap, that rule applies to everything 💅

• -c, --cache — sets the CACHE bit in the READ ATTRIBUTE cdb, which tells the device server to return cached attributes 💾 by default that bit is cleared, which tells the device server not to return cached attributes 🙈
• -e, --enumerate — enumerates all known attributes and service actions ✨ each attribute comes with an identifier, length, format and a name as defined by T10. if DEVICE is given then it gets ignored 💀
• -E, --ea=EA — where EA is an element address that gets placed in the READ ATTRIBUTE cdb. this field only shows up in SMC-2 and SMC-3 drafts for medium changers, which are usually tied to tape libraries 📚 by default this field is set to zero 🧸
• -f, --filter=FL — where FL is an attribute identifier in the range 0 to 65535, or -1. identifiers are usually written in hexadecimal, in which case you prefix the hex number with "0x" or put a trailing "h" on it 🔢 "-1" is the default and means 'match all' 🌈 for every other value of FL, only the matching attribute gets output 🎯
• -F, --first=FAI — where FAI is the "first attribute identifier" field in the cdb 🧩 it seems like the point of this field is that only attributes whose identifiers are equal to or greater than FAI get returned 🤔 the default value of FAI is zero, and attributes come back in ascending identifier order 📈
• -h, --help — outputs the usage message, then exits 🙋‍♀️
• -H, --hex — outputs the response in hexadecimal to stdout 🍓 used once, the whole response comes out as ASCII hexadecimal with a leading address (starting at 0) on each line. used twice, each attribute descriptor in the response gets output separately in hexadecimal. used thrice, the whole response is output in hexadecimal with no leading address on each line 🙌 output made by -HHH (or --hex used three times) can be redirected to a file, and that file will be in a suitable format for --in=FN to use in a later invocation 🔁
• -i, --in=FN — FN is treated as a file name (or - for stdin) containing ASCII hexadecimal or binary that represents the response to a READ ATTRIBUTE command with service action 0x0 (i.e (fetch) attribute values) 📥 when this option is given, DEVICE (if also given) is ignored 🙃 By default, FN is assumed to hold ASCII hexadecimal arranged as bytes, which are delimited by a space, tab or comma 🧁 all characters from (and including) "#" to the end of the line are ignored 💬 if the --raw option is also given, then FN is assumed to contain binary data 🤖 when --raw is given, the internal raw variable gets reset to 0 after the input is processed, so it has no effect on the output 🫠 the READ ATTRIBUTE response doesn't include the service action number it's responding to, so you should give --sa=SA (if it's not service action 0, the attribute values, that's what gets assumed) 🫶
• -l, --lvn=LVN — where LVN is placed in the "logical volume number" field of the cdb 🎯 the default is zero, which is required to be the logical volume number if the device only has one volume 📀
• -m, --maxlen=LEN — where LEN is the (maximum) response length in bytes 📏 it's placed in the cdb's "allocation length" field 🧠 if it's not given (or LEN is zero), then 8192 is used 🌟 the maximum allowed value of LEN is 1048576 🚀
• -p, --pn=PN — where PN is placed in the "partition number" field of the cdb 🗂️ if the DEVICE only has one partition, then its partition number must be zero 💜 the default value of PN is zero 🫧
• -q, --quiet — reduces the amount of info that gets output 🤫 for example, when used once (SA=0), it suppresses the header line that announces the output of attributes 🔇 used twice, it suppresses the name of each attribute and leaves only the associated attribute values (or strings) 🎶
• -r, --raw — outputs the SCSI response (i.e. the data-out buffer) in binary, to stdout 🧃
• -R, --readonly — opens the DEVICE read-only (e.g. in Unix with the O_RDONLY flag) 👀 the default is to open it read-write 🙈
• -s, --sa=SA — where SA is placed in the "service action" field of the cdb 🎀 values from 0 to 63 are accepted, with a default of 0 🌷 spc5r08.pdf defines five service actions: 0 for attribute values; 1 for an attribute list (names, not values); 2 for the logical volume list; 3 for the partition list; 4 is restricted for SMC-3; and 5 for the supported attribute list 📖 you can also give an acronym for SA instead 🔤 it should be one of "av", "al", "lvl", "pn", "smc" or "sa" for service actions 0 to 5 respectively 💅 the acronyms can also be given in upper case, which is giving main character energy 👑
• -v, --verbose — increases the level of verbosity (i.e. debug output) 🔍
• -V, --version — prints the version string, then exits 🏷️

🌈 NOTES 🌈

ngl only tape systems seem to actually implement the SCSI READ ATTRIBUTE command 📼 the vast majority of its definition lives in the SPC standard though, so other device types could use it 🤷‍♀️

a lot of the info READ ATTRIBUTE gives you can also be found in the pages returned by LOG SENSE (see the sg_logs utility) and in the VPD pages returned by the INQUIRY command 🧠

🧚‍♀️ EXAMPLES 🧚‍♀️

okay so to list the attributes of a tape drive whose DEVICE is /dev/sg1, you could use this 🎀

  # sg_read_attr -s al /dev/sg1
  Attribute list:
    Remaining capacity in partition [MiB]
    Maximum capacity in partition [MiB]
    TapeAlert flags
    Load count
    MAM space remaining [B]
    Assigning organization
    Format density code
    ...

to check the number of partitions 🗂️

  # sg_read_attr -s pl /dev/sg1
  Partition number list:
    First partition number: 0
    Number of partitions available: 2

and to see the attribute values (which is the default service action) 💖

  # sg_read_attr /dev/sg1
  Attribute values:
    Remaining capacity in partition [MiB]: 1386103
    Maximum capacity in partition [MiB]: 1386103
    TapeAlert flags: 0
    ....

to redirect the attribute values response to a file for decoding later 📁

  # sg_read_attr -HHH /dev/sg1 > av.hex

and later, the response held in the av.hex file could be decoded with this 🔓

  # sg_read_attr -s av --in=av.hex
  Attribute values:
    Remaining capacity in partition [MiB]: 1386103
    Maximum capacity in partition [MiB]: 1386103
    TapeAlert flags: 0
    ....

🦄 EXIT STATUS 🦄

the exit status of sg_read_attr is 0 when it's successful ✅ otherwise, check out the sg3_utils(8) man page 📚

👩‍💻 AUTHORS 👩‍💻

written by Douglas Gilbert 🫶

🐛 REPORTING BUGS 🐛

report bugs to <dgilbert at interlog dot com> 📬

🔒 COPYRIGHT 🔒

Copyright © 2016-2020 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 🙃

🔗 SEE ALSO 🔗

sg_vpd, sg_logs(sg3_utils) 💜

---

okay that's the whole tea, bestie 🌈 this page came from SG3_UTILS, version sg3_utils-1.46, dated December 2020. slay the tape drives responsibly 🎀💖✨