Poll SCSI Sense Data and Progress with sg_requests

sg_requests sends a SCSI REQUEST SENSE command and lets you inspect or poll the response. It can even watch a progress percentage on some long-running operations. The examples use sg_requests from the sg3-utils package. Allow about 10 minutes if you already know the target device, longer if you first need to identify the correct SCSI generic node.

Before you start

• A Linux host with sg3-utils installed. This guide was checked with package version 1.46-3ubuntu4; the installed utility reports sg_requests 1.36 (20210329).
• A SCSI device that accepts the REQUEST SENSE command, and its device path. Substitute a real path for /dev/sgX in every example.
• Permission to open that device. The utility opens it read-only, but access to a SCSI generic node commonly needs elevated privileges anyway.

1. Confirm the local command

Check the installed interface before you build a script around it:

sg_requests --version
sg_requests --help

The version command should print a line similar to sg_requests: version: 1.36 20210329. The help text confirms that the required positional argument is DEVICE, and that the default is one REQUEST SENSE command with a maximum response length of 252 bytes.

The manpage shipped with this host is labelled sg3_utils 1.45, while the installed package is 1.46-3ubuntu4 and the program identifies itself as 1.36. Keep that distinction in incident notes: the package, the manpage revision and the utility version are not necessarily the same number.

2. Request and display sense data

Run one request and ask for an ASCII hexadecimal response:

sudo sg_requests --hex /dev/sgX

sudo is only needed when your current account cannot open the device. The command sends one REQUEST SENSE command, because --num defaults to 1. With a compatible device, output is the returned parameter data in hexadecimal. The exact bytes depend on the device state, so do not compare them against a fixed transcript.

Without --hex, the normal response format is a decoded, human-readable sense-data report when the device returns data the utility can interpret. Use hexadecimal when you need to preserve the response for an investigation, or compare fields against a SCSI specification.

3. Make the exit status reflect sense data

Add --status when a shell script must treat decoded sense information as the actual result:

if sudo sg_requests --status /dev/sgX; then
    echo "REQUEST SENSE reported no sense condition"
else
    rc=$?
    echo "REQUEST SENSE reported a condition (exit $rc)" >&2
fi

If the command itself finishes without a SCSI error, --status analyses the parameter data as sense data. A NO SENSE key with zero additional sense code and qualifier produces exit status 0. Other sense conditions can produce a non-zero status; the manpage points to sg3-utils(8) for the complete exit-status meanings. One documented case is a NO SENSE key with non-zero information for a failure-prediction threshold condition, which returns 10.

Do not use a bare non-zero test to claim the device is broken. First distinguish a sense condition, a permission problem and a pass-through failure. Querying /dev/null, for example, is not a valid device test: this utility reports an inappropriate-ioctl error because that file is not a SCSI device at all.

4. Poll a long-running operation

Some SCSI operations expose a percentage in sense data while they continue. Ask sg_requests to poll for it:

sudo sg_requests --progress --num=20 /dev/sgX

The utility stops when it reaches the requested number of commands, or when an error occurs. If it detects an initial progress indication and NUM is greater than 1, it waits 30 seconds before the next check. This is deliberately not a fast polling loop.

--progress ignores --hex, --raw and --time. Use it for a device operation already known to expose progress, such as a long-running format started with an immediate-return setting. It cannot make an ordinary device invent a percentage out of nowhere.

For a one-off diagnostic where waiting is undesirable, omit --progress and request a single response. Never start or interrupt a format, tape operation or other media-changing command just to test this utility.

5. Repeat requests or measure throughput

Use --num for repeated requests and --time to calculate the average operations per second:

sudo sg_requests --num=10 --time /dev/sgX

This sends up to ten commands and stops early if an error occurs. It is a diagnostic workload, not a benchmark of the disk. A real device may log, wake, or otherwise react to each command, so keep the count small unless you have a specific reason to repeat it.

The --error option is different. Used once, it changes the opcode to 0xff, which should be rejected, though a vendor could assign that opcode to something. Used twice, it bypasses the pass-through call so package-library overhead can be measured. Reserve these modes for controlled testing and never use the once form against an unknown production device.

6. Choose response format and length deliberately

For a script that needs the raw response bytes, redirect the binary output rather than displaying it in a terminal:

sudo sg_requests --raw /dev/sgX > sense.bin
od -Ax -tx1 sense.bin

The --raw response is binary. The default maximum response length is 252 bytes; set another allocation length with --maxlen=LEN, up to 255 bytes. The manpage notes that SPC-4 recommends 252. A zero length also selects the default.

Use --desc when the device supports descriptor sense format rather than fixed format:

sudo sg_requests --desc --hex /dev/sgX

Descriptor format is supported by SPC-3 and later devices. An older device may ignore the bit, or return an illegal-request condition. This option changes the requested format; it does not convert a fixed-format response after the fact.

Common traps

• Permission denied. Retry with the least privilege needed, normally sudo for the single command. Do not make the device node world-writable as a shortcut.
• Inappropriate ioctl or pass-through error. Verify the path is actually a SCSI device and that the kernel driver exposes the required pass-through interface. There is no file to repair or undo; correct the path or access conditions instead.
• No progress percentage. The device may not expose progress, or the preceding operation may already have completed. Remove --progress for ordinary sense inspection.
• Unreadable output after --raw. The output file is binary by design. Inspect it with od, or remove the temporary file once you have collected the evidence.

Done means

• Version and help checked. You verified the installed version and help output.
• Correct device used. You used the correct SCSI device path and understood whether privilege escalation was needed.
• Right format chosen. You chose decoded, hexadecimal or raw output for the task.
• Status option used when needed. You used --status when sense data, rather than only SCSI command status, should control a script.
• Polling treated as device-specific. You treated progress polling and repeated requests as device-specific diagnostic work, not harmless generic polling.