{ "content": [ { "type": "text", "text": "# sg_write_same (man)\n\n## NAME\n\nsgwritesame - send SCSI WRITE SAME command\n\n## SYNOPSIS\n\nsgwritesame [--10] [--16] [--32] [--anchor] [--ff] [--grpnum=GN] [--help] [--in=IF]\n[--lba=LBA] [--lbdata] [--num=NUM] [--ndob] [--pbdata] [--timeout=TO] [--unmap] [--verbose]\n[--version] [--wrprotect=WPR] [--xferlen=LEN] DEVICE\n\n## DESCRIPTION\n\nSend the SCSI WRITE SAME (10, 16 or 32 byte) command to DEVICE. This command writes the given\nblock NUM times to consecutive blocks on the DEVICE starting at logical block address LBA.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **OPTIONS** (19 subsections)\n- **UNMAP**\n- **NOTES**\n- **EXIT STATUS**\n- **EXAMPLES**\n- **AUTHORS**\n- **REPORTING BUGS**\n- **COPYRIGHT**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "sg_write_same", "section": "", "mode": "man", "summary": "sgwritesame - send SCSI WRITE SAME command", "synopsis": "sgwritesame [--10] [--16] [--32] [--anchor] [--ff] [--grpnum=GN] [--help] [--in=IF]\n[--lba=LBA] [--lbdata] [--num=NUM] [--ndob] [--pbdata] [--timeout=TO] [--unmap] [--verbose]\n[--version] [--wrprotect=WPR] [--xferlen=LEN] DEVICE", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "-R", "long": "--10", "arg": null, "description": "send a SCSI WRITE SAME (10) command to DEVICE. The ability to set the --unmap (and --anchor) options to this command was added in SBC-3 revision 26." }, { "flag": "-S", "long": "--16", "arg": null, "description": "send a SCSI WRITE SAME (16) command to DEVICE." }, { "flag": "-T", "long": "--32", "arg": null, "description": "send a SCSI WRITE SAME (32) command to DEVICE." }, { "flag": "-a", "long": "--anchor", "arg": null, "description": "sets the ANCHOR bit in the cdb. Introduced in SBC-3 revision 22. That draft requires the --unmap option to also be specified." }, { "flag": "-f", "long": "--ff", "arg": null, "description": "the data-out buffer sent with this command is initialized with 0xff bytes when this option is given." }, { "flag": "-g", "long": "--grpnum", "arg": null, "description": "sets the 'Group number' field to GN. Defaults to a value of zero. GN should be a value between 0 and 63." }, { "flag": "-h", "long": "--help", "arg": null, "description": "output the usage message then exit." }, { "flag": "-i", "long": "--in", "arg": null, "description": "read data (binary) from file named IF and use it as the data-out buffer for the SCSI WRITE SAME command. The length of the data-out buffer is --xferlen=LEN or, if that is not given, the length of the IF file. If IF is \"-\" then stdin is read. If this option and the --ff are not given then 0x00 bytes are used as fill with the length of the data-out buffer obtained from --xferlen=LEN or by calling READ CAPACITY(16 or 10). If the response to READ CAPACITY(16) has the PROTEN bit set then data- out buffer size is modified accordingly with the last 8 bytes set to 0xff." }, { "flag": "-l", "long": "--lba", "arg": null, "description": "where LBA is the logical block address to start the WRITE SAME command. Defaults to lba 0 which is a dangerous block to overwrite on a disk that is in use. Assumed to be in decimal unless prefixed with '0x' or has a trailing 'h'." }, { "flag": "-L", "long": "--lbdata", "arg": null, "description": "sets the LBDATA bit in the WRITE SAME cdb. This bit was made obsolete in sbc3r32 in September 2012." }, { "flag": "-N", "long": "--ndob", "arg": null, "description": "sets the NDOB bit in the WRITE SAME (16 and 32 byte) commands. NDOB stands for No Data-Out Buffer. Default is to clear this bit. When this option is given then --in=IF is not allowed and --xferlen=LEN can only be given if LEN is 0 . By default zeros are written in each block, but it is possible that the \"provisioning initialization pattern\" is written depending on other settings." }, { "flag": "-n", "long": "--num", "arg": null, "description": "where NUM is the number of blocks, starting at LBA, to write the data-out buffer to. The default value for NUM is 1. The value corresponds to the 'Number of logical blocks' field in the WRITE SAME cdb. Note that a value of 0 in NUM may be interpreted as write the data-out buffer on every block starting at LBA to the end of the DEVICE. If the WSNZ bit (introduced in sbc3r26, January 2011) in the Block Limits VPD page is set then the value of 0 is dis‐ allowed, yielding an Invalid request sense key." }, { "flag": "-P", "long": "--pbdata", "arg": null, "description": "sets the PBDATA bit in the WRITE SAME cdb. This bit was made obsolete in sbc3r32 in September 2012." }, { "flag": "-t", "long": "--timeout", "arg": null, "description": "where TO is the command timeout value in seconds. The default value is 60 seconds. If NUM is large (or zero) a WRITE SAME command may require considerably more time than 60 seconds to complete." }, { "flag": "-U", "long": "--unmap", "arg": null, "description": "sets the UNMAP bit in the WRITE SAME(10, 16 and 32) cdb. See UNMAP section below." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "increase the degree of verbosity (debug messages)." }, { "flag": "-V", "long": "--version", "arg": null, "description": "output version string then exit." }, { "flag": "-w", "long": "--wrprotect", "arg": null, "description": "sets the \"Write protect\" field in the WRITE SAME cdb to WPR. The default value is zero. WPR should be a value between 0 and 7. When WPR is 1 or greater, and the disk's protection type is 1 or greater, then 8 extra bytes of protection information are ex‐ pected or generated (to place in the command's data-out buffer)." }, { "flag": "-x", "long": "--xferlen", "arg": null, "description": "where LEN is the data-out buffer length. Defaults to the length of the IF file or, if that is not given, then the READ CAPACITY(16 or 10) command is used to find the 'Logi‐ cal block length in bytes'. That figure may be increased by 8 bytes if the DEVICE's protection type is 1 or greater and the WRPROTECT field (see --wrprotect=WPR) is 1 or greater. If both this option and the IF option are given and LEN exceeds the length of the IF file then LEN is the data-out buffer length with zeros used as pad bytes." } ], "examples": [ "BEWARE: all these examples will overwrite the data on one or more blocks, potentially CLEAR‐", "ING the WHOLE DISK.", "One simple usage is to write blocks of zero from (and including) a given LBA for 63 blocks:", "sgwritesame --lba=0x1234 --num=63 /dev/sdc", "Since --xferlen=LEN has not been given, then this utility will call the READ CAPACITY command", "on /dev/sdc to determine the number of bytes in a logical block. Let us assume that is 512", "bytes. Since --in=IF is not given a block of zeros is assumed. So 63 blocks of zeros (each", "block containing 512 bytes) will be written from (and including) LBA 0x1234 . Note that only", "one block of zeros is passed to the SCSI WRITE SAME command in the data-out buffer (as re‐", "quired by SBC-3). Using the WRITE SAME SCSI command to write one or more blocks blocks of ze‐", "ros is equivalent to the NVMe command: Write Zeroes.", "Now we will write zero blocks to the WHOLE disk. [Note sanitize type commands will also clear", "blocks and metadata that are not directly visible]:", "sgwritesame --lba=0x0 --num=0 /dev/sdc", "Yes, in this context --num=0 means the rest of the disk. The above invocation may give an er‐", "ror due to the WSNZ bit in the Block Limits VPD page being set. To get around that try:", "sgwritesame --lba=0x0 --ndob /dev/sdc", "this invocation, if supported, has the added benefit of not sending a data out buffer of ze‐", "ros. Notes that it is possible that the \"provisioning initialization pattern\" is written to", "each block instead of zeros.", "A similar example follows but in this case the blocks are \"unmapped\" (\"trimmed\" in ATA speak)", "rather than zeroed:", "sgwritesame --unmap -L 0x1234 -n 63 /dev/sdc", "Note that if the LBPRZ bit in the READ CAPACITY(16) response is set (i.e. LPPRZ is an acro‐", "nym for logical block provisioning read zeros) then these two examples do the same thing, at", "least seen from the point of view of subsequent reads.", "This utility can also be used to write protection information (PI) on disks formatted with a", "protection type greater than zero. PI is 8 bytes of extra data appended to the user data of a", "logical block: the first two bytes are a CRC (the \"guard\"), the next two bytes are the \"ap‐", "plication tag\" and the last four bytes are the \"reference tag\". With protection types 1 and 2", "if the application tag is 0xffff then the guard should not be checked (against the user", "data).", "In this example we assume the logical block size (of the user data) is 512 bytes and the disk", "has been formatted with protection type 1. Since we are going to modify LBA 2468 then we take", "a copy of it first:", "dd if=/dev/sdb skip=2468 bs=512 of=2468.bin count=1", "The following command line sets the user data to zeros and the PI to 8 0xFF bytes on LBA", "2468:", "sgwritesame --lba=2468 /dev/sdb", "Reading back that block should be successful because the application tag is 0xffff which sup‐", "presses the guard (CRC) check (which would otherwise be wrong):", "dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1", "Now an attempt is made to create a binary file with zeros in the user data, 0x0000 in the ap‐", "plication tag and 0xff bytes in the other two PI fields. It is awkward to create 0xff bytes", "in a file (in Unix) as the \"tr\" command below shows:", "dd if=/dev/zero bs=1 count=512 of=ud.bin", "tr \"\\000\" \"\\377\" < /dev/zero | dd bs=1 of=ffs.bin count=8", "cat ud.bin ffs.bin > lb.bin", "dd if=/dev/zero bs=1 count=2 seek=514 conv=notrunc of=lb.bin", "The resulting file can be viewed with 'hexdump -C lb.bin' and should contain 520 bytes. Now", "that file can be written to LBA 2468 as follows:", "sgwritesame --lba=2468 wrprotect=3 --in=lb.bin /dev/sdb", "Note the --wrprotect=3 rather than being set to 1, since we want the WRITE SAME command to", "succeed even though the PI data now indicates the user data is corrupted. When an attempt is", "made to read the LBA, an error should occur:", "dd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1", "dd errors are not very expressive, if dmesg is checked there should be a line something like", "this: \"[sdb] Add. Sense: Logical block guard check failed\". The block can be corrected by", "doing a \"sgwritesame --lba=1234 /dev/sdb\" again or restoring the original contents of that", "LBA:", "dd if=2468.bin bs=512 seek=2468 of=/dev/sdb conv=notrunc count=1", "Hopefully the dd command would never try to truncate the output file when it is a block de‐", "vice." ], "see_also": [ { "name": "sgwritex", "section": "sg3utils", "url": "https://www.chedong.com/phpMan.php/man/sgwritex/sg3utils/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 4, "subsections": [] }, { "name": "DESCRIPTION", "lines": 43, "subsections": [] }, { "name": "OPTIONS", "lines": 3, "subsections": [ { "name": "-R --10", "lines": 3, "flag": "-R", "long": "--10" }, { "name": "-S --16", "lines": 2, "flag": "-S", "long": "--16" }, { "name": "-T --32", "lines": 2, "flag": "-T", "long": "--32" }, { "name": "-a --anchor", "lines": 3, "flag": "-a", "long": "--anchor" }, { "name": "-f --ff", "lines": 3, "flag": "-f", "long": "--ff" }, { "name": "-g --grpnum", "lines": 3, "flag": "-g", "long": "--grpnum" }, { "name": "-h --help", "lines": 2, "flag": "-h", "long": "--help" }, { "name": "-i --in", "lines": 8, "flag": "-i", "long": "--in" }, { "name": "-l --lba", "lines": 4, "flag": "-l", "long": "--lba" }, { "name": "-L --lbdata", "lines": 3, "flag": "-L", "long": "--lbdata" }, { "name": "-N --ndob", "lines": 6, "flag": "-N", "long": "--ndob" }, { "name": "-n --num", "lines": 8, "flag": "-n", "long": "--num" }, { "name": "-P --pbdata", "lines": 3, "flag": "-P", "long": "--pbdata" }, { "name": "-t --timeout", "lines": 4, "flag": "-t", "long": "--timeout" }, { "name": "-U --unmap", "lines": 2, "flag": "-U", "long": "--unmap" }, { "name": "-v --verbose", "lines": 2, "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "lines": 2, "flag": "-V", "long": "--version" }, { "name": "-w --wrprotect", "lines": 5, "flag": "-w", "long": "--wrprotect" }, { "name": "-x --xferlen", "lines": 7, "flag": "-x", "long": "--xferlen" } ] }, { "name": "UNMAP", "lines": 41, "subsections": [] }, { "name": "NOTES", "lines": 9, "subsections": [] }, { "name": "EXIT STATUS", "lines": 3, "subsections": [] }, { "name": "EXAMPLES", "lines": 90, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "sgwritesame - send SCSI WRITE SAME command\n", "subsections": [] }, "SYNOPSIS": { "content": "sgwritesame [--10] [--16] [--32] [--anchor] [--ff] [--grpnum=GN] [--help] [--in=IF]\n[--lba=LBA] [--lbdata] [--num=NUM] [--ndob] [--pbdata] [--timeout=TO] [--unmap] [--verbose]\n[--version] [--wrprotect=WPR] [--xferlen=LEN] DEVICE\n", "subsections": [] }, "DESCRIPTION": { "content": "Send the SCSI WRITE SAME (10, 16 or 32 byte) command to DEVICE. This command writes the given\nblock NUM times to consecutive blocks on the DEVICE starting at logical block address LBA.\n\nThe length of the block to be written multiple times is obtained from either the LEN argu‐\nment, or the length of the given input file IF, or by calling READ CAPACITY(16) on DEVICE.\nThe contents of the block to be written are obtained from the input file IF or zeros are\nused. If READ CAPACITY(16) is called (which implies IF was not given) and the PROTEN bit is\nset then an extra 8 bytes (i.e. more than the logical block size) of 0xff are sent. If READ\nCAPACITY(16) fails then READ CAPACITY(10) is used to determine the block size.\n\nIf neither --10, --16 nor --32 is given then WRITE SAME(10) is sent unless one of the follow‐\ning conditions is met. If LBA (plus NUM) exceeds 32 bits, NUM exceeds 65535, or the --unmap\noption is given then WRITE SAME(16) is sent. The --10, --16 and --32 options are mutually\nexclusive.\n\nSBC-3 revision 35d introduced a \"No Data-Out Buffer\" (NDOB) bit which, if set, bypasses the\nrequirement to send a single block of data to the DEVICE together with the command. Only\nWRITE SAME (16 and 32 byte) support the NDOB bit. If given, a user block of zeros is assumed;\nif required, protection information of 0xffs is assumed.\n\nIn SBC-3 revision 26 the UNMAP and ANCHOR bits were added to the WRITE SAME (10) command.\nSince the UNMAP bit has been in WRITE SAME (16) and WRITE SAME (32) since SBC-3 revision 18,\nthe lower of the two (i.e. WRITE SAME (16)) is the default when the --unmap option is given.\nTo send WRITE SAME (10) use the --10 option.\n\nTake care: The WRITE SAME(10, 16 and 32) commands may interpret a NUM of zero as write to the\nend of DEVICE. This utility defaults NUM to 1 . The WRITE SAME commands have no IMMED bit so\nif NUM is large (or zero) then an invocation of this utility could take a long time, poten‐\ntially as long as a FORMAT UNIT command. In such situations the command timeout value TO may\nneed to be increased from its default value of 60 seconds. In SBC-3 revision 26 the WSNZ\n(write same no zero) bit was added to the Block Limits VPD page [0xB0]. If set the WRITE SAME\ncommands will not accept a NUM of zero. The same SBC-3 revision added the \"Maximum Write Same\nLength\" field to the Block Limits VPD page.\n\nThe Logical Block Provisioning VPD page [0xB2] contains the LBPWS and LBPWS10 bits. If LBPWS\nis set then WRITE SAME (16) supports the UNMAP bit. If LBPWS10 is set then WRITE SAME (10)\nsupports the UNMAP bit. If either LBPWS or LBPWS10 is set and the WRITE SAME (32) is sup‐\nported then WRITE SAME (32) supports the UNMAP bit.\n\nAs a precaution against an accidental 'sgwritesame /dev/sda' (for example) overwriting LBA\n0 on /dev/sda with zeros, at least one of the --in=IF, --lba=LBA or --num=NUM options must be\ngiven. Obviously this utility can destroy a lot of user data so check the options carefully.\n", "subsections": [] }, "OPTIONS": { "content": "Arguments to long options are mandatory for short options as well. The options are arranged\nin alphabetical order based on the long option name.\n", "subsections": [ { "name": "-R --10", "content": "send a SCSI WRITE SAME (10) command to DEVICE. The ability to set the --unmap (and\n--anchor) options to this command was added in SBC-3 revision 26.\n", "flag": "-R", "long": "--10" }, { "name": "-S --16", "content": "send a SCSI WRITE SAME (16) command to DEVICE.\n", "flag": "-S", "long": "--16" }, { "name": "-T --32", "content": "send a SCSI WRITE SAME (32) command to DEVICE.\n", "flag": "-T", "long": "--32" }, { "name": "-a --anchor", "content": "sets the ANCHOR bit in the cdb. Introduced in SBC-3 revision 22. That draft requires\nthe --unmap option to also be specified.\n", "flag": "-a", "long": "--anchor" }, { "name": "-f --ff", "content": "the data-out buffer sent with this command is initialized with 0xff bytes when this\noption is given.\n", "flag": "-f", "long": "--ff" }, { "name": "-g --grpnum", "content": "sets the 'Group number' field to GN. Defaults to a value of zero. GN should be a\nvalue between 0 and 63.\n", "flag": "-g", "long": "--grpnum" }, { "name": "-h --help", "content": "output the usage message then exit.\n", "flag": "-h", "long": "--help" }, { "name": "-i --in", "content": "read data (binary) from file named IF and use it as the data-out buffer for the SCSI\nWRITE SAME command. The length of the data-out buffer is --xferlen=LEN or, if that is\nnot given, the length of the IF file. If IF is \"-\" then stdin is read. If this option\nand the --ff are not given then 0x00 bytes are used as fill with the length of the\ndata-out buffer obtained from --xferlen=LEN or by calling READ CAPACITY(16 or 10). If\nthe response to READ CAPACITY(16) has the PROTEN bit set then data- out buffer size\nis modified accordingly with the last 8 bytes set to 0xff.\n", "flag": "-i", "long": "--in" }, { "name": "-l --lba", "content": "where LBA is the logical block address to start the WRITE SAME command. Defaults to\nlba 0 which is a dangerous block to overwrite on a disk that is in use. Assumed to be\nin decimal unless prefixed with '0x' or has a trailing 'h'.\n", "flag": "-l", "long": "--lba" }, { "name": "-L --lbdata", "content": "sets the LBDATA bit in the WRITE SAME cdb. This bit was made obsolete in sbc3r32 in\nSeptember 2012.\n", "flag": "-L", "long": "--lbdata" }, { "name": "-N --ndob", "content": "sets the NDOB bit in the WRITE SAME (16 and 32 byte) commands. NDOB stands for No\nData-Out Buffer. Default is to clear this bit. When this option is given then --in=IF\nis not allowed and --xferlen=LEN can only be given if LEN is 0 .\nBy default zeros are written in each block, but it is possible that the \"provisioning\ninitialization pattern\" is written depending on other settings.\n", "flag": "-N", "long": "--ndob" }, { "name": "-n --num", "content": "where NUM is the number of blocks, starting at LBA, to write the data-out buffer to.\nThe default value for NUM is 1. The value corresponds to the 'Number of logical\nblocks' field in the WRITE SAME cdb.\nNote that a value of 0 in NUM may be interpreted as write the data-out buffer on every\nblock starting at LBA to the end of the DEVICE. If the WSNZ bit (introduced in\nsbc3r26, January 2011) in the Block Limits VPD page is set then the value of 0 is dis‐\nallowed, yielding an Invalid request sense key.\n", "flag": "-n", "long": "--num" }, { "name": "-P --pbdata", "content": "sets the PBDATA bit in the WRITE SAME cdb. This bit was made obsolete in sbc3r32 in\nSeptember 2012.\n", "flag": "-P", "long": "--pbdata" }, { "name": "-t --timeout", "content": "where TO is the command timeout value in seconds. The default value is 60 seconds. If\nNUM is large (or zero) a WRITE SAME command may require considerably more time than 60\nseconds to complete.\n", "flag": "-t", "long": "--timeout" }, { "name": "-U --unmap", "content": "sets the UNMAP bit in the WRITE SAME(10, 16 and 32) cdb. See UNMAP section below.\n", "flag": "-U", "long": "--unmap" }, { "name": "-v --verbose", "content": "increase the degree of verbosity (debug messages).\n", "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "content": "output version string then exit.\n", "flag": "-V", "long": "--version" }, { "name": "-w --wrprotect", "content": "sets the \"Write protect\" field in the WRITE SAME cdb to WPR. The default value is\nzero. WPR should be a value between 0 and 7. When WPR is 1 or greater, and the disk's\nprotection type is 1 or greater, then 8 extra bytes of protection information are ex‐\npected or generated (to place in the command's data-out buffer).\n", "flag": "-w", "long": "--wrprotect" }, { "name": "-x --xferlen", "content": "where LEN is the data-out buffer length. Defaults to the length of the IF file or, if\nthat is not given, then the READ CAPACITY(16 or 10) command is used to find the 'Logi‐\ncal block length in bytes'. That figure may be increased by 8 bytes if the DEVICE's\nprotection type is 1 or greater and the WRPROTECT field (see --wrprotect=WPR) is 1 or\ngreater. If both this option and the IF option are given and LEN exceeds the length of\nthe IF file then LEN is the data-out buffer length with zeros used as pad bytes.\n", "flag": "-x", "long": "--xferlen" } ] }, "UNMAP": { "content": "Logical block provisioning is a new term introduced in SBC-3 revision 25 for the ability to\nmark blocks as unused. For large storage arrays, it is a way to provision less physical stor‐\nage than the READ CAPACITY command reports is available, potentially allocating more physical\nstorage when WRITE commands require it. For flash memory (e.g. SSD drives) it is a way of po‐\ntentially saving power (and perhaps access time) when it is known large sections (or almost\nall) of the flash memory is not in use. SSDs need wear levelling algorithms to have accept‐\nable endurance and typically over provision to simplify those algorithms; hence they typi‐\ncally contain more physical flash storage than their logical size would dictate.\n\nSupport for logical block provisioning is indicated by the LBPME bit being set in the READ\nCAPACITY(16) command response (see the sgreadcap utility). That implies at least one of the\nUNMAP or WRITE SAME(16) commands is implemented. If the UNMAP command is implemented then the\n\"Maximum unmap LBA count\" and \"Maximum unmap block descriptor count\" fields in the Block Lim‐\nits VPD page should both be greater than zero. The READ CAPACITY(16) command response also\ncontains a LBPRZ bit which if set means that if unmapped blocks are read then zeros will be\nreturned for the data (and if protection information is active, 0xff bytes are returned for\nthat). In SBC-3 revision 27 the same LBPRZ bit was added to the Logical Block Provisioning\nVPD page.\n\nIn SBC-3 revision 25 the LBPU and ANCSUP bits where added to the Logical Block Provisioning\nVPD page. When LBPU is set it indicates that the device supports the UNMAP command (see the\nsgunmap utility). When the ANCSUP bit is set it indicates the device supports anchored\nLBAs.\n\nWhen the UNMAP bit is set in the cdb then the data-out buffer is also sent. Additionally the\ndata section of that data-out buffer should be full of 0x0 bytes while the data protection\nblock, 8 bytes at the end if present, should be set to 0xff bytes. If these conditions are\nnot met and the LBPRZ bit is set then the UNMAP bit is ignored and the data-out buffer is\nwritten to the DEVICE as if the UNMAP bit was zero. In the absence of the --in=IF option,\nthis utility will attempt build a data-out buffer that meets the requirements for the UNMAP\nbit in the cdb to be acted on by the DEVICE.\n\nLogical blocks may also be unmapped by the SCSI UNMAP and FORMAT UNIT commands (see the\nsgunmap and sgformat utilities).\n\nThe unmap capability in SCSI is closely related to the ATA DATA SET MANAGEMENT command with\nthe \"Trim\" bit set. That ATA trim capability does not interact well with SATA command queue‐\ning known as NCQ. T13 have introduced a new command called the SFQ DATA SET MANAGEMENT com‐\nmand also with a the \"Trim\" bit to address that problem. The SCSI WRITE SAME with the UNMAP\nbit set and the UNMAP commands do not have any problems with SCSI queueing.\n", "subsections": [] }, "NOTES": { "content": "Various numeric arguments (e.g. LBA) may include multiplicative suffixes or be given in hexa‐\ndecimal. See the \"NUMERIC ARGUMENTS\" section in the sg3utils(8) man page.\n\nIn Linux, prior to lk 3.17, the sg driver did not support cdb sizes greater than 16 bytes.\nHence a device node like /dev/sg1 which is associated with the sg driver would fail with this\nutility if the --32 option was given (or implied by other options). The bsg driver with de‐\nvice nodes like /dev/bsg/6:0:0:1 does support cdb sizes greater than 16 bytes since its in‐\ntroduction in lk 2.6.28 .\n", "subsections": [] }, "EXIT STATUS": { "content": "The exit status of sgwritesame is 0 when it is successful. Otherwise see the sg3utils(8)\nman page.\n", "subsections": [] }, "EXAMPLES": { "content": "BEWARE: all these examples will overwrite the data on one or more blocks, potentially CLEAR‐\nING the WHOLE DISK.\n\nOne simple usage is to write blocks of zero from (and including) a given LBA for 63 blocks:\n\nsgwritesame --lba=0x1234 --num=63 /dev/sdc\n\nSince --xferlen=LEN has not been given, then this utility will call the READ CAPACITY command\non /dev/sdc to determine the number of bytes in a logical block. Let us assume that is 512\nbytes. Since --in=IF is not given a block of zeros is assumed. So 63 blocks of zeros (each\nblock containing 512 bytes) will be written from (and including) LBA 0x1234 . Note that only\none block of zeros is passed to the SCSI WRITE SAME command in the data-out buffer (as re‐\nquired by SBC-3). Using the WRITE SAME SCSI command to write one or more blocks blocks of ze‐\nros is equivalent to the NVMe command: Write Zeroes.\nNow we will write zero blocks to the WHOLE disk. [Note sanitize type commands will also clear\nblocks and metadata that are not directly visible]:\n\nsgwritesame --lba=0x0 --num=0 /dev/sdc\n\nYes, in this context --num=0 means the rest of the disk. The above invocation may give an er‐\nror due to the WSNZ bit in the Block Limits VPD page being set. To get around that try:\n\nsgwritesame --lba=0x0 --ndob /dev/sdc\n\nthis invocation, if supported, has the added benefit of not sending a data out buffer of ze‐\nros. Notes that it is possible that the \"provisioning initialization pattern\" is written to\neach block instead of zeros.\n\nA similar example follows but in this case the blocks are \"unmapped\" (\"trimmed\" in ATA speak)\nrather than zeroed:\n\nsgwritesame --unmap -L 0x1234 -n 63 /dev/sdc\n\nNote that if the LBPRZ bit in the READ CAPACITY(16) response is set (i.e. LPPRZ is an acro‐\nnym for logical block provisioning read zeros) then these two examples do the same thing, at\nleast seen from the point of view of subsequent reads.\n\nThis utility can also be used to write protection information (PI) on disks formatted with a\nprotection type greater than zero. PI is 8 bytes of extra data appended to the user data of a\nlogical block: the first two bytes are a CRC (the \"guard\"), the next two bytes are the \"ap‐\nplication tag\" and the last four bytes are the \"reference tag\". With protection types 1 and 2\nif the application tag is 0xffff then the guard should not be checked (against the user\ndata).\n\nIn this example we assume the logical block size (of the user data) is 512 bytes and the disk\nhas been formatted with protection type 1. Since we are going to modify LBA 2468 then we take\na copy of it first:\n\ndd if=/dev/sdb skip=2468 bs=512 of=2468.bin count=1\n\nThe following command line sets the user data to zeros and the PI to 8 0xFF bytes on LBA\n2468:\n\nsgwritesame --lba=2468 /dev/sdb\n\nReading back that block should be successful because the application tag is 0xffff which sup‐\npresses the guard (CRC) check (which would otherwise be wrong):\n\ndd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1\n\nNow an attempt is made to create a binary file with zeros in the user data, 0x0000 in the ap‐\nplication tag and 0xff bytes in the other two PI fields. It is awkward to create 0xff bytes\nin a file (in Unix) as the \"tr\" command below shows:\n\ndd if=/dev/zero bs=1 count=512 of=ud.bin\ntr \"\\000\" \"\\377\" < /dev/zero | dd bs=1 of=ffs.bin count=8\ncat ud.bin ffs.bin > lb.bin\ndd if=/dev/zero bs=1 count=2 seek=514 conv=notrunc of=lb.bin\n\nThe resulting file can be viewed with 'hexdump -C lb.bin' and should contain 520 bytes. Now\nthat file can be written to LBA 2468 as follows:\n\nsgwritesame --lba=2468 wrprotect=3 --in=lb.bin /dev/sdb\n\nNote the --wrprotect=3 rather than being set to 1, since we want the WRITE SAME command to\nsucceed even though the PI data now indicates the user data is corrupted. When an attempt is\nmade to read the LBA, an error should occur:\n\ndd if=/dev/sdb skip=2468 bs=512 of=/dev/null count=1\n\ndd errors are not very expressive, if dmesg is checked there should be a line something like\nthis: \"[sdb] Add. Sense: Logical block guard check failed\". The block can be corrected by\ndoing a \"sgwritesame --lba=1234 /dev/sdb\" again or restoring the original contents of that\nLBA:\n\ndd if=2468.bin bs=512 seek=2468 of=/dev/sdb conv=notrunc count=1\n\nHopefully the dd command would never try to truncate the output file when it is a block de‐\nvice.\n", "subsections": [] }, "AUTHORS": { "content": "Written by Douglas Gilbert.\n", "subsections": [] }, "REPORTING BUGS": { "content": "Report bugs to .\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright © 2009-2020 Douglas Gilbert\nThis software is distributed under a FreeBSD license. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n", "subsections": [] }, "SEE ALSO": { "content": "sgformat,sggetlbastatus,sgreadcap,sgvpd,sgunmap, sgwritex(sg3utils)\n\n\n\nsg3utils-1.45 June 2020 SGWRITESAME(8)", "subsections": [] } } } }