Poll SCSI Sense Data and Progress with sg_requests

By the end of this guide, you will be able to send a SCSI REQUEST SENSE command, inspect its response, and poll a device for progress without confusing a transport failure with a sense-data result. The examples use sg_requests from the sg3-utils package. Allow about 10 minutes if you already know the target device; allow longer if you first need to identify the correct SCSI generic node.

Prerequisites

• 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 requires elevated privileges.

1. Confirm the local command

Check the installed interface before building 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, manpage revision and 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 with a fixed transcript.

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

3. Make the exit status reflect sense data

Add --status when a shell script must treat decoded sense information as the 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 that the device is broken. First distinguish a sense condition, a permission problem and a pass-through failure. For example, querying /dev/null is not a valid device test: this utility reports an inappropriate-ioctl error because that file is not a SCSI device.

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 subsequent checks. This is deliberately not a fast polling loop.

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

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, although a vendor could assign that opcode. Used twice, it bypasses the pass-through call so that 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 and recovery

• 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 that the path is 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.
• No progress percentage: the device may not expose progress, or the preceding operation may 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 after collecting the evidence.

Done means

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