SG_REQUESTS(8)

💖 sg_requests 💖

okay bestie, this is the SG3_UTILS manual page for sg_requests 🧚 it's part of the sg3_utils toolkit and it's giving SCSI REQUEST SENSE vibes ✨

✨ NAME ✨

sg_requests - send one or more SCSI REQUEST SENSE commands 🎀

✨ SYNOPSIS ✨

sg_requests [--desc] [--error] [--help] [--hex] [--maxlen=LEN]
[--num=NUM] [--number=NUM] [--progress] [--raw] [--status] [--time]
[--timeout=SE] [--verbose] [--version] DEVICE

✨ DESCRIPTION ✨

okay so this tool sends a SCSI REQUEST SENSE command to your DEVICE and spits back the parameter data it gets in return 💅 that data is supposed to be sense data, and it can be either fixed or descriptor format. both are supported, so no drama 🫶

you can also fire off a bunch of REQUEST SENSE commands in one go with --num=NUM. this is lowkey perfect for timing stuff or keeping an eye on the progress indication 🔥

✨ OPTIONS ✨

Arguments to long options are mandatory for short options as well. no skipping, periodt 💜

• -d, --desc — sets the DESC bit in the REQUEST SENSE SCSI cdb 🌸 this asks the DEVICE to send sense data in descriptor format instead of fixed. it only works if the device knows descriptor format (SPC-3 and later). if the device is pre SPC-3, then flipping that bit in a reserved field might give you a check condition status with an illegal request sense key 💀 but most likely it just gets ignored
• -e, --error — when you use it once, it swaps the REQUEST SENSE opcode from 0x3 to 0xff, which the DEVICE should reject 🙈 there's a tiny chance the vendor has a vendor specific command sitting at 0xff, so keep that in mind. use it twice and the pass-through call that sends the SCSI command gets bypassed entirely 😭 the whole point is to measure how much user space overhead this package's library eats up to set up and process a SCSI command response. this one is usually paired with --num=NUM and --time where NUM is a big number (e.g. 1000000) ✨
• -h, --help — shows the usage message, then exits 🧚
• -H, --hex — outputs the response in ASCII hexadecimal 🍓
• -m, --maxlen=LEN — LEN is the (maximum) response length in bytes 💖 it gets placed in the cdb's "allocation length" field. if you don't give it (or LEN is zero), it defaults to 252. the max LEN is 255, but SPC-4 recommends 252, so stick with that bestie 🫶
• -n, --num=NUM — runs NUM SCSI REQUEST SENSE commands, stopping early if an error happens 🔥 the default NUM is 1 .
• --number=NUM — same energy as --num=NUM 💅 it's here for compatibility with sg_turs.
• -p, --progress — shows a progress indication (a percentage) if the device has one 📈 if you use --num=NUM with NUM greater than 1 and an initial progress indication was detected, this tool waits 30 seconds before checking again 👑 it exits when NUM is reached or when there are no more progress indications. it ignores the --hex, --raw and --time options, so don't be confused. see the NOTES section below 🌈
• -r, --raw — outputs the response in binary, straight to stdout 🦋
• -s, --status — okay this one is the real deal ⭐ if the REQUEST SENSE command finished without error (as shown by its SCSI status), then the parameter data gets analysed as sense data and the exit status is set to match 🔥 by default, when you don't use this option, the parameter data is ignored for exit status purposes. some errors set a sense key of "NO SENSE" with non-zero information in the additional sense code (e.g. the FAILURE PREDICTION THRESHOLD EXCEEDED group of codes). that gives an exit status value of 10 😭 if the sense key is "NO SENSE" and both asc and ascq are zero, the exit status is set to 0 . see the sg3_utils(8) man page for exit status values 💜
• -t, --time — times the SCSI REQUEST SENSE command(s) and works out the average number of operations per second ⏱️✨
• -T, --timeout=SE — SE is the command timeout of each TEST UNIT READY command 🕰️ the unit is seconds. if you give 0, it gets mapped to 60 seconds, which is the default. an alternate long option form is --tmo=SE 🎀
• -v, --verbose — turns up the verbosity (i.e. debug output) 🔍 on top of that, the response (if one was received) gets printed in ASCII-HEX. use this flag multiple times for even more tea ☕
• -V, --version — prints the version string, then exits 🧚

✨ NOTES ✨

okay real talk, in SCSI 1 and 2 the REQUEST SENSE command was super important for error and warning processing 📚 then autosense came along and made it kinda superfluous 🙈

BUT recent SCSI drafts (e.g. SPC-4 rev 14 and SBC-3 rev 14) bring the utility of REQUEST SENSE back. idle and standby (low) power conditions can be detected with this command 🌙

The REQUEST SENSE command is not marked as mandatory in SPC-3 (i.e. for all SCSI devices), but it is marked as mandatory in SBC-2 (i.e. for disks), SSC-3 (i.e. for tapes) and MMC-4 (i.e. for CD/DVD/HD-DVD/BD drives) 💅

The progress indication is optionally part of the sense data 📈 when a prior command that takes forever to finish (and usually blocks other media access commands) is still going, the progress indication can tell you how long until the device is back to its normal state 🫶

The SCSI FORMAT command for disks used with the IMMED bit set is a great example of an operation that takes a significant amount of time and blocks other media access during that time 😭 the IMMED bit set tells FORMAT to hand control back to the application client once the format has started (see SBC-3). several long duration SCSI commands for tape drives also use the progress indication (see SSC-3) 🎬

Early standards suggested that the SCSI TEST UNIT READY command be used for polling the progress indication (see the sg_turs utility). since SPC-3, the standards suggest the SCSI REQUEST SENSE command be used instead 🔄

The DEVICE is opened with a read-only flag (e.g. in Unix with the O_RDONLY flag) 🔒

✨ EXIT STATUS ✨

the exit status of sg_requests 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 © 2004-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 💅

✨ SEE ALSO ✨

sg_turs (sg3_utils) 🦋

---

bestie, that's the whole thing 💖 this sg_requests page from sg3_utils 1.48 (May 2023) is all yours now 🧚✨