{ "mode": "man", "parameter": "sg_write_x", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sg_write_x/8/json", "generated": "2026-10-06T02:06:00Z", "synopsis": "sgwritex [--16] [--32] [--app-tag=AT] [--atomic=AB] [--bmop=OP,PGP] [--bs=BS] [--com‐\nbined=DOF] [--dld=DLD] [--dpo] [--dry-run] [--fua] [--generation=EOG,NOG] [--grpnum=GN]\n[--help] --in=IF [--lba=LBA[,LBA...]] [--normal] [--num=NUM[,NUM...]] [--offset=OFF[,DLEN]]\n[--or] [--quiet] [--ref-tag=RT] [--same=NDOB] [--scat-file=SF] [--scat-raw] [--scattered=RD]\n[--stream=ID] [--strict] [--tag-mask=TM] [--timeout=TO] [--unmap=UA] [--verbose] [--version]\n[--wrprotect=WPR] DEVICE\nSynopsis per supported command:\nsgwritex --normal --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dld=DLD] [--dpo]\n[--fua] [--grpnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict]\n[--tag-mask=TM] [--timeout=TO] [--wrprotect=WPR] DEVICE\nsgwritex --or --in=IF [--16] [--32] [--bmop=OP,PGP] [--bs=BS] [--dpo] [--fua] [--genera‐\ntion=EOG,NOG] [--grpnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--strict] [--time‐\nout=TO] [--wrprotect=OPR] DEVICE\nsgwritex --atomic=AB --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dpo] [--fua] [--grp‐\nnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict] [--time‐\nout=TO] [--wrprotect=WPR] DEVICE\nsgwritex --same=NDOB [--16] [--32] [--app-tag=AT] [--bs=BS] [--dpo] [--fua] [--grpnum=GN]\n[--in=IF] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict] [--time‐\nout=TO] [--unmap=UA] [--wrprotect=WPR] DEVICE\nsgwritex --scattered=RD --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dld=DLD] [--dpo]\n[--fua] [--grpnum=GN] [--lba=LBA[,LBA...]] [--num=NUM[,NUM...]] [--offset=OFF[,DLEN]]\n[--ref-tag=RT] [--scat-file=SF] [--scat-raw] [--strict] [--tag-mask=TM] [--timeout=TO] [--wr‐\nprotect=WPR] DEVICE\nsgwritex --stream=ID --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dpo] [--fua] [--grp‐\nnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict]\n[--tag-mask=TM] [--timeout=TO] [--wrprotect=WPR] DEVICE", "sections": { "NAME": { "content": "sgwritex - SCSI WRITE normal/ATOMIC/SAME/SCATTERED/STREAM, ORWRITE commands\n", "subsections": [] }, "SYNOPSIS": { "content": "sgwritex [--16] [--32] [--app-tag=AT] [--atomic=AB] [--bmop=OP,PGP] [--bs=BS] [--com‐\nbined=DOF] [--dld=DLD] [--dpo] [--dry-run] [--fua] [--generation=EOG,NOG] [--grpnum=GN]\n[--help] --in=IF [--lba=LBA[,LBA...]] [--normal] [--num=NUM[,NUM...]] [--offset=OFF[,DLEN]]\n[--or] [--quiet] [--ref-tag=RT] [--same=NDOB] [--scat-file=SF] [--scat-raw] [--scattered=RD]\n[--stream=ID] [--strict] [--tag-mask=TM] [--timeout=TO] [--unmap=UA] [--verbose] [--version]\n[--wrprotect=WPR] DEVICE\n\nSynopsis per supported command:\n\nsgwritex --normal --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dld=DLD] [--dpo]\n[--fua] [--grpnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict]\n[--tag-mask=TM] [--timeout=TO] [--wrprotect=WPR] DEVICE\n\nsgwritex --or --in=IF [--16] [--32] [--bmop=OP,PGP] [--bs=BS] [--dpo] [--fua] [--genera‐\ntion=EOG,NOG] [--grpnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--strict] [--time‐\nout=TO] [--wrprotect=OPR] DEVICE\n\nsgwritex --atomic=AB --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dpo] [--fua] [--grp‐\nnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict] [--time‐\nout=TO] [--wrprotect=WPR] DEVICE\n\nsgwritex --same=NDOB [--16] [--32] [--app-tag=AT] [--bs=BS] [--dpo] [--fua] [--grpnum=GN]\n[--in=IF] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict] [--time‐\nout=TO] [--unmap=UA] [--wrprotect=WPR] DEVICE\n\nsgwritex --scattered=RD --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dld=DLD] [--dpo]\n[--fua] [--grpnum=GN] [--lba=LBA[,LBA...]] [--num=NUM[,NUM...]] [--offset=OFF[,DLEN]]\n[--ref-tag=RT] [--scat-file=SF] [--scat-raw] [--strict] [--tag-mask=TM] [--timeout=TO] [--wr‐\nprotect=WPR] DEVICE\n\nsgwritex --stream=ID --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dpo] [--fua] [--grp‐\nnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict]\n[--tag-mask=TM] [--timeout=TO] [--wrprotect=WPR] DEVICE\n", "subsections": [] }, "DESCRIPTION": { "content": "This utility will send one of six SCSI commands, all associated with writing data to the\ngiven DEVICE. They are a \"normal\" WRITE, ORWRITE, WRITE ATOMIC, WRITE SAME, WRITE SCATTERED\nor WRITE STREAM. This utility supports the 16 and 32 byte variants of all six commands. Hence\nsome closely related commands are not supported (e.g. WRITE(10)). All 32 byte variants, apart\nfrom ORWRITE(32), require the DEVICE to be formatted with type 1, 2 or 3 Protection Informa‐\ntion (PI), making all logical blocks 8 bytes (or a multiple of 8 bytes) longer on the media.\n\nThe command line interface is a little crowded with over thirty options. Hence the SYNOPSIS,\nafter listing all the (long) options, lists those applicable to each supported command. For\neach command synopsis, the option that selects the SCSI command is shown first followed by\nany required options. If no command option is given then a \"normal\" WRITE is assumed. Even\nthough the --scat-file=SF option can be given for every command, it is only shown for WRITE\nSCATTERED where it is most useful. If the --scat-file=SF option is given then neither the\n--lba=LBA[,LBA...] nor the --num=NUM[,NUM...] options should be given. Only the first item of\nthe --lba=LBA[,LBA...] and the --num=NUM[,NUM...] options (or first pair (or quintet) from\nthe --scat-file=SF option) is used for all but the WRITE SCATTERED command. All commands can\ntake --dry-run and --verbose in addition to those shown in the SYNOPSIS.\n\nThe logical block size in bytes can be given explicitly with the --bs=BS option, as long as\nBS is greater than zero. It is typically a power of two, 512 or greater. If the --bs=BS op‐\ntion is not given or BS is zero then the SCSI READ CAPACITY command is used to find the logi‐\ncal block size. First the READ CAPACITY(16) command is tried and if successful the logical\nblock size in the response is typically used as the actual block size for this utility. The\nexception is when PROTEN is set in the response and the --wrprotect=WPR option is given and\nnon-zero; in which case 8 (bytes) is added to the logical block size to yield the actual\nblock size used by this utility. If READ CAPACITY(16) fails then READ CAPACITY(10) is tried\nand if that works then the logical block size in the response is used as the actual block\nsize.\n\nThe number of bytes this utility will attempt to read from the file named by IF is the prod‐\nuct of the actual block size and the numberofblocks (NUM or the sum of NUM arguments). If\nless bytes are read from the file IF and the --strict option is given then this utility exits\nwith an exit status of SGLIBFILEERROR. If less bytes are read from the file IF and the\n--strict option is not given then bytes of zero are substituted for the \"missing\" bytes and\nthis utility continues.\n\nAttempts to write multi megabyte data with a single command are likely to fail for one of\nseveral reasons. First the operating system might object to allocating a buffer that large.\nNext the SCSI pass-through usually limits data blocks to a few megabytes or less. Finally the\nstorage device might have a limited amount of RAM to support a write operation such as atomic\n(as it may need to roll back). The storage device can inform the application client of its\nlimitations via the block limits VPD page (0xb0), with the maximum atomic transfer length\nfield amongst others.\n\nA degenerate LBA (Logical Block Address) range descriptor with no PI has an LBA and NUM of\nzero. A degenerate LBA range descriptor with PI additionally has its RT, AT and TM fields set\nto zero (note: that is not the default values for RT, AT and TM). They are degenerate in the\nsense that they are indistinguishable from a pad of zeros that follow the scatter list in the\ndata-out buffer. SBC-4 makes clear that a degenerate LBA range descriptor is valid. This may\nbecome an issue if RD given in the --scattered=RD option has the value 0. In this case the\nlogic may need to scan the user provided data to calculate the number of LBA range descrip‐\ntors which is required by the WRITE SCATTERED cdb. In the absence of other information the\nlogic will take a degenerate LBA range descriptor as a terminator of the scatter list.\n\nThe current reference for these commands is draft SBC-4 (T10/BSR INCITS 506) revision 15\ndated 9 November 2017. All six SCSI commands are described in that document. WRITE ATOMIC was\nadded in SBC-4 revision 3; WRITE STREAM was added in SBC-4 revision 7; WRITE SCATTERED was\nadded in SBC-4 revision 11 while the others are in the SBC-3 standard.\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": "-6 --16", "content": "send the 16 byte cdb variant of the selected SCSI command. If no command is selected\nthen the (normal) SCSI WRITE(16) command is sent. If neither this option nor the --32\noption is given then this option is assumed.\n", "flag": "-6", "long": "--16" }, { "name": "-3 --32", "content": "send the 32 byte cdb variant of the selected SCSI command. If no command is selected\nthen the (normal) SCSI WRITE(32) command is sent. If neither this option nor the --16\noption is given then then the --16 option is assumed. If both this option and the --16\noption are given then this option takes precedence. Note that apart from ORWRITE(32)\nall other 32 byte cdb variants require a DEVICE formatted with type 1, 2 or 3 protec‐\ntion information.\n", "flag": "-3", "long": "--32" }, { "name": "-a --app-tag", "content": "where AT is the \"expected logical block application tag\" field found in most of the 32\nbyte cdb variants (the exception is ORWRITE(32)). AT is a 16 bit field which means the\nmaximum value is 0xffff. The default value is 0xffff .\n", "flag": "-a", "long": "--app-tag" }, { "name": "-A --atomic", "content": "selects the WRITE ATOMIC command and AB is placed in the Atomic Boundary field of its\ncdb. It is a 16 bit field so the maximum value is 0xffff. If unsure what value to set,\ntry 0 which will attempt to write the whole data-out buffer in a single atomic opera‐\ntion.\n", "flag": "-A", "long": "--atomic" }, { "name": "-B --bmop", "content": "where OP and PGP are the values to be placed in ORWRITE(32)'s BMOP and 'Previous Gen‐\neration Processing' fields respectively. BMOP is a 3 bit field (ranges from 0 to 7)\nand PGP is a 4 bit field (ranges from 0 to 15). Both fields default to 0.\n", "flag": "-B", "long": "--bmop" }, { "name": "-b --bs", "content": "where BS is the logical block size or the actual block size which will be slightly\nbigger. The default value is zero. If this option is not given or is given with a BS\nof zero then the SCSI READ CAPACITY(16) command is sent to DEVICE. If that fails then\nthe READ CAPACITY(10) command is sent. The logical and actual block size will be de‐\nrived from the response of the READ CAPACITY command.\nThis section assumes BS is greater than zero. If BS is less than 512 (bytes) or not a\nmultiple of 8, a warning is issued and the utility continues unless the --strict op‐\ntion is also given. If BS is a power of two (e.g. 512) then the logical and actual\nblock size is set to BS (e.g. 512). If BS is not a power of two (e.g. 520) then the\nlogical block size is set to the closest power of two less than BS (e.g. 512) and the\nactual block size is set to BS (e.g. 520).\nIf the logical and actual block size are different then a later check will reduce the\nactual block size back to the logical block size unless --wrprotect=WPR is greater\nthan zero.\n", "flag": "-b", "long": "--bs" }, { "name": "-c --combined", "content": "This option only applies to WRITE SCATTERED and assumes the whole data-out buffer can\nbe read from IF given by the --in=IF option. The whole data-out buffer is the parame‐\nter list header, followed by zero or more LBA range descriptors, optionally followed\nby some pad bytes and then the data to be written to the media. If the\n--lba=LBA[,LBA...], --num=NUM[,NUM...] or --scat-file=SF options are also given then\nan error is generated. The DOF argument should be the value suitable for the 'Logical\nBlock Data Offset' field in the WRITE SCATTERED cdb. This is the offset in the\ndata-out buffer where the data to write to the media commences. The unit of that field\nis the actual block size which is the logical block size plus a multiple of 8, if pro‐\ntection information (PI) is being sent. When WPR (from --wrprotect=WPR) is greater\nthan zero then PI is expected. SBC-4 revision 15 does not state it but it would appear\nthat a DOF value of 0 is invalid. It is suggested that this option be used with the\n--strict option while experimenting as random or incorrect data fed in via the --in=IF\noption could write a lot of \"interesting\" data all over the DEVICE. If DOF is given\nas 0 the utility will scan the data in IF until RD LBA range descriptors are found; or\nif RD is also 0 until a degenerate LBA range descriptor is found.\n", "flag": "-c", "long": "--combined" }, { "name": "-D --dld", "content": "where DLD is the duration limits descriptor spread across 3 bits in the SCSI WRITE(16)\nand the WRITE SCATTERED(16) cdbs. DLD is between 0 to 7 inclusive with a default of\nzero. The DLD0 field in WRITE(16) and WRITE SCATTERED(16) is set if (0x1 & DLD) is\nnon-zero. The DLD1 field in both cdbs is set if (0x2 & DLD) is non-zero. The DLD2\nfield in both cdbs is set if (0x4 & DLD) is non-zero.\n", "flag": "-D", "long": "--dld" }, { "name": "-d --dpo", "content": "if this option is given then the DPO (disable page out) bit field in the cdb is set.\nThe default is to clear this bit field. Applies to all commands supported by thus\nutility except WRITE SAME.\n", "flag": "-d", "long": "--dpo" }, { "name": "-x --dry-run", "content": "this option exits (with a status of 0) just before it would otherwise send the se‐\nlected SCSI write command. It may still send a SCSI READ CAPACITY command (16 byte\nvariant and perhaps 10 byte variant as well) so the DEVICE is still required. It reads\nthe data in and processes it if the --in=IF and/or the --scat-file=SF options are\ngiven. All command line processing and sanity checks (e.g. if the --strict option is\ngiven) will be performed and if there is an error then there will be a non zero exit\nstatus value.\nIf this option is given twice (e.g. -xx) then instead of performing the selected write\nSCSI command, the data-out buffer is written to a file called sgwritex.bin . If it\ndoesn't exist then that file is created in the current directory and is truncated if\nit previously did exist with longer contents. The data-out buffer is written in binary\nwith some information about it written to stdout. For writes other than scattered the\nfilename and its length in bytes is output to stdout. For write scattered additionally\nits number of LBA range descriptors and its logical block data offset written to std‐\nout.\n", "flag": "-x", "long": "--dry-run" }, { "name": "-f --fua", "content": "if this option is given then the FUA (force unit access) bit field in the cdb is set.\nThe default is to clear this bit field. Applies to all commands supported by thus\nutility except WRITE SAME.\n", "flag": "-f", "long": "--fua" }, { "name": "-G --generation", "content": "the arguments for this option are used by the ORWITE(32) command only. EOG is placed\nin the \"Expected ORWgeneration\" field while NOG is placed in the \"New ORWgeneration\"\nfield. Both are 32 bits long and default to zero.\n", "flag": "-G", "long": "--generation" }, { "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. Use multiple times for more help. Currently '-h'\nto '-hhhh' provide different output.\n", "flag": "-h", "long": "--help" }, { "name": "-i --in", "content": "read data (in binary) from a file named IF in a single OS system call (in Unix:\nread(2)). That data is placed in a continuous buffer and then used as the data-out\nbuffer for all SCSI write commands apart from WRITE SCATTERED(16 or 32) which may in‐\nclude other data in the data-out buffer. For WRITE SCATTERED (16 or 32) the data-out\nbuffer is made up of 3 or 4 components in this order: a parameter list header (32 zero\nbytes); zero or more LBA range descriptors, optionally some pad bytes (zeros) and then\ndata to write to the media. For WRITE SCATTERED IF only provides the data to write to\nthe media unless --combined=DOF is given. When the --combined=DOF option is given IF\ncontains all components of the WRITE SCATTERED data-out buffer in binary. The data\nread from IF starts from byte offset OFF which defaults to zero and no more than DLEN\nbytes are read from that point (i.e. from the file byte offset OFF). If DLEN is zero\nor not given the rest of the file IF is read. This option is mandatory apart from when\n--same=1 is given (that sets the NDOB bit which stands for \"No Data Out Buffer\"). In\nUnix based OSes, any number of zeros can be produced by using the /dev/zero device\nfile.\nIF may be \"-\" which is taken as stdin. In this case the --offset=OFF,DLEN can be given\nwith OFF set to 0 and LEN set to a non-zero value, preferably a multiple of the actual\nblock size. The utility can also deduce how long the IF should be from NUM (or the sum\nof them in the case of a scatter list).\n", "flag": "-i", "long": "--in" }, { "name": "-l --lba", "content": "where the argument is a single Logical Block Address (LBA) or a comma separated list\nof LBAs each of which is the address of the first block written by the selected write\ncommand. Only the WRITE SCATTERED command can usefully take more than one LBA. What‐\never number of LBAs is given, there needs to be an equal number of NUMs given to the\n--num=NUM[,NUM...] option. The first given LBA joins with the first given NUM to form\nthe first LBA range descriptor (which T10 number from zero in SBC-4). The second LBA\njoins with the second LBA to form the second LBA range descriptor, etc. A more conve‐\nnient way to define a large number of LBA range descriptors is with the --scat-file=SF\noption. Defaults to logical block 0 (which could be dangerous) while NUM defaults to 0\nwhich makes the combination harmless. LBA is assumed to be in decimal unless prefixed\nwith '0x' or has a trailing 'h'.\n", "flag": "-l", "long": "--lba" }, { "name": "-N --normal", "content": "the choice of a \"normal\" WRITE (16 or 32) command can be made explicitly with this op‐\ntion. In the absence of selecting any other command (e.g. --atomic=AB ), the choice\nof a \"normal\" WRITE is the default.\n", "flag": "-N", "long": "--normal" }, { "name": "-n --num", "content": "where the argument is a single NUMber of blocks (NUM) or a comma separated list of\nNUMs that pair with the corresponding entries in the --lba=LBA[,LBA...] option. If a\nNUM is given and is not provided by another method (e.g. by using the --scat-file=SF\noption) then it defaults to the number of blocks derived from the size of the file\nnamed by IF (starting at byte offset OFF to the end or the file or DLEN). Apart from\nthe --combined=DOF option, an LBA must be explicitly given (either with I--lba=LBA or\nvia --scat-file=SF), if not NUM defaults to 0 as a safety measure.\n", "flag": "-n", "long": "--num" }, { "name": "-o --offset", "content": "where OFF is the byte offset within the file named IF to start reading from. The de‐\nfault value of OFF is zero which is the beginning of file named IF. DLEN is the maxi‐\nmum number of bytes to read, starting at byte offset OFF, from the file named IF. Less\nbytes will be read if an end of file occurs before DLEN is exhausted. If DLEN is zero\nor not given then reading from byte offset OFF to the end of the file named IF is as‐\nsumed.\n", "flag": "-o", "long": "--offset" }, { "name": "-O --or", "content": "selects the ORWRITE command. ORWRITE(16) has similar fields to WRITE(16) apart from\nthe WRPROTECT field being named ORPROTECT with slightly different semantics and the\nabsence of the 3 DLD bit fields. ORWRITE(32) has four extra fields that are set with\nthe --bmop=OP,PGP and --generation=EOG,NOG options. ORWRITE(32) is the only 32 byte\ncdb command in this utility that does not require a DEVICE formatted with type 1, 2 or\n3 PI (although it will still work if it is formatted with PI).\n", "flag": "-O", "long": "--or" }, { "name": "-Q --quiet", "content": "suppress some informational messages such as the ones associated with detected errors\nwhen this utility is about to exit. The exit status value is still returned to the op‐\nerating system when this utility exits.\n", "flag": "-Q", "long": "--quiet" }, { "name": "-r --ref-tag", "content": "where RT is the \"expected initial logical block reference tag\" field found in the 32\nbyte cdb variants of WRITE, WRITE ATOMIC, WRITE SAME and WRITE STREAM. The field is\nalso found in the WRITE SCATTERED(32) LBA range descriptors. It is a 32 bit field\nwhich means the maximum value is 0xffffffff. The default value is 0xffffffff.\n", "flag": "-r", "long": "--ref-tag" }, { "name": "-S --same", "content": "selects the WRITE SAME command with the NDOB field set to NDOB which stands for No\nData-Out Buffer. NDOB can take values 0 or 1 (i.e. it is a single bit field). When\n--same=1 all options associated with the data-out buffer are ignored.\n", "flag": "-S", "long": "--same" }, { "name": "-q --scat-file", "content": "where SF is the name of an auxiliary file containing the scatter list for the WRITE\nSCATTERED command. If the --scat-raw option is also given then SF is assumed to con‐\ntain both the parameter list header (32 bytes of zeros) followed by zero or more LBA\nrange descriptors which are also 32 bytes long each. These components are as defined\nby SBC-4 (i.e. in binary with integers in big endian format). If the --scat-raw op‐\ntion is not given then a file of ACSII hexadecimal is expected as described in the\nSCATTERED FILE ASCII FORMAT section below.\nIf this option is given with the --combined=DOF option then this utility will exit\nwith a syntax error. SF must not be \"-\", a way of stopping the user trying to redirect\nstdin.\n", "flag": "-q", "long": "--scat-file" }, { "name": "-R --scat-raw", "content": "this option only effects the way that the file named SF from the --scat-file=SF option\nfor WRITE SCATTERED is interpreted. By default (i.e. without this option), SF is\nparsed as ASCII hexadecimal with blank lines and line contents from and including '#'\nto the end of line ignored. Hence it can contain comments and other indications. When\nthis option is given, the file named SF is interpreted as binary. As binary it is as‐\nsumed to contain 32 bytes of zeros (the WRITE SCATTERED parameter list header) fol‐\nlowed by zero or more LBA range descriptors (which are 32 bytes each). If the --strict\noption is given the reserved field in those two items are checked with any non zero\nbytes causing an error.\n", "flag": "-R", "long": "--scat-raw" }, { "name": "-S --scattered", "content": "selects the WRITE SCATTERED command with RD being the number of LBA range descriptors\nthat will be placed in the data-out buffer. If RD is zero then the logic will try and\ndetermine the number of range descriptors by other means (e.g. by parsing the file\nnamed by SF, if there is one). The LBA range descriptors differ between the 16 and 32\nbyte cdb variants of WRITE SCATTERED. In the 16 byte cdb variant the 32 byte LBA range\ndescriptor is made up of an 8 byte LBA, followed by a 4 byte numberofblocks followed\nby 20 bytes of zeros. In the 32 byte variant the LBA and numberofblocks are followed\nby a RT (4 bytes), an AT (2 bytes) and a TM (2 bytes) then 12 bytes of zeros.\nThis paragraph applies when RD is greater than zero. If RD is less than the number of\nLBA range descriptors built from command line options, from the --scat-file=SF option\nor decoded from IF (when the --combined=DOF option is given) then RD takes precedence;\nso RD is placed in the \"Number of LBA Range Descriptors\" field in the cdb. If RD is\ngreater than the number of LBA range descriptors found from the provided data and op‐\ntions, then an error is generated.\n", "flag": "-S", "long": "--scattered" }, { "name": "-T --stream", "content": "selects the WRITE STREAM command with the STRID field set to ID. ID can take values\nfrom 0 to 0xffff (i.e. it is a 16 bit field).\n", "flag": "-T", "long": "--stream" }, { "name": "-s --strict", "content": "when this option is present, more things (e.g. that reserved fields contain zeros) and\nany irregularities will terminate the utility with a message to stderr and an indica‐\ntive exit status. While experimenting with these commands, especially WRITE SCATTERED,\nit is recommended to use this option.\n", "flag": "-s", "long": "--strict" }, { "name": "-t --tag-mask", "content": "where TM is the \"logical block application tag mask\" field found in the 32 byte cdb\nvariants of WRITE, WRITE ATOMIC, WRITE SAME and WRITE STREAM. The field is also found\nin the WRITE SCATTERED(32) LBA range descriptors. It is a 16 bit field which means the\nmaximum value is 0xffff. The default value is 0xffff.\n", "flag": "-t", "long": "--tag-mask" }, { "name": "-I --timeout", "content": "where TO is the command timeout value in seconds. The default value is 120 seconds. If\nNUM is large on slow media then these WRITE commands may require considerably more\ntime than 120 seconds to complete.\n", "flag": "-I", "long": "--timeout" }, { "name": "-u --unmap", "content": "where UA is OR-ed bit values used to set the UNMAP and ANCHOR bit fields in the WRITE\nSAME (16 or 32) cdb. If UA is 1 then the UNMAP bit field is set; if UA is 2 then the\nANCHOR bit field is set; if UA is 3 then both the UNMAP and ANCHOR bit fields are\nset. The default value for both bit fields is clear (0); setting UA to 0 will also\nclear both bit fields.\n", "flag": "-u", "long": "--unmap" }, { "name": "-v --verbose", "content": "increase the degree of verbosity (debug messages). These messages are usually written\nto stderr.\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 WRPROTECT field (3 bits) in all sgwritex commands apart from ORWRITE which\nhas a 3 bit ORPROTECT field (and the synopsis shows OPR to highlight the difference).\nIn all cases WPR is placed in that 3 bit field. The default value is zero which does\nnot send any PI in the data-out buffer. WPR should be a value between 0 and 7.\n", "flag": "-w", "long": "--wrprotect" } ] }, "SCATTERED FILE ASCII FORMAT": { "content": "All commands in this utility can take a --scat-file=SF and that option can be seen as a re‐\nplacement for the --lba=LBA[,LBA...] and --num=NUM[,NUM...] options. if both the\n--scat-file=SF and --scat-raw options are given then the file named SF is expected to be bi‐\nnary and contain the parameter list header (32 bytes of zeros for both the 16 and 32 byte\nvariants) followed by zero or more LBA range descriptors, each of 32 bytes each. This section\ndescribes what is expected in SF when the --scat-raw option is not given.\n\nThe ASCII hexadecimal \"scatter file\" (named by SF) can contain comments, empty lines and num‐\nbers. If multiple numbers appear on one line they can be separated by spaces, tabs or a sin‐\ngle comma. Numbers are parsed as decimal unless prefixed by \"0x\" (or \"0X\") or have a suffix\nof \"h\". Ox is the prefix of hexadecimal number is the C language while T10 uses the \"h\" suf‐\nfix for the same purpose. Anything from and including a \"#\" character to the end-of-line is\nignored, so comments can be placed there.\n\nFor the WRITE SCATTERED (16) command, its LBA range descriptors contain two items per de‐\nscriptor: an 8 byte LBA followed by a 4 byte numberofblocks. The remaining 20 bytes of the\ndescriptor are zeros. The format accepted is relatively loose with each decoded value being\nplaced in an LBA and then a numberofblocks until the end-of-file is reached. The pattern\nstarts with a LBA and if it doesn't finish with a numberofblocks (i.e. an odd number of\nvalues are parsed) an error occurs. So the number of LBA range descriptors generated will be\nhalf the number of values parsed in SF.\n\nFor the WRITE SCATTERED (32) command, its LBA range descriptors contain five items per de‐\nscriptor: an 8 byte LBA followed by a 4 byte numberofblocks, then a 4 byte RT, a 2 byte AT,\nand a 2 byte TM. The last three items are associated with protection information (PI). The\naccepted format in the SF file is more constrained than the 16 byte cdb variant. The items\nfor each LBA range descriptor must be found on one line with adjacent items being comma sepa‐\nrated. The first two items (LBA and numberofblocks) must be given, and if no more items are\non the line then RT, AT and TM are given their default values (all \"ff\" bytes). Spaces and\ntabs may appear between items but commas are the separators. Two commas with no value between\nthem will cause the \"missing\" item to receive its default value.\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 sgwritex is 0 when it is successful. Otherwise see the sg3utils(8) man\npage.\n", "subsections": [] }, "EXAMPLES": { "content": "One simple usage is to write 4 blocks of zeros from (and including) a given LBA according to\nthe rules of WRITE ATOMIC with an atomic boundary of 0. Since no cdb size option is given,\nthe 16 byte cdb will be assumed (i.e. WRITE ATOMIC(16)):\n\nsgwritex --atomic=0 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc\n\nSince --bs=BS has not been given, then this utility will call the READ CAPACITY(16) command\non /dev/sdc to determine the number of bytes in a logical block. If the READ CAPACITY(16)\ncommand fails then the READ CAPACITY(10) command is tried. Let us assume one of them works\nand that the number of bytes in each logical block is 512 bytes. So 4 blocks of zeros (each\nblock containing 512 bytes) will be written from (and including) LBA 0x1234 . Now to bypass\nthe need for the READ CAPACITY command(s) the --bs=BS option can be used:\n\nsgwritex --atomic=0 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc\n\nSince --bs= is given and its value (512) is a power of 2, then the actual block size is also\n512. If instead 520 was given then the logical block size would be 512 (the highest power of\n2 less than 520) and the actual block size would be 520 bytes. To send the 32 byte variant\nadd --32 as in:\n\nsgwritex --atomic=0 --32 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc\n\nFor examples using 'sgwritex --same=NDOB' see the manpage for sgwritesame(8). The syntax\nis a little different but the semantics are the same.\n\nTo send a WRITE STREAM(32) with a STRID of 1 use the following:\n\nsgwritex --stream=1 --32 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc\n\nNext is a WRITE SCATTERED(16) command with the scatter list, split between the --lba= and\n--num= options, on the command line:\n\nsgwritex --scattered=2 --lba=2,0x33 --num=4,1 -i /dev/zero /dev/sg1\n\nExample of a WRITE SCATTERED(16) command with a degenerate LBA range descriptor (first ele‐\nment to --lba= and --num=):\n\nsgwritex --scattered=2 --lba=0,0x33 --num=0,1 -i /dev/zero /dev/sg1\n\nExample of a WRITE SCATTERED(16) command with the scatter list in scatfile.txt\n\nsgwritex --scattered=3 -q scatfile.txt -i /dev/zero /dev/sg1\n\nNext a WRITE SCATTERED(16) command with its scatter list and data in a single file. Note that\nthe argument to --scattered= is 0 so the number of LBA range descriptors is calculated by an‐\nalyzing the first two blocks of scatdata.bin (because the argument to --combined= is 2) :\n\nsgwritex --scattered=0 --combined=2 -i scatdata.bin /dev/sg1\n\nWhen the -xx option is used, a WRITE SCATTERED command is not executed but instead the con‐\ntents of the data-out buffer are written to a file called sgwritex.bin . In the case of\nWRITE SCATTERED that binary file is suitable for supplying to a later invocation to do the\nactual write to media. For example:\n\nsgwritex --scattered=3 -q scatfile.txt -xx -i /dev/zero /dev/sg1\nWrote 8192 bytes to sgwritex.bin, LB data offset: 1\nNumber of LBA range descriptors: 3\nsgwritex --scattered=0 --combined=1 -i sgwritex.bin /dev/sg1\n\nNotice when the sgwritex.bin is written (and nothing is written to the media), a summary of\nwhat has happened is sent to stdout. The value shown for \"LB data offset:\" (1) should be\ngiven to the --combined= option when the write to media actually occurs (i.e. the second in‐\nvocation shown directly above).\n", "subsections": [] }, "AUTHORS": { "content": "Written by Douglas Gilbert.\n", "subsections": [] }, "REPORTING BUGS": { "content": "Report bugs to .\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright © 2017-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": "", "subsections": [ { "name": "sg_readcap,sg_vpd,sg_write_same,sg_stream_ctl(sg3_utils)", "content": "sg3utils-1.45 June 2020 SGWRITEX(8)" } ] } }, "summary": "sgwritex - SCSI WRITE normal/ATOMIC/SAME/SCATTERED/STREAM, ORWRITE commands", "flags": [ { "flag": "-6", "long": "--16", "arg": null, "description": "send the 16 byte cdb variant of the selected SCSI command. If no command is selected then the (normal) SCSI WRITE(16) command is sent. If neither this option nor the --32 option is given then this option is assumed." }, { "flag": "-3", "long": "--32", "arg": null, "description": "send the 32 byte cdb variant of the selected SCSI command. If no command is selected then the (normal) SCSI WRITE(32) 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) all other 32 byte cdb variants require a DEVICE formatted with type 1, 2 or 3 protec‐ tion information." }, { "flag": "-a", "long": "--app-tag", "arg": null, "description": "where AT is the \"expected logical block application tag\" field found in most of the 32 byte cdb variants (the exception is ORWRITE(32)). AT is a 16 bit field which means the maximum value is 0xffff. The default value is 0xffff ." }, { "flag": "-A", "long": "--atomic", "arg": null, "description": "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." }, { "flag": "-B", "long": "--bmop", "arg": null, "description": "where OP and PGP are the values to be placed in ORWRITE(32)'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." }, { "flag": "-b", "long": "--bs", "arg": null, "description": "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) command is sent to DEVICE. If that fails then the READ CAPACITY(10) 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." }, { "flag": "-c", "long": "--combined", "arg": null, "description": "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." }, { "flag": "-D", "long": "--dld", "arg": null, "description": "where DLD is the duration limits descriptor spread across 3 bits in the SCSI WRITE(16) and the WRITE SCATTERED(16) cdbs. DLD is between 0 to 7 inclusive with a default of zero. The DLD0 field in WRITE(16) and WRITE SCATTERED(16) 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." }, { "flag": "-d", "long": "--dpo", "arg": null, "description": "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." }, { "flag": "-x", "long": "--dry-run", "arg": null, "description": "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 sgwritex.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." }, { "flag": "-f", "long": "--fua", "arg": null, "description": "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." }, { "flag": "-G", "long": "--generation", "arg": null, "description": "the arguments for this option are used by the ORWITE(32) 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." }, { "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. Use multiple times for more help. Currently '-h' to '-hhhh' provide different output." }, { "flag": "-i", "long": "--in", "arg": null, "description": "read data (in binary) from a file named IF in a single OS system call (in Unix: read(2)). 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)." }, { "flag": "-l", "long": "--lba", "arg": null, "description": "where the argument is a single Logical Block Address (LBA) or a comma separated list of LBAs 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 LBAs is given, there needs to be an equal number of NUMs 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'." }, { "flag": "-N", "long": "--normal", "arg": null, "description": "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." }, { "flag": "-n", "long": "--num", "arg": null, "description": "where the argument is a single NUMber of blocks (NUM) or a comma separated list of NUMs 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." }, { "flag": "-o", "long": "--offset", "arg": null, "description": "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." }, { "flag": "-O", "long": "--or", "arg": null, "description": "selects the ORWRITE command. ORWRITE(16) has similar fields to WRITE(16) apart from the WRPROTECT field being named ORPROTECT with slightly different semantics and the absence of the 3 DLD bit fields. ORWRITE(32) has four extra fields that are set with the --bmop=OP,PGP and --generation=EOG,NOG options. ORWRITE(32) 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)." }, { "flag": "-Q", "long": "--quiet", "arg": null, "description": "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." }, { "flag": "-r", "long": "--ref-tag", "arg": null, "description": "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) LBA range descriptors. It is a 32 bit field which means the maximum value is 0xffffffff. The default value is 0xffffffff." }, { "flag": "-S", "long": "--same", "arg": null, "description": "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." }, { "flag": "-q", "long": "--scat-file", "arg": null, "description": "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." }, { "flag": "-R", "long": "--scat-raw", "arg": null, "description": "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." }, { "flag": "-S", "long": "--scattered", "arg": null, "description": "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 numberofblocks followed by 20 bytes of zeros. In the 32 byte variant the LBA and numberofblocks 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." }, { "flag": "-T", "long": "--stream", "arg": null, "description": "selects the WRITE STREAM command with the STRID field set to ID. ID can take values from 0 to 0xffff (i.e. it is a 16 bit field)." }, { "flag": "-s", "long": "--strict", "arg": null, "description": "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." }, { "flag": "-t", "long": "--tag-mask", "arg": null, "description": "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) LBA range descriptors. It is a 16 bit field which means the maximum value is 0xffff. The default value is 0xffff." }, { "flag": "-I", "long": "--timeout", "arg": null, "description": "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." }, { "flag": "-u", "long": "--unmap", "arg": null, "description": "where UA is OR-ed bit values used to set the UNMAP and ANCHOR bit fields in the WRITE SAME (16 or 32) cdb. If UA is 1 then the UNMAP bit field is set; if UA is 2 then the ANCHOR bit field is set; if UA is 3 then both the UNMAP and ANCHOR bit fields are set. The default value for both bit fields is clear (0); setting UA to 0 will also clear both bit fields." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "increase the degree of verbosity (debug messages). These messages are usually written to stderr." }, { "flag": "-V", "long": "--version", "arg": null, "description": "output version string then exit." }, { "flag": "-w", "long": "--wrprotect", "arg": null, "description": "sets the WRPROTECT field (3 bits) in all sgwritex 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." } ], "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)):", "sgwritex --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) command", "on /dev/sdc to determine the number of bytes in a logical block. If the READ CAPACITY(16)", "command fails then the READ CAPACITY(10) 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:", "sgwritex --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:", "sgwritex --atomic=0 --32 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc", "For examples using 'sgwritex --same=NDOB' see the manpage for sgwritesame(8). The syntax", "is a little different but the semantics are the same.", "To send a WRITE STREAM(32) with a STRID of 1 use the following:", "sgwritex --stream=1 --32 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc", "Next is a WRITE SCATTERED(16) command with the scatter list, split between the --lba= and", "--num= options, on the command line:", "sgwritex --scattered=2 --lba=2,0x33 --num=4,1 -i /dev/zero /dev/sg1", "Example of a WRITE SCATTERED(16) command with a degenerate LBA range descriptor (first ele‐", "ment to --lba= and --num=):", "sgwritex --scattered=2 --lba=0,0x33 --num=0,1 -i /dev/zero /dev/sg1", "Example of a WRITE SCATTERED(16) command with the scatter list in scatfile.txt", "sgwritex --scattered=3 -q scatfile.txt -i /dev/zero /dev/sg1", "Next a WRITE SCATTERED(16) 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 scatdata.bin (because the argument to --combined= is 2) :", "sgwritex --scattered=0 --combined=2 -i scatdata.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 sgwritex.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:", "sgwritex --scattered=3 -q scatfile.txt -xx -i /dev/zero /dev/sg1", "Wrote 8192 bytes to sgwritex.bin, LB data offset: 1", "Number of LBA range descriptors: 3", "sgwritex --scattered=0 --combined=1 -i sgwritex.bin /dev/sg1", "Notice when the sgwritex.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)." ], "see_also": [] }