# SG_WRITE_X - SCSI WRITE normal/ATOMIC/SAME/SCATTERED/STREAM, ORWRIT... - man(8) - [phpMan] [_SG_WRITE_X_(8)](https://www.chedong.com/phpMan.php/man/SGWRITEX/8/markdown) SG3_UTILS [_SG_WRITE_X_(8)](https://www.chedong.com/phpMan.php/man/SGWRITEX/8/markdown) ## NAME sg_write_x - SCSI WRITE normal/ATOMIC/SAME/SCATTERED/STREAM, ORWRITE commands ## SYNOPSIS **sg_write_x **[_--16_] [_--32_] [_--app-tag=AT_] [_--atomic=AB_] [_--bmop=OP,PGP_] [_--bs=BS_] [_--com‐_ _bined=DOF_] [_--dld=DLD_] [_--dpo_] [_--dry-run_] [_--fua_] [_--generation=EOG,NOG_] [_--grpnum=GN_] [_--help_] _--in=IF_ [_--lba=LBA[,LBA...]_] [_--normal_] [_--num=NUM[,NUM...]_] [_--offset=OFF[,DLEN]_] [_--or_] [_--quiet_] [_--ref-tag=RT_] [_--same=NDOB_] [_--scat-file=SF_] [_--scat-raw_] [_--scattered=RD_] [_--stream=ID_] [_--strict_] [_--tag-mask=TM_] [_--timeout=TO_] [_--unmap=U_A_] [_--verbose_] [_--version_] [_--wrprotect=WPR_] _DEVICE_ Synopsis per supported command: **sg_write_x _**--normal_ _--in=IF_ [_--16_] [_--32_] [_--app-tag=AT_] [_--bs=BS_] [_--dld=DLD_] [_--dpo_] [_--fua_] [_--grpnum=GN_] [_--lba=LBA_] [_--num=NUM_] [_--offset=OFF[,DLEN]_] [_--ref-tag=RT_] [_--strict_] [_--tag-mask=TM_] [_--timeout=TO_] [_--wrprotect=WPR_] _DEVICE_ **sg_write_x _**--or_ _--in=IF_ [_--16_] [_--32_] [_--bmop=OP,PGP_] [_--bs=BS_] [_--dpo_] [_--fua_] [_--genera‐_ _tion=EOG,NOG_] [_--grpnum=GN_] [_--lba=LBA_] [_--num=NUM_] [_--offset=OFF[,DLEN]_] [_--strict_] [_--time‐_ _out=TO_] [_--wrprotect=OPR_] _DEVICE_ **sg_write_x _**--atomic=AB_ _--in=IF_ [_--16_] [_--32_] [_--app-tag=AT_] [_--bs=BS_] [_--dpo_] [_--fua_] [_--grp‐_ _num=GN_] [_--lba=LBA_] [_--num=NUM_] [_--offset=OFF[,DLEN]_] [_--ref-tag=RT_] [_--strict_] [_--time‐_ _out=TO_] [_--wrprotect=WPR_] _DEVICE_ **sg_write_x _**--same=NDOB_ [_--16_] [_--32_] [_--app-tag=AT_] [_--bs=BS_] [_--dpo_] [_--fua_] [_--grpnum=GN_] [_--in=IF_] [_--lba=LBA_] [_--num=NUM_] [_--offset=OFF[,DLEN]_] [_--ref-tag=RT_] [_--strict_] [_--time‐_ _out=TO_] [_--unmap=U_A_] [_--wrprotect=WPR_] _DEVICE_ **sg_write_x _**--scattered=RD_ _--in=IF_ [_--16_] [_--32_] [_--app-tag=AT_] [_--bs=BS_] [_--dld=DLD_] [_--dpo_] [_--fua_] [_--grpnum=GN_] [_--lba=LBA[,LBA...]_] [_--num=NUM[,NUM...]_] [_--offset=OFF[,DLEN]_] [_--ref-tag=RT_] [_--scat-file=SF_] [_--scat-raw_] [_--strict_] [_--tag-mask=TM_] [_--timeout=TO_] [_--wr‐_ _protect=WPR_] _DEVICE_ **sg_write_x _**--stream=ID_ _--in=IF_ [_--16_] [_--32_] [_--app-tag=AT_] [_--bs=BS_] [_--dpo_] [_--fua_] [_--grp‐_ _num=GN_] [_--lba=LBA_] [_--num=NUM_] [_--offset=OFF[,DLEN]_] [_--ref-tag=RT_] [_--strict_] [_--tag-mask=TM_] [_--timeout=TO_] [_--wrprotect=WPR_] _DEVICE_ ## DESCRIPTION This utility will send one of six SCSI commands, all associated with writing data to the given _DEVICE_. They are a "normal" WRITE, ORWRITE, WRITE ATOMIC, WRITE SAME, WRITE SCATTERED or WRITE STREAM. This utility supports the 16 and 32 byte variants of all six commands. Hence some closely related commands are not supported (e.g. [WRITE(10)](https://www.chedong.com/phpMan.php/man/WRITE/10/markdown)). All 32 byte variants, apart from [ORWRITE(32)](https://www.chedong.com/phpMan.php/man/ORWRITE/32/markdown), require the _DEVICE_ to be formatted with type 1, 2 or 3 Protection Informa‐ tion (PI), making all logical blocks 8 bytes (or a multiple of 8 bytes) longer on the media. The command line interface is a little crowded with over thirty options. Hence the SYNOPSIS, after listing all the (long) options, lists those applicable to each supported command. For each command synopsis, the option that selects the SCSI command is shown first followed by any required options. If no command option is given then a "normal" WRITE is assumed. Even though the _--scat-file=SF_ option can be given for every command, it is only shown for WRITE SCATTERED where it is most useful. If the _--scat-file=SF_ option is given then neither the _--lba=LBA[,LBA...]_ nor the _--num=NUM[,NUM...]_ options should be given. Only the first item of the _--lba=LBA[,LBA...]_ and the _--num=NUM[,NUM...]_ options (or first pair (or quintet) from the _--scat-file=SF_ option) is used for all but the WRITE SCATTERED command. All commands can take _--dry-run_ and _--verbose_ in addition to those shown in the SYNOPSIS. The logical block size in bytes can be given explicitly with the _--bs=BS_ option, as long as _BS_ is greater than zero. It is typically a power of two, 512 or greater. If the _--bs=BS_ op‐ tion is not given or _BS_ is zero then the SCSI READ CAPACITY command is used to find the logi‐ cal block size. First the READ [CAPACITY(16)](https://www.chedong.com/phpMan.php/man/CAPACITY/16/markdown) command is tried and if successful the logical block size in the response is typically used as the actual block size for this utility. The exception is when PROT_EN is set in the response and the _--wrprotect=WPR_ option is given and non-zero; in which case 8 (bytes) is added to the logical block size to yield the actual block size used by this utility. If READ [CAPACITY(16)](https://www.chedong.com/phpMan.php/man/CAPACITY/16/markdown) fails then READ [CAPACITY(10)](https://www.chedong.com/phpMan.php/man/CAPACITY/10/markdown) is tried and if that works then the logical block size in the response is used as the actual block size. The number of bytes this utility will attempt to read from the file named by _IF_ is the prod‐ uct of the actual block size and the number_of_blocks (_NUM_ or the sum of _NUM_ arguments). If less bytes are read from the file _IF_ and the _--strict_ option is given then this utility exits with an exit status of SG_LIB_FILE_ERROR. If less bytes are read from the file _IF_ and the _--strict_ option is not given then bytes of zero are substituted for the "missing" bytes and this utility continues. Attempts to write multi megabyte data with a single command are likely to fail for one of several reasons. First the operating system might object to allocating a buffer that large. Next the SCSI pass-through usually limits data blocks to a few megabytes or less. Finally the storage device might have a limited amount of RAM to support a write operation such as atomic (as it may need to roll back). The storage device can inform the application client of its limitations via the block limits VPD page (0xb0), with the maximum atomic transfer length field amongst others. A degenerate LBA (Logical Block Address) range descriptor with no PI has an LBA and NUM of zero. A degenerate LBA range descriptor with PI additionally has its RT, AT and TM fields set to zero (note: that is not the default values for RT, AT and TM). They are degenerate in the sense that they are indistinguishable from a pad of zeros that follow the scatter list in the data-out buffer. SBC-4 makes clear that a degenerate LBA range descriptor is valid. This may become an issue if _RD_ given in the _--scattered=RD_ option has the value 0. In this case the logic may need to scan the user provided data to calculate the number of LBA range descrip‐ tors which is required by the WRITE SCATTERED cdb. In the absence of other information the logic will take a degenerate LBA range descriptor as a terminator of the scatter list. The current reference for these commands is draft SBC-4 (T10/BSR INCITS 506) revision 15 dated 9 November 2017. All six SCSI commands are described in that document. WRITE ATOMIC was added in SBC-4 revision 3; WRITE STREAM was added in SBC-4 revision 7; WRITE SCATTERED was added in SBC-4 revision 11 while the others are in the SBC-3 standard. ## OPTIONS Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name. ### -6 --16 send the 16 byte cdb variant of the selected SCSI command. If no command is selected then the (normal) SCSI [WRITE(16)](https://www.chedong.com/phpMan.php/man/WRITE/16/markdown) command is sent. If neither this option nor the _--32_ option is given then this option is assumed. ### -3 --32 send the 32 byte cdb variant of the selected SCSI command. If no command is selected then the (normal) SCSI [WRITE(32)](https://www.chedong.com/phpMan.php/man/WRITE/32/markdown) command is sent. If neither this option nor the _--16_ option is given then then the _--16_ option is assumed. If both this option and the _--16_ option are given then this option takes precedence. Note that apart from [ORWRITE(32)](https://www.chedong.com/phpMan.php/man/ORWRITE/32/markdown) all other 32 byte cdb variants require a _DEVICE_ formatted with type 1, 2 or 3 protec‐ tion information. ### -a --app-tag where _AT_ is the "expected logical block application tag" field found in most of the 32 byte cdb variants (the exception is [ORWRITE(32)](https://www.chedong.com/phpMan.php/man/ORWRITE/32/markdown)). _AT_ is a 16 bit field which means the maximum value is 0xffff. The default value is 0xffff . ### -A --atomic selects the WRITE ATOMIC command and _AB_ is placed in the Atomic Boundary field of its cdb. It is a 16 bit field so the maximum value is 0xffff. If unsure what value to set, try 0 which will attempt to write the whole data-out buffer in a single atomic opera‐ tion. ### -B --bmop where _OP_ and _PGP_ are the values to be placed in [ORWRITE(32)](https://www.chedong.com/phpMan.php/man/ORWRITE/32/markdown)'s BMOP and 'Previous Gen‐ eration Processing' fields respectively. BMOP is a 3 bit field (ranges from 0 to 7) and PGP is a 4 bit field (ranges from 0 to 15). Both fields default to 0. ### -b --bs where _BS_ is the logical block size or the actual block size which will be slightly bigger. The default value is zero. If this option is not given or is given with a _BS_ of zero then the SCSI READ [CAPACITY(16)](https://www.chedong.com/phpMan.php/man/CAPACITY/16/markdown) command is sent to _DEVICE_. If that fails then the READ [CAPACITY(10)](https://www.chedong.com/phpMan.php/man/CAPACITY/10/markdown) command is sent. The logical and actual block size will be de‐ rived from the response of the READ CAPACITY command. This section assumes _BS_ is greater than zero. If _BS_ is less than 512 (bytes) or not a multiple of 8, a warning is issued and the utility continues unless the _--strict_ op‐ tion is also given. If _BS_ is a power of two (e.g. 512) then the logical and actual block size is set to _BS_ (e.g. 512). If _BS_ is not a power of two (e.g. 520) then the logical block size is set to the closest power of two less than _BS_ (e.g. 512) and the actual block size is set to _BS_ (e.g. 520). If the logical and actual block size are different then a later check will reduce the actual block size back to the logical block size unless _--wrprotect=WPR_ is greater than zero. ### -c --combined This option only applies to WRITE SCATTERED and assumes the whole data-out buffer can be read from _IF_ given by the _--in=IF_ option. The whole data-out buffer is the parame‐ ter list header, followed by zero or more LBA range descriptors, optionally followed by some pad bytes and then the data to be written to the media. If the _--lba=LBA[,LBA...]_, _--num=NUM[,NUM...]_ or _--scat-file=SF_ options are also given then an error is generated. The _DOF_ argument should be the value suitable for the 'Logical Block Data Offset' field in the WRITE SCATTERED cdb. This is the offset in the data-out buffer where the data to write to the media commences. The unit of that field is the actual block size which is the logical block size plus a multiple of 8, if pro‐ tection information (PI) is being sent. When _WPR_ (from _--wrprotect=WPR_) is greater than zero then PI is expected. SBC-4 revision 15 does not state it but it would appear that a _DOF_ value of 0 is invalid. It is suggested that this option be used with the _--strict_ option while experimenting as random or incorrect data fed in via the _--in=IF_ option could write a lot of "interesting" data all over the _DEVICE_. If _DOF_ is given as 0 the utility will scan the data in _IF_ until _RD_ LBA range descriptors are found; or if _RD_ is also 0 until a degenerate LBA range descriptor is found. ### -D --dld where _DLD_ is the duration limits descriptor spread across 3 bits in the SCSI [WRITE(16)](https://www.chedong.com/phpMan.php/man/WRITE/16/markdown) and the WRITE [SCATTERED(16)](https://www.chedong.com/phpMan.php/man/SCATTERED/16/markdown) cdbs. _DLD_ is between 0 to 7 inclusive with a default of zero. The DLD0 field in [WRITE(16)](https://www.chedong.com/phpMan.php/man/WRITE/16/markdown) and WRITE [SCATTERED(16)](https://www.chedong.com/phpMan.php/man/SCATTERED/16/markdown) is set if (0x1 & _DLD_) is non-zero. The DLD1 field in both cdbs is set if (0x2 & _DLD_) is non-zero. The DLD2 field in both cdbs is set if (0x4 & _DLD_) is non-zero. ### -d --dpo if this option is given then the DPO (disable page out) bit field in the cdb is set. The default is to clear this bit field. Applies to all commands supported by thus utility except WRITE SAME. ### -x --dry-run this option exits (with a status of 0) just before it would otherwise send the se‐ lected SCSI write command. It may still send a SCSI READ CAPACITY command (16 byte variant and perhaps 10 byte variant as well) so the _DEVICE_ is still required. It reads the data in and processes it if the _--in=IF_ and/or the _--scat-file=SF_ options are given. All command line processing and sanity checks (e.g. if the _--strict_ option is given) will be performed and if there is an error then there will be a non zero exit status value. If this option is given twice (e.g. -xx) then instead of performing the selected write SCSI command, the data-out buffer is written to a file called sg_write_x.bin . If it doesn't exist then that file is created in the current directory and is truncated if it previously did exist with longer contents. The data-out buffer is written in binary with some information about it written to stdout. For writes other than scattered the filename and its length in bytes is output to stdout. For write scattered additionally its number of LBA range descriptors and its logical block data offset written to std‐ out. ### -f --fua if this option is given then the FUA (force unit access) bit field in the cdb is set. The default is to clear this bit field. Applies to all commands supported by thus utility except WRITE SAME. ### -G --generation the arguments for this option are used by the [ORWITE(32)](https://www.chedong.com/phpMan.php/man/ORWITE/32/markdown) command only. _EOG_ is placed in the "Expected ORWgeneration" field while _NOG_ is placed in the "New ORWgeneration" field. Both are 32 bits long and default to zero. ### -g --grpnum sets the 'Group number' field to _GN_. Defaults to a value of zero. _GN_ should be a value between 0 and 63. ### -h --help output the usage message then exit. Use multiple times for more help. Currently '-h' to '-hhhh' provide different output. ### -i --in read data (in binary) from a file named _IF_ in a single OS system call (in Unix: [read(2)](https://www.chedong.com/phpMan.php/man/read/2/markdown)). That data is placed in a continuous buffer and then used as the data-out buffer for all SCSI write commands apart from WRITE SCATTERED(16 or 32) which may in‐ clude other data in the data-out buffer. For WRITE SCATTERED (16 or 32) the data-out buffer is made up of 3 or 4 components in this order: a parameter list header (32 zero bytes); zero or more LBA range descriptors, optionally some pad bytes (zeros) and then data to write to the media. For WRITE SCATTERED _IF_ only provides the data to write to the media unless _--combined=DOF_ is given. When the _--combined=DOF_ option is given _IF_ contains all components of the WRITE SCATTERED data-out buffer in binary. The data read from _IF_ starts from byte offset _OFF_ which defaults to zero and no more than _DLEN_ bytes are read from that point (i.e. from the file byte offset _OFF_). If _DLEN_ is zero or not given the rest of the file _IF_ is read. This option is mandatory apart from when --same=1 is given (that sets the NDOB bit which stands for "No Data Out Buffer"). In Unix based OSes, any number of zeros can be produced by using the /dev/zero device file. _IF_ may be "-" which is taken as stdin. In this case the _--offset=OFF,DLEN_ can be given with _OFF_ set to 0 and _LEN_ set to a non-zero value, preferably a multiple of the actual block size. The utility can also deduce how long the _IF_ should be from _NUM_ (or the sum of them in the case of a scatter list). ### -l --lba where the argument is a single Logical Block Address (LBA) or a comma separated list of _LBA_s each of which is the address of the first block written by the selected write command. Only the WRITE SCATTERED command can usefully take more than one _LBA_. What‐ ever number of _LBA_s is given, there needs to be an equal number of _NUM_s given to the _--num=NUM[,NUM...]_ option. The first given _LBA_ joins with the first given _NUM_ to form the first LBA range descriptor (which T10 number from zero in SBC-4). The second _LBA_ joins with the second _LBA_ to form the second LBA range descriptor, etc. A more conve‐ nient way to define a large number of LBA range descriptors is with the _--scat-file=SF_ option. Defaults to logical block 0 (which could be dangerous) while _NUM_ defaults to 0 which makes the combination harmless. _LBA_ is assumed to be in decimal unless prefixed with '0x' or has a trailing 'h'. ### -N --normal the choice of a "normal" WRITE (16 or 32) command can be made explicitly with this op‐ tion. In the absence of selecting any other command (e.g. _--atomic=AB_ ), the choice of a "normal" WRITE is the default. ### -n --num where the argument is a single NUMber of blocks (NUM) or a comma separated list of _NUM_s that pair with the corresponding entries in the _--lba=LBA[,LBA...]_ option. If a _NUM_ is given and is not provided by another method (e.g. by using the _--scat-file=SF_ option) then it defaults to the number of blocks derived from the size of the file named by _IF_ (starting at byte offset _OFF_ to the end or the file or _DLEN_). Apart from the _--combined=DOF_ option, an LBA must be explicitly given (either with _I--lba=LBA_ or via _--scat-file=SF_), if not _NUM_ defaults to 0 as a safety measure. ### -o --offset where _OFF_ is the byte offset within the file named _IF_ to start reading from. The de‐ fault value of _OFF_ is zero which is the beginning of file named _IF_. _DLEN_ is the maxi‐ mum number of bytes to read, starting at byte offset _OFF_, from the file named _IF_. Less bytes will be read if an end of file occurs before _DLEN_ is exhausted. If _DLEN_ is zero or not given then reading from byte offset _OFF_ to the end of the file named _IF_ is as‐ sumed. ### -O --or selects the ORWRITE command. [ORWRITE(16)](https://www.chedong.com/phpMan.php/man/ORWRITE/16/markdown) has similar fields to [WRITE(16)](https://www.chedong.com/phpMan.php/man/WRITE/16/markdown) apart from the WRPROTECT field being named ORPROTECT with slightly different semantics and the absence of the 3 DLD bit fields. [ORWRITE(32)](https://www.chedong.com/phpMan.php/man/ORWRITE/32/markdown) has four extra fields that are set with the _--bmop=OP,PGP_ and _--generation=EOG,NOG_ options. [ORWRITE(32)](https://www.chedong.com/phpMan.php/man/ORWRITE/32/markdown) is the only 32 byte cdb command in this utility that does not require a _DEVICE_ formatted with type 1, 2 or 3 PI (although it will still work if it is formatted with PI). ### -Q --quiet suppress some informational messages such as the ones associated with detected errors when this utility is about to exit. The exit status value is still returned to the op‐ erating system when this utility exits. ### -r --ref-tag where _RT_ is the "expected initial logical block reference tag" field found in the 32 byte cdb variants of WRITE, WRITE ATOMIC, WRITE SAME and WRITE STREAM. The field is also found in the WRITE [SCATTERED(32)](https://www.chedong.com/phpMan.php/man/SCATTERED/32/markdown) LBA range descriptors. It is a 32 bit field which means the maximum value is 0xffffffff. The default value is 0xffffffff. ### -S --same selects the WRITE SAME command with the NDOB field set to _NDOB_ which stands for No Data-Out Buffer. _NDOB_ can take values 0 or 1 (i.e. it is a single bit field). When --same=1 all options associated with the data-out buffer are ignored. ### -q --scat-file where _SF_ is the name of an auxiliary file containing the scatter list for the WRITE SCATTERED command. If the _--scat-raw_ option is also given then _SF_ is assumed to con‐ tain both the parameter list header (32 bytes of zeros) followed by zero or more LBA range descriptors which are also 32 bytes long each. These components are as defined by SBC-4 (i.e. in binary with integers in big endian format). If the _--scat-raw_ op‐ tion is not given then a file of ACSII hexadecimal is expected as described in the SCATTERED FILE ASCII FORMAT section below. If this option is given with the _--combined=DOF_ option then this utility will exit with a syntax error. _SF_ must not be "-", a way of stopping the user trying to redirect stdin. ### -R --scat-raw this option only effects the way that the file named _SF_ from the _--scat-file=SF_ option for WRITE SCATTERED is interpreted. By default (i.e. without this option), _SF_ is parsed as ASCII hexadecimal with blank lines and line contents from and including '#' to the end of line ignored. Hence it can contain comments and other indications. When this option is given, the file named _SF_ is interpreted as binary. As binary it is as‐ sumed to contain 32 bytes of zeros (the WRITE SCATTERED parameter list header) fol‐ lowed by zero or more LBA range descriptors (which are 32 bytes each). If the _--strict_ option is given the reserved field in those two items are checked with any non zero bytes causing an error. ### -S --scattered selects the WRITE SCATTERED command with _RD_ being the number of LBA range descriptors that will be placed in the data-out buffer. If _RD_ is zero then the logic will try and determine the number of range descriptors by other means (e.g. by parsing the file named by _SF_, if there is one). The LBA range descriptors differ between the 16 and 32 byte cdb variants of WRITE SCATTERED. In the 16 byte cdb variant the 32 byte LBA range descriptor is made up of an 8 byte LBA, followed by a 4 byte number_of_blocks followed by 20 bytes of zeros. In the 32 byte variant the LBA and number_of_blocks are followed by a RT (4 bytes), an AT (2 bytes) and a TM (2 bytes) then 12 bytes of zeros. This paragraph applies when _RD_ is greater than zero. If _RD_ is less than the number of LBA range descriptors built from command line options, from the _--scat-file=SF_ option or decoded from _IF_ (when the _--combined=DOF_ option is given) then _RD_ takes precedence; so _RD_ is placed in the "Number of LBA Range Descriptors" field in the cdb. If _RD_ is greater than the number of LBA range descriptors found from the provided data and op‐ tions, then an error is generated. ### -T --stream selects the WRITE STREAM command with the STR_ID field set to _ID_. _ID_ can take values from 0 to 0xffff (i.e. it is a 16 bit field). ### -s --strict when this option is present, more things (e.g. that reserved fields contain zeros) and any irregularities will terminate the utility with a message to stderr and an indica‐ tive exit status. While experimenting with these commands, especially WRITE SCATTERED, it is recommended to use this option. ### -t --tag-mask where _TM_ is the "logical block application tag mask" field found in the 32 byte cdb variants of WRITE, WRITE ATOMIC, WRITE SAME and WRITE STREAM. The field is also found in the WRITE [SCATTERED(32)](https://www.chedong.com/phpMan.php/man/SCATTERED/32/markdown) LBA range descriptors. It is a 16 bit field which means the maximum value is 0xffff. The default value is 0xffff. ### -I --timeout where _TO_ is the command timeout value in seconds. The default value is 120 seconds. If _NUM_ is large on slow media then these WRITE commands may require considerably more time than 120 seconds to complete. ### -u --unmap where _U_A_ is OR-ed bit values used to set the UNMAP and ANCHOR bit fields in the WRITE SAME (16 or 32) cdb. If _U_A_ is 1 then the UNMAP bit field is set; if _U_A_ is 2 then the ANCHOR bit field is set; if _U_A_ is 3 then both the UNMAP and ANCHOR bit fields are set. The default value for both bit fields is clear (0); setting _U_A_ to 0 will also clear both bit fields. ### -v --verbose increase the degree of verbosity (debug messages). These messages are usually written to stderr. ### -V --version output version string then exit. ### -w --wrprotect sets the WRPROTECT field (3 bits) in all sg_write_x commands apart from ORWRITE which has a 3 bit ORPROTECT field (and the synopsis shows _OPR_ to highlight the difference). In all cases _WPR_ is placed in that 3 bit field. The default value is zero which does not send any PI in the data-out buffer. _WPR_ should be a value between 0 and 7. ## SCATTERED FILE ASCII FORMAT All commands in this utility can take a _--scat-file=SF_ and that option can be seen as a re‐ placement for the _--lba=LBA[,LBA...]_ and _--num=NUM[,NUM...]_ options. if both the _--scat-file=SF_ and _--scat-raw_ options are given then the file named _SF_ is expected to be bi‐ nary and contain the parameter list header (32 bytes of zeros for both the 16 and 32 byte variants) followed by zero or more LBA range descriptors, each of 32 bytes each. This section describes what is expected in _SF_ when the _--scat-raw_ option is not given. The ASCII hexadecimal "scatter file" (named by _SF_) can contain comments, empty lines and num‐ bers. If multiple numbers appear on one line they can be separated by spaces, tabs or a sin‐ gle comma. Numbers are parsed as decimal unless prefixed by "0x" (or "0X") or have a suffix of "h". Ox is the prefix of hexadecimal number is the C language while T10 uses the "h" suf‐ fix for the same purpose. Anything from and including a "#" character to the end-of-line is ignored, so comments can be placed there. For the WRITE SCATTERED (16) command, its LBA range descriptors contain two items per de‐ scriptor: an 8 byte LBA followed by a 4 byte number_of_blocks. The remaining 20 bytes of the descriptor are zeros. The format accepted is relatively loose with each decoded value being placed in an LBA and then a number_of_blocks until the end-of-file is reached. The pattern starts with a LBA and if it doesn't finish with a number_of_blocks (i.e. an odd number of values are parsed) an error occurs. So the number of LBA range descriptors generated will be half the number of values parsed in _SF_. For the WRITE SCATTERED (32) command, its LBA range descriptors contain five items per de‐ scriptor: an 8 byte LBA followed by a 4 byte number_of_blocks, then a 4 byte RT, a 2 byte AT, and a 2 byte TM. The last three items are associated with protection information (PI). The accepted format in the _SF_ file is more constrained than the 16 byte cdb variant. The items for each LBA range descriptor must be found on one line with adjacent items being comma sepa‐ rated. The first two items (LBA and number_of_blocks) must be given, and if no more items are on the line then RT, AT and TM are given their default values (all "ff" bytes). Spaces and tabs may appear between items but commas are the separators. Two commas with no value between them will cause the "missing" item to receive its default value. ## NOTES Various numeric arguments (e.g. _LBA_) may include multiplicative suffixes or be given in hexa‐ decimal. See the "NUMERIC ARGUMENTS" section in the [sg3_utils(8)](https://www.chedong.com/phpMan.php/man/sg3utils/8/markdown) man page. In Linux, prior to lk 3.17, the sg driver did not support cdb sizes greater than 16 bytes. Hence a device node like /dev/sg1 which is associated with the sg driver would fail with this utility if the _--32_ option was given (or implied by other options). The bsg driver with de‐ vice nodes like /dev/bsg/6:0:0:1 does support cdb sizes greater than 16 bytes since its in‐ troduction in lk 2.6.28 . ## EXIT STATUS The exit status of sg_write_x is 0 when it is successful. Otherwise see the [sg3_utils(8)](https://www.chedong.com/phpMan.php/man/sg3utils/8/markdown) man page. ## EXAMPLES One simple usage is to write 4 blocks of zeros from (and including) a given LBA according to the rules of WRITE ATOMIC with an atomic boundary of 0. Since no cdb size option is given, the 16 byte cdb will be assumed (i.e. WRITE [ATOMIC(16)](https://www.chedong.com/phpMan.php/man/ATOMIC/16/markdown)): sg_write_x --atomic=0 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc Since _--bs=BS_ has not been given, then this utility will call the READ [CAPACITY(16)](https://www.chedong.com/phpMan.php/man/CAPACITY/16/markdown) command on /dev/sdc to determine the number of bytes in a logical block. If the READ [CAPACITY(16)](https://www.chedong.com/phpMan.php/man/CAPACITY/16/markdown) command fails then the READ [CAPACITY(10)](https://www.chedong.com/phpMan.php/man/CAPACITY/10/markdown) command is tried. Let us assume one of them works and that the number of bytes in each logical block is 512 bytes. So 4 blocks of zeros (each block containing 512 bytes) will be written from (and including) LBA 0x1234 . Now to bypass the need for the READ CAPACITY command(s) the _--bs=BS_ option can be used: sg_write_x --atomic=0 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc Since --bs= is given and its value (512) is a power of 2, then the actual block size is also 512. If instead 520 was given then the logical block size would be 512 (the highest power of 2 less than 520) and the actual block size would be 520 bytes. To send the 32 byte variant add --32 as in: sg_write_x --atomic=0 --32 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc For examples using 'sg_write_x --same=NDOB' see the manpage for [sg_write_same(8)](https://www.chedong.com/phpMan.php/man/sgwritesame/8/markdown). The syntax is a little different but the semantics are the same. To send a WRITE [STREAM(32)](https://www.chedong.com/phpMan.php/man/STREAM/32/markdown) with a STR_ID of 1 use the following: sg_write_x --stream=1 --32 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc Next is a WRITE [SCATTERED(16)](https://www.chedong.com/phpMan.php/man/SCATTERED/16/markdown) command with the scatter list, split between the --lba= and --num= options, on the command line: sg_write_x --scattered=2 --lba=2,0x33 --num=4,1 -i /dev/zero /dev/sg1 Example of a WRITE [SCATTERED(16)](https://www.chedong.com/phpMan.php/man/SCATTERED/16/markdown) command with a degenerate LBA range descriptor (first ele‐ ment to --lba= and --num=): sg_write_x --scattered=2 --lba=0,0x33 --num=0,1 -i /dev/zero /dev/sg1 Example of a WRITE [SCATTERED(16)](https://www.chedong.com/phpMan.php/man/SCATTERED/16/markdown) command with the scatter list in scat_file.txt sg_write_x --scattered=3 -q scat_file.txt -i /dev/zero /dev/sg1 Next a WRITE [SCATTERED(16)](https://www.chedong.com/phpMan.php/man/SCATTERED/16/markdown) command with its scatter list and data in a single file. Note that the argument to --scattered= is 0 so the number of LBA range descriptors is calculated by an‐ alyzing the first two blocks of scat_data.bin (because the argument to --combined= is 2) : sg_write_x --scattered=0 --combined=2 -i scat_data.bin /dev/sg1 When the -xx option is used, a WRITE SCATTERED command is not executed but instead the con‐ tents of the data-out buffer are written to a file called sg_write_x.bin . In the case of WRITE SCATTERED that binary file is suitable for supplying to a later invocation to do the actual write to media. For example: sg_write_x --scattered=3 -q scat_file.txt -xx -i /dev/zero /dev/sg1 Wrote 8192 bytes to sg_write_x.bin, LB data offset: 1 Number of LBA range descriptors: 3 sg_write_x --scattered=0 --combined=1 -i sg_write_x.bin /dev/sg1 Notice when the sg_write_x.bin is written (and nothing is written to the media), a summary of what has happened is sent to stdout. The value shown for "LB data offset:" (1) should be given to the --combined= option when the write to media actually occurs (i.e. the second in‐ vocation shown directly above). ## AUTHORS Written by Douglas Gilbert. ## REPORTING BUGS Report bugs to . ## COPYRIGHT Copyright © 2017-2020 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MER‐ CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. ## SEE ALSO ### sg_readcap,sg_vpd,sg_write_same,sg_stream_ctl(sg3_utils) sg3_utils-1.45 June 2020 [_SG_WRITE_X_(8)](https://www.chedong.com/phpMan.php/man/SGWRITEX/8/markdown)