SG_READ_BUFFER(8)

✨ SG_READ_BUFFER(8) ✨

okay bestie, welcome to the sg_read_buffer(8) manual 💖 it's part of the SG3_UTILS crew 🎀

🌸 NAME 🌸

sg_read_buffer - send SCSI READ BUFFER command

🦋 SYNOPSIS 🦋

sg_read_buffer [--eh_code=EHC] [--help] [--hex] [--id=ID] [--inhex=FN]
[--length=LEN] [--mode=MO] [--no_output] [--offset=OFF] [--raw]
[--readonly] [--specific=MS] [--verbose] [--version] DEVICE

💅 DESCRIPTION 💅

okay so this tool sends a SCSI READ BUFFER command to the DEVICE 🔥 if the device actually answers, you get to pick how it shows up: decoded, hexadecimal, or raw binary sent to stdout. ngl that's a whole vibe 💜

if the response comes from a "descriptor" mode, it gets decoded unless you pass --hex or --raw 🙈 non-descriptor modes print in hexadecimal by default, unless you use --raw.

the responses for the Read microcode status ('rd_microc_st' [0xf]) and Error history ('err_hist' [0x1c]) modes are decoded as described in spc6r06.pdf and earlier T10 documents 🧚

and literally the best part: you can skip DEVICE entirely and use --inhex=FN instead ✨ FN is a file name (or - for stdin). the contents get treated as hexadecimal (or binary) data representing a SCSI READ BUFFER command response, and then it gets decoded like usual 🫶

🎀 OPTIONS 🎀

ok so the rule is: arguments to long options are mandatory for short options as well 💀 same energy, different outfit.

• -e, --eh_code=EHC — this is the error history code that goes into the Buffer ID field of the cdb 🌈 the Mode field gets set to err_hist [0x1c]. it's basically the same as '--mode=eh --id=EHC'. if you give this plus another option and they contradict each other, it throws an error, so no drama allowed 😭 the default (maximum) response length goes up to 64 bytes when it might need to, and if that happens the output will note it if it gets truncated ✨ for example, setting EHC to 0 decodes the error history directory (unless you use --hex or --raw) 🍓
• -h, --help — prints the usage message and exits 💖 use it multiple times and it also shows the mode names and their acronyms 🫶
• -H, --hex — outputs the response in hexadecimal 🔥 give it twice and you get hex with the matching ASCII on the right side of each line 💅 give it three times and the hex prints without the addresses (indexes) at the start of each line 🙈 that format is perfect for feeding into --inhex=FN on a later run ✨
• -i, --id=ID — sets the Buffer ID field in the cdb 🦋 ID can be anything from 0 (default) up to 255 inclusive 🌸 what it means depends on the value in the Mode field of the cdb 👑
• -I, --inhex=FN — FN is a file name (or - for stdin) containing ASCII hexadecimal or binary that represents a READ BUFFER response 💜 if it's known, this tool decodes that response for you 🧚 it's really better to also give --mode=MO, --id=ID and maybe --specific=MS, because those aren't stored in the response itself 🙈 check the "HEX, BINARY AND JSON FORMATS" section in the sg3_utils manpage for more deets 📖 if you also give --raw, then FN is treated as binary 🔥
• -l, --length=LEN — LEN is the length in bytes that goes into the "allocation length" field of the cdb ✨ the default is 4 bytes, but it bumps up to 64 if the 'err_hist' mode [0x1c] is given or implied 💅 the device might respond with fewer bytes than you asked for, so don't panic 💀 if you use --inhex=FN, the default length jumps to 8192 bytes, and then it can get reduced to match the number of bytes decoded from the contents of FN 🌈
• -m, --mode=MO — sets the mode field in the cdb 💖 MO is a value between 0 (default) and 31 inclusive 🎀 you can also use an abbreviation instead, see the MODES section below 🦋 to list the available mode abbreviations, just use an invalid one (e.g. '--mode=xxx') 👑 for example, to fetch the read buffer descriptor, give '--mode=desc' 🍓
• -N, --no_output — when you give this, the response still gets sent and processed looking for any errors, and then the tool exits 🙈 any data read by the READ BUFFER command gets ignored 💀 this one might be useful for timing bigger reads from the DEVICE buffer in 'data' mode [0x2] ⏱️
• -o, --offset=OFF — sets the buffer offset field in the cdb 🧚 OFF is a byte offset, anywhere from 0 (default) to 2**24-1 ✨
• -r, --raw — if a response comes back, it gets sent to stdout in binary 🌊 when you combine this with --inhex=FN, the contents of FN are assumed to be binary, and the output of this tool is normal ASCII (so _not_ binary) 💅
• -R, --readonly — opens the DEVICE read-only (like with the O_RDONLY flag on Unix) 🔒 the default is read-write, so this is the move if you want to be extra safe 🫶
• -S, --specific=MS — sets the mode specific field in the cdb 🌸 MS is a value between 0 and 7, since it's a 3 bit field 🎀
• -v, --verbose — cranks up the verbosity, aka more debug output 🔍 main character energy for debugging 💜
• -V, --version — prints the version string and then exits 🌈

🧚 MODES 🧚

okay so here's the full list of READ BUFFER command settings for the MODE field 💖 each one starts with an acronym that the MO argument of this utility accepts ✨ right after the acronym, in square brackets, are the matching decimal and hex values that you can also give for MO 🦋 they're listed in numerical order, so no guessing needed 🍓

• hd [0, 0x0] — combined header and data 🥀 (obsolete in SPC-4)
• vendor [1, 0x1] — vendor specific 🌈
• data [2, 0x2] — data 💅
• desc [3, 0x3] — descriptor 👑 this one yields 4 bytes that contain an offset boundary field (1 byte) and a buffer capacity (3 bytes) ✨
• echo [10, 0xa] — reads data from the echo buffer 🫶 (this was called "Echo buffer" in SPC-3)
• echo_desc [11, 0xb] — echo buffer descriptor 🔥 yields 4 bytes, and the last (lowest) 13 bits represent the echo buffer capacity 💜 the maximum echo buffer size is 4096 bytes 🎀
• rd_microc_st [15, 0xf] — read microcode status 🧚 added in spc5r20 ✨
• en_ex [26, 0x1a] — enables the expander communications protocol and the Echo buffer 🌸 made obsolete in SPC-4 🥀
• err_hist|eh [28, 0x1c] — error history 🍓 you can use either 'err_hist' or the short 'eh' abbreviation for this mode 💖 introduced in SPC-4 👑

📝 NOTES 📝

all numbers given with options are assumed to be decimal, bestie 🙈 but if you want hex, you can write it with either a "0x" or "0X" prefix (or put a trailing "h" or "H" on it) ✨

🚪 EXIT STATUS 🚪

the exit status of sg_read_buffer is 0 when it's successful 💅 otherwise, check the sg3_utils(8) man page 📖

👩‍💻 AUTHORS 👩‍💻

written by Luben Tuikov and Douglas Gilbert 🫶

🐛 REPORTING BUGS 🐛

report bugs to <dgilbert at interlog dot com> 💌

⚖️ COPYRIGHT ⚖️

Copyright © 2006-2023 Luben Tuikov and 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_write_buffer(sg3_utils) 💜

---

that's the whole tea ☕💖 this is sg3_utils-1.48 from June 2023, and it's giving SG_READ_BUFFER(8) realness forever 👑✨