Safely repeat a block write with sg_write_same

You will use sg_write_same to write one block pattern across a known range of logical blocks, or to request that a device unmap that range. The command can destroy data quickly, so this guide starts with read-only checks and uses explicit ranges throughout. Allow about 15 minutes for a prepared test device, plus time to confirm the target LBA range from your storage documentation.

You need the sg3-utils package, a SCSI device that supports the requested WRITE SAME variant, and permission to open its device node. The installed package here is sg3-utils 1.46-3ubuntu4; the binary identifies itself as sg_write_same version: 1.31 20200430, while the installed manual page is labelled sg3_utils-1.45. Check your own executable because distributions can package these components with different version labels.

1. Confirm the executable and its version

Start with commands that do not access a device:

$ command -v sg_write_same
/usr/bin/sg_write_same
$ sg_write_same --version
sg_write_same: version: 1.31 20200430

The version output above is an example from this machine. Your package may report a different utility version. Read the local manual page as well, because the command's defaults and safety checks are the contract you are about to use.

Checkpoint: if command -v prints nothing, install or repair sg3-utils through your normal package-management process before continuing. Installation is an administrative action, not part of the write procedure.

2. Inspect the target without writing

Set the device name only after checking it against your SCSI topology and change records. sg_readcap reports the logical block size and capacity; sg_vpd can show the block limits and provisioning pages that affect WRITE SAME.

$ DEVICE=/dev/sgX
$ sg_readcap "$DEVICE"
$ sg_vpd --page=0xb0 "$DEVICE"
$ sg_vpd --page=0xb2 "$DEVICE"

Use the device node that represents the intended SCSI logical unit. The commands above are read-only, but a wrong device name still gives you information about the wrong target. The Block Limits page may report a maximum WRITE SAME length and the WSNZ bit, which means a number-of-blocks value of zero is not accepted. The Logical Block Provisioning page indicates whether the device can use WRITE SAME with UNMAP.

Do not infer the logical block size from a filesystem mount point. Record the value returned by sg_readcap and use it when constructing an input block.

3. Write a bounded range of zeros

With a verified test device, choose a starting LBA and a positive count. This command writes one zero-filled logical block repeatedly to 63 consecutive blocks:

$ sudo sg_write_same --lba=0x1234 --num=63 "$DEVICE"

--lba accepts decimal or hexadecimal values such as 0x1234. --num is the number of logical blocks, not a byte count. If neither --in nor --ff is supplied, the data block is filled with zeros. Without --xferlen, the utility obtains the logical block length with READ CAPACITY and sends one repeated block in the data-out buffer.

The default count is 1, but the default LBA is 0. That combination is dangerous on an in-use disk. The utility therefore requires at least one of --in, --lba, or --num; keep both --lba and --num explicit in scripts.

Expected success is a zero exit status and usually no normal output:

$ status=$?
$ printf 'sg_write_same exit status: %s\n' "$status"
sg_write_same exit status: 0

That status confirms command completion, not that you selected the right disk. Verify the target and range in your change record before treating it as a successful storage operation.

4. Choose the command size deliberately

By default the utility selects WRITE SAME(10). It switches to WRITE SAME(16) when the LBA range needs more than 32 bits, the count exceeds 65535, or --unmap is used. You can force one of the three command sizes with exactly one of --10, --16, or --32:

$ sudo sg_write_same --16 --lba=0x1234 --num=63 "$DEVICE"

Do not add a force option merely to make an error disappear. The device must support the selected SCSI command. WRITE SAME(32) also needs a transport path that accepts a 32-byte CDB; old Linux SCSI generic support did not accept CDBs larger than 16 bytes.

5. Repeat a supplied binary block

To write a pattern other than zeros, make a binary file exactly the size of one logical block, then pass it with --in. For a device whose logical block size is 512 bytes:

$ dd if=/dev/zero of=pattern.bin bs=512 count=1 status=none
$ sudo sg_write_same --in=pattern.bin --lba=0x1234 --num=63 "$DEVICE"

The first command creates a zero block and is safe in the current directory, but it is not a substitute for checking the target. If the input file is shorter than an explicitly supplied --xferlen, the utility pads with zeros. If no transfer length is supplied, the file length determines the data-out buffer length. Keep the file length equal to the device's logical block size unless you have a specific protection-information layout to apply.

To use a file from standard input, pass --in=-. Avoid interactive pipelines for destructive operations: a delayed or truncated input stream is difficult to review. The --ff option fills the data-out buffer with 0xff bytes when no input file is supplied.

6. Treat zero as a special count

Do not use --num=0 as a shorthand for an unknown length. SCSI devices may interpret zero as every block from the starting LBA to the end of the device. That can take a long time and can clear an entire disk. Devices with WSNZ set reject zero instead.

If a full-device operation is genuinely intended, stop and calculate the range from the device capacity, confirm an approved maintenance window, and check the device name a second time. A large positive count can also exceed the default 60-second timeout. Raise it only after estimating the operation:

$ sudo sg_write_same --lba=0x1234 --num=100000 --timeout=1800 "$DEVICE"

The WRITE SAME command has no IMMED bit, so the utility waits for the device. A timeout is not proof that the device stopped changing data; check the target's documentation and logs before retrying.

7. Use UNMAP only when provisioning support is confirmed

--unmap requests logical block provisioning rather than writing an ordinary pattern. The utility selects WRITE SAME(16) by default for this option:

$ sudo sg_write_same --unmap --lba=0x1234 --num=63 "$DEVICE"

Confirm the device's provisioning support first. The command's effect is device-dependent: an unmapped read may return zeros when the device reports LBPRZ, but that is not the same guarantee as writing a durable zero pattern. If the device lacks the required capability, expect an error or an operation that does not provide the semantics your application needs.

8. Recover from a mistaken test

There is no universal undo for overwritten blocks. If the range mattered, restore it from a verified backup or a copy made before the write. For a test device, the recovery is normally to recreate its filesystem or restore its test image, according to the device's role. Do not run another WRITE SAME command as an improvised repair: it can overwrite more blocks and does not recover the old contents.

If the command fails, save its exit status and diagnostic output, then inspect the device logs and SCSI sense data. Check the device path, LBA range, count, logical block size, command variant, protection-information settings, and timeout before retrying. Do not repeatedly retry an operation after a timeout until you know whether the target completed it.