Inspect XCOPY Capability and Status with sg_copy_results

You will finish with a repeatable way to query a SCSI device's Extended Copy (XCOPY) information, check an active copy by list identifier, and keep response decoding separate from copy execution. This guide uses the installed sg3-utils package version 1.46-3ubuntu4; the executable reports sg_copy_results: version: 1.23 20180625.

Allow about ten minutes for a read-only inspection. You need a Linux shell, sg3-utils, and a SCSI generic device path such as /dev/sg3 supplied by your storage documentation. Some modern arrays support XCOPY, but ordinary disks and USB bridges may not. The examples send SCSI commands to the named device. They do not start, stop or cancel a copy, but use a maintenance window when querying a production array is subject to its own change controls.

1. Confirm the installed command

Check the package and binary before using a copied command from another host. These checks are ordinary commands and do not need elevated privileges:

$ dpkg-query -W -f='${Package} ${Version}\n' sg3-utils
sg3-utils 1.46-3ubuntu4
$ command -v sg_copy_results
/usr/bin/sg_copy_results
$ sg_copy_results --version
sg_copy_results: version: 1.23 20180625

Checkpoint: the command must be present, and its help should show the same four service-action selectors used below:

$ sg_copy_results --help
Usage: sg_copy_results [--failed|--params|--receive|--status] ... DEVICE

The installed syntax accepts long options and their short forms. Keep the option spelling from this host's help if a later package changes it.

2. Identify the device path

Use the SCSI generic device that represents the target array or disk, not a guessed block-device name. If you already have a path from your storage inventory, assign it as a quoted shell variable:

$ DEVICE='/dev/sg3'
$ test -e "$DEVICE" && printf 'using %s\n' "$DEVICE"
using /dev/sg3

Replace /dev/sg3 with a real path on your host. Do not infer that /dev/sg3 is safe merely because it exists: SCSI generic numbering can change after a rescan or reboot. Check the device identity with your normal inventory or an approved SCSI inspection tool before sending the query.

Most installations require permission to open the device. If the command reports a permission failure, rerun the same query with the privilege your host policy permits:

$ sudo sg_copy_results --params --readonly "$DEVICE"

sudo is not a magic fix for an unsupported command. It only changes access to the device. Use the least privilege that works.

3. Query operating parameters first

Operating parameters are the useful starting point because they describe whether the target exposes the XCOPY facility and which descriptor limits it reports. The --params option is also the default, but spelling it out makes a runbook easier to review:

$ sg_copy_results --params --readonly "$DEVICE"
Receive copy results (report operating parameters):
    Supports no list identifier: no
    Maximum target descriptor count: 2
    Maximum segment descriptor count: 1
    Maximum descriptor list length: 92 bytes
    Maximum segment length: 33553920 bytes
    Inline data not supported
    Held data limit: 0 bytes
    Maximum stream device transfer size: 0 bytes
    Total concurrent copies: 0
    Maximum concurrent copies: 255
    Data segment granularity: 512 bytes
    Inline data granularity: 1 bytes
    Held data granularity: 1 bytes
    Implemented descriptor list:
        Segment descriptor 0x02: Copy from block device to block device
        Target descriptor 0xe4: Identification descriptor

Your values will be device-specific. Treat the output as capability data, not as a promise that an arbitrary sg_xcopy request will succeed. In particular, a zero concurrent-copy value and an unsupported descriptor are useful constraints, not invitations to guess different descriptor formats.

Checkpoint: record the complete output with the device identity and date. If the device returns a SCSI error or says the command is unsupported, stop here and investigate the array's XCOPY support rather than repeatedly retrying.

4. Check the status of a copy

When an XCOPY operation has a list identifier, select the COPY STATUS service action with --status. The list identifier defaults to zero, so always pass the identifier explicitly when one is known:

$ LIST_ID='7'
$ sg_copy_results --status --list_id="$LIST_ID" --readonly "$DEVICE"
Receive copy results (report copy status):
    ... device-specific status fields ...

The exact fields and wording come from the target's response. Do not treat the ellipsis above as literal output. If your copy manager gave you a different identifier, replace 7; the default of zero is not a discovery mechanism.

The --readonly option opens the device with the Unix read-only flag. It is a sensible default for an inspection run, but it does not turn an unsupported or badly addressed SCSI command into a harmless local file read. Confirm the target path before running it.

5. Request failure details when status points to an error

For a failed segment, use --failed with the same list identifier:

$ sg_copy_results --failed --list_id="$LIST_ID" --readonly "$DEVICE"
Receive copy results (report failed segment details):
    ... device-specific sense and segment data ...

The response is target-specific and contains copy-target sense information when available. Preserve it alongside the original status response. A non-zero exit status means the utility did not complete successfully; the manpage directs you to sg3_utils(8) for the general exit-status and error conventions. Capture standard error as well as standard output when handing the result to a storage vendor.

6. Request held data only when the target supports it

--receive selects RECEIVE DATA for the list identifier. The manpage says this is meaningful only when the relevant segment descriptors support held data, and that decoding this service action is not implemented by sg_copy_results. Treat that as a boundary, not as a format you can safely parse by eye:

$ sg_copy_results --receive --list_id="$LIST_ID" --readonly "$DEVICE"
Receive copy results (receive data):
    ... response or device-specific error ...

Run this only when the operating-parameters response and the XCOPY implementation documentation justify it. It does not retrieve arbitrary file contents, and this utility does not decode the returned data. If you need the raw response for vendor analysis, add --hex and save the output to a controlled diagnostic file:

$ sg_copy_results --status --list_id="$LIST_ID" --hex --readonly "$DEVICE" \
    > "xcopy-status-${LIST_ID}.hex"
$ test -s "xcopy-status-${LIST_ID}.hex" && printf 'saved diagnostic response\n'
saved diagnostic response

Diagnostic output may contain device or workload details. Protect it according to your storage support policy and remove it through your normal records-retention process when it is no longer needed.

7. Tune the response length only for a reason

The allocation length defaults to 520 bytes. Use --xfer_len=BTL when the response you need is known to require a different maximum, keeping the value below 10000:

$ sg_copy_results --params --xfer_len=1024 --readonly "$DEVICE"
Receive copy results (report operating parameters):
    ... response is limited to at most 1024 bytes ...

A larger allocation length does not make the device return more information than it supports. A smaller value can truncate a response. Start with the default and change it only when the device documentation or a captured response gives you a reason. Use --verbose for debugging command details, not as a substitute for interpreting the target's SCSI response.