1SG_WRITE_X(8)                      SG3_UTILS                     SG_WRITE_X(8)
2
3
4

NAME

6       sg_write_x  -  SCSI  WRITE normal/ATOMIC/SAME/SCATTERED/STREAM, ORWRITE
7       commands
8

SYNOPSIS

10       sg_write_x [--16] [--32] [--app-tag=AT]  [--atomic=AB]  [--bmop=OP,PGP]
11       [--bs=BS]  [--combined=DOF]  [--dld=DLD]  [--dpo]  [--dry-run]  [--fua]
12       [--generation=EOG,NOG]       [--grpnum=GN]       [--help]       --in=IF
13       [--lba=LBA[,LBA...]]     [--normal]     [--num=NUM[,NUM...]]    [--off‐
14       set=OFF[,DLEN]]   [--or]   [--quiet]    [--ref-tag=RT]    [--same=NDOB]
15       [--scat-file=SF] [--scat-raw] [--scattered=RD] [--stream=ID] [--strict]
16       [--tag-mask=TM] [--timeout=TO]  [--unmap=U_A]  [--verbose]  [--version]
17       [--wrprotect=WPR] DEVICE
18
19       Synopsis per supported command:
20
21       sg_write_x  --normal  --in=IF  [--16]  [--32]  [--app-tag=AT] [--bs=BS]
22       [--dld=DLD]  [--dpo]  [--fua]  [--grpnum=GN]  [--lba=LBA]   [--num=NUM]
23       [--offset=OFF[,DLEN]]    [--ref-tag=RT]    [--strict]   [--tag-mask=TM]
24       [--timeout=TO] [--wrprotect=WPR] DEVICE
25
26       sg_write_x --or --in=IF [--16] [--32] [--bmop=OP,PGP] [--bs=BS] [--dpo]
27       [--fua]  [--generation=EOG,NOG]  [--grpnum=GN]  [--lba=LBA] [--num=NUM]
28       [--offset=OFF[,DLEN]]   [--strict]   [--timeout=TO]   [--wrprotect=OPR]
29       DEVICE
30
31       sg_write_x  --atomic=AB  --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS]
32       [--dpo]   [--fua]   [--grpnum=GN]   [--lba=LBA]   [--num=NUM]   [--off‐
33       set=OFF[,DLEN]]   [--ref-tag=RT]  [--strict]  [--timeout=TO]  [--wrpro‐
34       tect=WPR] DEVICE
35
36       sg_write_x --same=NDOB [--16] [--32] [--app-tag=AT]  [--bs=BS]  [--dpo]
37       [--fua]   [--grpnum=GN]   [--in=IF]   [--lba=LBA]  [--num=NUM]  [--off‐
38       set=OFF[,DLEN]] [--ref-tag=RT] [--strict] [--timeout=TO]  [--unmap=U_A]
39       [--wrprotect=WPR] DEVICE
40
41       sg_write_x   --scattered=RD   --in=IF   [--16]   [--32]  [--app-tag=AT]
42       [--bs=BS]      [--dld=DLD]      [--dpo]      [--fua]      [--grpnum=GN]
43       [--lba=LBA[,LBA...]]      [--num=NUM[,NUM...]]    [--offset=OFF[,DLEN]]
44       [--ref-tag=RT] [--scat-file=SF] [--scat-raw] [--strict] [--tag-mask=TM]
45       [--timeout=TO] [--wrprotect=WPR] DEVICE
46
47       sg_write_x  --stream=ID  --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS]
48       [--dpo]   [--fua]   [--grpnum=GN]   [--lba=LBA]   [--num=NUM]   [--off‐
49       set=OFF[,DLEN]]   [--ref-tag=RT]  [--strict]  [--tag-mask=TM]  [--time‐
50       out=TO] [--wrprotect=WPR] DEVICE
51

DESCRIPTION

53       This utility will send one of six SCSI commands,  all  associated  with
54       writing  data  to the given DEVICE. They are a "normal" WRITE, ORWRITE,
55       WRITE ATOMIC, WRITE SAME, WRITE SCATTERED or WRITE STREAM. This utility
56       supports  the  16  and 32 byte variants of all six commands. Hence some
57       closely related commands are not supported  (e.g.  WRITE(10)).  All  32
58       byte variants, apart from ORWRITE(32), require the DEVICE to be format‐
59       ted with type 1, 2 or 3 Protection Information (PI), making all logical
60       blocks 8 bytes (or a multiple of 8 bytes) longer on the media.
61
62       The  command  line  interface  is  a  little  crowded  with over thirty
63       options. Hence the SYNOPSIS, after  listing  all  the  (long)  options,
64       lists those applicable to each supported command. For each command syn‐
65       opsis, the option that selects the SCSI command is shown first followed
66       by  any required options. If no command option is given then a "normal"
67       WRITE is assumed. Even though the --scat-file=SF option  can  be  given
68       for  every  command,  it  is only shown for WRITE SCATTERED where it is
69       most useful. If the --scat-file=SF option is  given  then  neither  the
70       --lba=LBA[,LBA...]  nor the --num=NUM[,NUM...] options should be given.
71       Only   the   first   item   of   the   --lba=LBA[,LBA...]    and    the
72       --num=NUM[,NUM...]  options  (or  first  pair  (or  quintet)  from  the
73       --scat-file=SF option) is used for all but the WRITE SCATTERED command.
74       All  commands  can  take  --dry-run  and --verbose in addition to those
75       shown in the SYNOPSIS.
76
77       The logical block size in  bytes  can  be  given  explicitly  with  the
78       --bs=BS  option,  as long as BS is greater than zero. It is typically a
79       power of two, 512 or greater. If the --bs=BS option is not given or  BS
80       is zero then the SCSI READ CAPACITY command is used to find the logical
81       block size. First the READ CAPACITY(16) command is tried  and  if  suc‐
82       cessful the logical block size in the response is typically used as the
83       actual block size for this utility. The exception is  when  PROT_EN  is
84       set  in  the  response  and  the  --wrprotect=WPR  option  is given and
85       non-zero; in which case 8 (bytes) is added to the logical block size to
86       yield  the actual block size used by this utility. If READ CAPACITY(16)
87       fails then READ CAPACITY(10) is tried and if that works then the  logi‐
88       cal block size in the response is used as the actual block size.
89
90       The  number  of  bytes  this utility will attempt to read from the file
91       named by IF is the product of  the  actual  block  size  and  the  num‐
92       ber_of_blocks (NUM or the sum of NUM arguments). If less bytes are read
93       from the file IF and the --strict option is  given  then  this  utility
94       exits  with an exit status of SG_LIB_FILE_ERROR. If less bytes are read
95       from the file IF and the --strict option is not  given  then  bytes  of
96       zero  are  substituted for the "missing" bytes and this utility contin‐
97       ues.
98
99       Attempts to write multi megabyte data with a single command are  likely
100       to  fail  for  one of several reasons. First the operating system might
101       object to allocating a buffer that large. Next  the  SCSI  pass-through
102       usually  limits  data  blocks  to  a few megabytes or less. Finally the
103       storage device might have a limited amount of RAM to  support  a  write
104       operation  such  as  atomic  (as it may need to roll back). The storage
105       device can inform the application client of  its  limitations  via  the
106       block  limits  VPD page (0xb0), with the maximum atomic transfer length
107       field amongst others.
108
109       A degenerate LBA (Logical Block Address) range descriptor  with  no  PI
110       has  an  LBA and NUM of zero. A degenerate LBA range descriptor with PI
111       additionally has its RT, AT and TM fields set to zero  (note:  that  is
112       not  the  default values for RT, AT and TM). They are degenerate in the
113       sense that they are indistinguishable from a pad of zeros  that  follow
114       the  scatter  list  in  the  data-out  buffer. SBC-4 makes clear that a
115       degenerate LBA range descriptor is valid. This may become an  issue  if
116       RD given in the --scattered=RD option has the value 0. In this case the
117       logic may need to scan the user provided data to calculate  the  number
118       of  LBA range descriptors which is required by the WRITE SCATTERED cdb.
119       In the absence of other information the logic will  take  a  degenerate
120       LBA range descriptor as a terminator of the scatter list.
121
122       The current reference for these commands is draft SBC-4 (T10/BSR INCITS
123       506) revision 15 dated 9 November  2017.  All  six  SCSI  commands  are
124       described in that document. WRITE ATOMIC was added in SBC-4 revision 3;
125       WRITE STREAM was added in SBC-4 revision 7; WRITE SCATTERED  was  added
126       in SBC-4 revision 11 while the others are in the SBC-3 standard.
127

OPTIONS

129       Arguments to long options are mandatory for short options as well.  The
130       options are arranged in alphabetical order based  on  the  long  option
131       name.
132
133       -6, --16
134              send the 16 byte cdb variant of the selected SCSI command. If no
135              command is selected then the (normal) SCSI WRITE(16) command  is
136              sent.  If  neither this option nor the --32 option is given then
137              this option is assumed.
138
139       -3, --32
140              send the 32 byte cdb variant of the selected SCSI command. If no
141              command  is selected then the (normal) SCSI WRITE(32) command is
142              sent. If neither this option nor the --16 option is  given  then
143              then  the  --16  option  is assumed. If both this option and the
144              --16 option are given then this option  takes  precedence.  Note
145              that  apart  from  ORWRITE(32)  all  other  32 byte cdb variants
146              require a DEVICE formatted with type 1, 2 or 3 protection infor‐
147              mation.
148
149       -a, --app-tag=AT
150              where  AT  is the "expected logical block application tag" field
151              found in most of the 32 byte  cdb  variants  (the  exception  is
152              ORWRITE(32)). AT is a 16 bit field which means the maximum value
153              is 0xffff. The default value is 0xffff .
154
155       -A, --atomic=AB
156              selects the WRITE ATOMIC command and AB is placed in the  Atomic
157              Boundary  field  of its cdb. It is a 16 bit field so the maximum
158              value is 0xffff. If unsure what value to set, try 0  which  will
159              attempt  to  write  the whole data-out buffer in a single atomic
160              operation.
161
162       -B, --bmop=OP,PGP
163              where OP and PGP are the values to be  placed  in  ORWRITE(32)'s
164              BMOP  and  'Previous Generation Processing' fields respectively.
165              BMOP is a 3 bit field (ranges from 0 to 7) and PGP is  a  4  bit
166              field (ranges from 0 to 15). Both fields default to 0.
167
168       -b, --bs=BS
169              where  BS  is  the  logical  block size or the actual block size
170              which will be slightly bigger. The default  value  is  zero.  If
171              this  option is not given or is given with a BS of zero then the
172              SCSI READ CAPACITY(16) command is sent to DEVICE. If that  fails
173              then  the  READ  CAPACITY(10)  command  is sent. The logical and
174              actual block size will be derived from the response of the  READ
175              CAPACITY command.
176              This section assumes BS is greater than zero. If BS is less than
177              512 (bytes) or not a multiple of 8, a warning is issued and  the
178              utility  continues  unless the --strict option is also given. If
179              BS is a power of two (e.g. 512)  then  the  logical  and  actual
180              block  size is set to BS (e.g. 512). If BS is not a power of two
181              (e.g. 520) then the logical block size is  set  to  the  closest
182              power  of  two less than BS (e.g. 512) and the actual block size
183              is set to BS (e.g.  520).
184              If the logical and actual block size are different then a  later
185              check  will  reduce  the  actual  block size back to the logical
186              block size unless --wrprotect=WPR is greater than zero.
187
188       -c, --combined=DOF
189              This option only applies to  WRITE  SCATTERED  and  assumes  the
190              whole  data-out  buffer can be read from IF given by the --in=IF
191              option. The whole data-out buffer is the parameter list  header,
192              followed  by zero or more LBA range descriptors, optionally fol‐
193              lowed by some pad bytes and then the data to be written  to  the
194              media.   If   the   --lba=LBA[,LBA...],   --num=NUM[,NUM...]  or
195              --scat-file=SF options are also given then an  error  is  gener‐
196              ated.  The  DOF  argument  should  be the value suitable for the
197              'Logical Block Data Offset' field in the  WRITE  SCATTERED  cdb.
198              This  is  the  offset  in  the data-out buffer where the data to
199              write to the media commences. The unit  of  that  field  is  the
200              actual  block size which is the logical block size plus a multi‐
201              ple of 8, if protection information (PI) is being sent. When WPR
202              (from --wrprotect=WPR) is greater than zero then PI is expected.
203              SBC-4 revision 15 does not state it but it would appear  that  a
204              DOF  value  of 0 is invalid. It is suggested that this option be
205              used with the --strict option while experimenting as  random  or
206              incorrect  data  fed in via the --in=IF option could write a lot
207              of "interesting" data all over the DEVICE.  If DOF is given as 0
208              the utility will scan the data in IF until RD LBA range descrip‐
209              tors are found; or if RD is also 0 until a degenerate LBA  range
210              descriptor is found.
211
212       -D, --dld=DLD
213              where DLD is the duration limits descriptor spread across 3 bits
214              in the SCSI WRITE(16) and the WRITE SCATTERED(16) cdbs.  DLD  is
215              between  0 to 7 inclusive with a default of zero. The DLD0 field
216              in WRITE(16) and WRITE SCATTERED(16) is set if (0x1  &  DLD)  is
217              non-zero.  The  DLD1 field in both cdbs is set if (0x2 & DLD) is
218              non-zero. The DLD2 field in both cdbs is set if (0x4 &  DLD)  is
219              non-zero.
220
221       -d, --dpo
222              if  this  option  is  given  then the DPO (disable page out) bit
223              field in the cdb is set. The default is to clear this bit field.
224              Applies  to  all commands supported by thus utility except WRITE
225              SAME.
226
227       -x, --dry-run
228              this option exits (with a status of 0) just before it would oth‐
229              erwise send the selected SCSI write command. It may still send a
230              SCSI READ CAPACITY command (16 byte variant and perhaps 10  byte
231              variant  as  well) so the DEVICE is still required. It reads the
232              data  in  and  processes  it   if   the   --in=IF   and/or   the
233              --scat-file=SF  options  are  given. All command line processing
234              and sanity checks (e.g. if the --strict option is given) will be
235              performed and if there is an error then there will be a non zero
236              exit status value.
237              If this option is given twice (e.g. -xx) then  instead  of  per‐
238              forming  the selected write SCSI command, the data-out buffer is
239              written to a file called sg_write_x.bin . If  it  doesn't  exist
240              then  that file is created in the current directory and is trun‐
241              cated if it previously  did  exist  with  longer  contents.  The
242              data-out buffer is written in binary with some information about
243              it written to stdout. For writes other than scattered the  file‐
244              name  and  its  length  in  bytes is output to stdout. For write
245              scattered additionally its number of LBA range  descriptors  and
246              its logical block data offset written to stdout.
247
248       -f, --fua
249              if  this  option  is  given then the FUA (force unit access) bit
250              field in the cdb is set. The default is to clear this bit field.
251              Applies  to  all commands supported by thus utility except WRITE
252              SAME.
253
254       -G, --generation=EOG,NOG
255              the arguments for this option are used by the ORWITE(32) command
256              only.  EOG is placed in the "Expected ORWgeneration" field while
257              NOG is placed in the "New ORWgeneration" field. Both are 32 bits
258              long and default to zero.
259
260       -g, --grpnum=GN
261              sets  the  'Group  number'  field  to GN. Defaults to a value of
262              zero.  GN should be a value between 0 and 63.
263
264       -h, --help
265              output the usage message then exit. Use multiple times for  more
266              help.  Currently '-h' to '-hhhh' provide different output.
267
268       -i, --in=IF
269              read data (in binary) from a file named IF in a single OS system
270              call (in Unix: read(2)). That data is  placed  in  a  continuous
271              buffer  and  then used as the data-out buffer for all SCSI write
272              commands apart from WRITE SCATTERED(16 or 32) which may  include
273              other  data  in the data-out buffer.  For WRITE SCATTERED (16 or
274              32) the data-out buffer is made up of 3 or 4 components in  this
275              order: a parameter list header (32 zero bytes); zero or more LBA
276              range descriptors, optionally some pad bytes  (zeros)  and  then
277              data to write to the media. For WRITE SCATTERED IF only provides
278              the data to write to the media unless --combined=DOF  is  given.
279              When  the  --combined=DOF option is given IF contains all compo‐
280              nents of the WRITE SCATTERED data-out buffer in binary. The data
281              read  from IF starts from byte offset OFF which defaults to zero
282              and no more than DLEN bytes are read from that point (i.e.  from
283              the file byte offset OFF). If DLEN is zero or not given the rest
284              of the file IF is read. This option is mandatory apart from when
285              --same=1  is  given (that sets the NDOB bit which stands for "No
286              Data Out Buffer"). In Unix based OSes, any number of  zeros  can
287              be produced by using the /dev/zero device file.
288              IF  may  be "-" which is taken as stdin. In this case the --off‐
289              set=OFF,DLEN can be given with OFF set to 0 and  LEN  set  to  a
290              non-zero  value, preferably a multiple of the actual block size.
291              The utility can also deduce how long the IF should be  from  NUM
292              (or the sum of them in the case of a scatter list).
293
294       -l, --lba=LBA[,LBA...]
295              where  the argument is a single Logical Block Address (LBA) or a
296              comma separated list of LBAs each of which is the address of the
297              first  block  written  by  the  selected write command. Only the
298              WRITE SCATTERED command can usefully take  more  than  one  LBA.
299              Whatever  number  of  LBAs  is given, there needs to be an equal
300              number of NUMs given to the --num=NUM[,NUM...] option. The first
301              given  LBA  joins with the first given NUM to form the first LBA
302              range descriptor (which T10 number from zero in SBC-4). The sec‐
303              ond  LBA  joins with the second LBA to form the second LBA range
304              descriptor, etc. A more convenient way to define a large  number
305              of  LBA  range  descriptors  is  with the --scat-file=SF option.
306              Defaults to logical block 0 (which could be dangerous) while NUM
307              defaults  to  0  which  makes  the combination harmless.  LBA is
308              assumed to be in decimal unless prefixed  with  '0x'  or  has  a
309              trailing 'h'.
310
311       -N, --normal
312              the  choice  of  a "normal" WRITE (16 or 32) command can be made
313              explicitly with this option. In the  absence  of  selecting  any
314              other  command  (e.g.   --atomic=AB  ), the choice of a "normal"
315              WRITE is the default.
316
317       -n, --num=NUM[,NUM...]
318              where the argument is a single NUMber of blocks (NUM) or a comma
319              separated  list of NUMs that pair with the corresponding entries
320              in the --lba=LBA[,LBA...] option. If a NUM is given and  is  not
321              provided  by  another  method  (e.g. by using the --scat-file=SF
322              option) then it defaults to the number of  blocks  derived  from
323              the size of the file named by IF (starting at byte offset OFF to
324              the end or the file or  DLEN).  Apart  from  the  --combined=DOF
325              option,  an LBA must be explicitly given (either with I--lba=LBA
326              or via --scat-file=SF), if not NUM defaults to  0  as  a  safety
327              measure.
328
329       -o, --offset=OFF[,DLEN]
330              where  OFF  is the byte offset within the file named IF to start
331              reading from. The default value of OFF  is  zero  which  is  the
332              beginning  of file named IF. DLEN is the maximum number of bytes
333              to read, starting at byte offset OFF, from the  file  named  IF.
334              Less  bytes will be read if an end of file occurs before DLEN is
335              exhausted. If DLEN is zero or not given then reading  from  byte
336              offset OFF to the end of the file named IF is assumed.
337
338       -O, --or
339              selects  the  ORWRITE command. ORWRITE(16) has similar fields to
340              WRITE(16) apart from the WRPROTECT field being  named  ORPROTECT
341              with  slightly  different semantics and the absence of the 3 DLD
342              bit fields. ORWRITE(32) has four extra fields that are set  with
343              the  --bmop=OP,PGP and --generation=EOG,NOG options. ORWRITE(32)
344              is the only 32 byte cdb command in this utility  that  does  not
345              require  a  DEVICE formatted with type 1, 2 or 3 PI (although it
346              will still work if it is formatted with PI).
347
348       -Q, --quiet
349              suppress some informational messages such as the ones associated
350              with  detected  errors  when  this utility is about to exit. The
351              exit status value is still returned to the operating system when
352              this utility exits.
353
354       -r, --ref-tag=RT
355              where  RT  is the "expected initial logical block reference tag"
356              field found in the 32 byte cdb variants of WRITE, WRITE  ATOMIC,
357              WRITE  SAME  and  WRITE  STREAM.  The field is also found in the
358              WRITE SCATTERED(32) LBA range descriptors. It is a 32 bit  field
359              which  means  the maximum value is 0xffffffff. The default value
360              is 0xffffffff.
361
362       -S, --same=NDOB
363              selects the WRITE SAME command with the NDOB field set  to  NDOB
364              which stands for No Data-Out Buffer. NDOB can take values 0 or 1
365              (i.e. it is a single bit field). When --same=1 all options asso‐
366              ciated with the data-out buffer are ignored.
367
368       -q, --scat-file=SF
369              where SF is the name of an auxiliary file containing the scatter
370              list for the WRITE SCATTERED command. If the  --scat-raw  option
371              is  also  given then SF is assumed to contain both the parameter
372              list header (32 bytes of zeros) followed by  zero  or  more  LBA
373              range  descriptors which are also 32 bytes long each. These com‐
374              ponents are as defined by SBC-4 (i.e.  in binary  with  integers
375              in  big  endian  format).  If the --scat-raw option is not given
376              then a file of ACSII hexadecimal is expected as described in the
377              SCATTERED FILE ASCII FORMAT section below.
378              If this option is given with the --combined=DOF option then this
379              utility will exit with a syntax error. SF must not be "-", a way
380              of stopping the user trying to redirect stdin.
381
382       -R, --scat-raw
383              this option only effects the way that the file named SF from the
384              --scat-file=SF option for WRITE  SCATTERED  is  interpreted.  By
385              default  (i.e. without this option), SF is parsed as ASCII hexa‐
386              decimal with blank lines and line contents  from  and  including
387              '#'  to  the  end of line ignored. Hence it can contain comments
388              and other indications. When this option is given, the file named
389              SF is interpreted as binary.  As binary it is assumed to contain
390              32 bytes of zeros (the WRITE SCATTERED  parameter  list  header)
391              followed  by  zero  or  more LBA range descriptors (which are 32
392              bytes each). If the --strict option is given the reserved  field
393              in  those  two items are checked with any non zero bytes causing
394              an error.
395
396       -S, --scattered=RD
397              selects the WRITE SCATTERED command with RD being the number  of
398              LBA  range  descriptors that will be placed in the data-out buf‐
399              fer. If RD is zero then the logic will  try  and  determine  the
400              number  of range descriptors by other means (e.g. by parsing the
401              file named by SF, if there is one).  The LBA  range  descriptors
402              differ  between  the  16 and 32 byte cdb variants of WRITE SCAT‐
403              TERED. In the 16 byte cdb variant the 32 byte LBA range descrip‐
404              tor  is  made  up  of  an  8 byte LBA, followed by a 4 byte num‐
405              ber_of_blocks followed by 20 bytes of  zeros.  In  the  32  byte
406              variant  the  LBA  and  number_of_blocks are followed by a RT (4
407              bytes), an AT (2 bytes) and a TM (2  bytes)  then  12  bytes  of
408              zeros.
409              This  paragraph  applies when RD is greater than zero.  If RD is
410              less than the number of LBA range descriptors built from command
411              line  options, from the --scat-file=SF option or decoded from IF
412              (when the --combined=DOF option is given) then RD  takes  prece‐
413              dence;  so RD is placed in the "Number of LBA Range Descriptors"
414              field in the cdb. If RD is greater than the number of LBA  range
415              descriptors  found  from  the provided data and options, then an
416              error is generated.
417
418       -T, --stream=ID
419              selects the WRITE STREAM command with the STR_ID  field  set  to
420              ID.   ID  can  take values from 0 to 0xffff (i.e. it is a 16 bit
421              field).
422
423       -s, --strict
424              when this option is present, more  things  (e.g.  that  reserved
425              fields  contain zeros) and any irregularities will terminate the
426              utility with a message to stderr and an indicative exit  status.
427              While  experimenting with these commands, especially WRITE SCAT‐
428              TERED, it is recommended to use this option.
429
430       -t, --tag-mask=TM
431              where TM is the  "logical  block  application  tag  mask"  field
432              found  in the 32 byte cdb variants of WRITE, WRITE ATOMIC, WRITE
433              SAME and WRITE STREAM. The field is  also  found  in  the  WRITE
434              SCATTERED(32)  LBA range descriptors. It is a 16 bit field which
435              means the maximum value is 0xffff. The default value is 0xffff.
436
437       -I, --timeout=TO
438              where TO is the command timeout value in  seconds.  The  default
439              value  is  120 seconds. If NUM is large on slow media then these
440              WRITE commands may require considerably more time than 120  sec‐
441              onds to complete.
442
443       -u, --unmap=U_A
444              where  U_A  is OR-ed bit values used to set the UNMAP and ANCHOR
445              bit fields in the WRITE SAME (16 or 32) cdb. If U_A  is  1  then
446              the  UNMAP  bit  field  is  set; if U_A is 2 then the ANCHOR bit
447              field is set; if U_A is 3 then both the  UNMAP  and  ANCHOR  bit
448              fields  are  set. The default value for both bit fields is clear
449              (0); setting U_A to 0 will also clear both bit fields.
450
451       -v, --verbose
452              increase the degree of verbosity (debug  messages).  These  mes‐
453              sages are usually written to stderr.
454
455       -V, --version
456              output version string then exit.
457
458       -w, --wrprotect=WPR
459              sets  the  WRPROTECT  field  (3 bits) in all sg_write_x commands
460              apart from ORWRITE which has a 3 bit ORPROTECT  field  (and  the
461              synopsis  shows  OPR  to highlight the difference). In all cases
462              WPR is placed in that 3 bit field. The  default  value  is  zero
463              which does not send any PI in the data-out buffer. WPR should be
464              a value between 0 and 7.
465

SCATTERED FILE ASCII FORMAT

467       All commands in this utility can take a --scat-file=SF and that  option
468       can   be   seen   as  a  replacement  for  the  --lba=LBA[,LBA...]  and
469       --num=NUM[,NUM...] options. if both the --scat-file=SF  and  --scat-raw
470       options  are  given then the file named SF is expected to be binary and
471       contain the parameter list header (32 bytes of zeros for  both  the  16
472       and  32  byte variants) followed by zero or more LBA range descriptors,
473       each of 32 bytes each. This section describes what is  expected  in  SF
474       when the --scat-raw option is not given.
475
476       The  ASCII  hexadecimal  "scatter  file" (named by SF) can contain com‐
477       ments, empty lines and numbers. If multiple numbers appear on one  line
478       they  can  be  separated by spaces, tabs or a single comma. Numbers are
479       parsed as decimal unless prefixed by "0x" (or "0X") or have a suffix of
480       "h". Ox is the prefix of hexadecimal number is the C language while T10
481       uses the "h" suffix for the same purpose. Anything from and including a
482       "#"  character to the end-of-line is ignored, so comments can be placed
483       there.
484
485       For the WRITE SCATTERED (16) command, its LBA range descriptors contain
486       two  items  per  descriptor:  an  8  byte LBA followed by a 4 byte num‐
487       ber_of_blocks.  The remaining 20 bytes of the descriptor are zeros. The
488       format  accepted  is  relatively  loose  with  each decoded value being
489       placed in an LBA and then a number_of_blocks until the  end-of-file  is
490       reached.  The pattern starts with a LBA and if it doesn't finish with a
491       number_of_blocks (i.e.  an odd number of values are  parsed)  an  error
492       occurs.  So  the number of LBA range descriptors generated will be half
493       the number of values parsed in SF.
494
495       For the WRITE SCATTERED (32) command, its LBA range descriptors contain
496       five  items  per  descriptor:  an  8 byte LBA followed by a 4 byte num‐
497       ber_of_blocks, then a 4 byte RT, a 2 byte AT, and a 2 byte TM. The last
498       three  items  are  associated  with  protection  information  (PI). The
499       accepted format in the SF file is more constrained than the 16 byte cdb
500       variant.  The  items for each LBA range descriptor must be found on one
501       line with adjacent items being comma separated.  The  first  two  items
502       (LBA  and  number_of_blocks) must be given, and if no more items are on
503       the line then RT, AT and TM are given their default  values  (all  "ff"
504       bytes).  Spaces  and  tabs  may appear between items but commas are the
505       separators. Two commas with no value between them will cause the "miss‐
506       ing" item to receive its default value.
507

NOTES

509       Various  numeric  arguments  (e.g. LBA) may include multiplicative suf‐
510       fixes or be given in hexadecimal. See the "NUMERIC  ARGUMENTS"  section
511       in the sg3_utils(8) man page.
512
513       In  Linux,  prior  to  lk 3.17, the sg driver did not support cdb sizes
514       greater than 16 bytes. Hence a device node like /dev/sg1 which is asso‐
515       ciated  with  the  sg  driver  would fail with this utility if the --32
516       option was given (or implied by other options).  The  bsg  driver  with
517       device  nodes like /dev/bsg/6:0:0:1 does support cdb sizes greater than
518       16 bytes since its introduction in lk 2.6.28 .
519

EXIT STATUS

521       The exit status of sg_write_x is 0 when it is successful. Otherwise see
522       the sg3_utils(8) man page.
523

EXAMPLES

525       One  simple  usage is to write 4 blocks of zeros from (and including) a
526       given LBA according to the rules of WRITE ATOMIC with an atomic  bound‐
527       ary  of  0.  Since no cdb size option is given, the 16 byte cdb will be
528       assumed (i.e.  WRITE ATOMIC(16)):
529
530         sg_write_x --atomic=0 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc
531
532       Since --bs=BS has not been given, then this utility will call the  READ
533       CAPACITY(16)  command on /dev/sdc to determine the number of bytes in a
534       logical block. If the READ CAPACITY(16) command  fails  then  the  READ
535       CAPACITY(10) command is tried. Let us assume one of them works and that
536       the number of bytes in each logical block is 512 bytes. So 4 blocks  of
537       zeros  (each  block  containing  512  bytes)  will be written from (and
538       including) LBA 0x1234 . Now to bypass the need for  the  READ  CAPACITY
539       command(s) the --bs=BS option can be used:
540
541         sg_write_x  --atomic=0  --bs=512  --in=/dev/zero --lba=0x1234 --num=4
542       /dev/sdc
543
544       Since --bs= is given and its value (512) is a  power  of  2,  then  the
545       actual  block size is also 512. If instead 520 was given then the logi‐
546       cal block size would be 512 (the highest power of 2 less than 520)  and
547       the  actual  block size would be 520 bytes. To send the 32 byte variant
548       add --32 as in:
549
550         sg_write_x  --atomic=0  --32  --bs=512  --in=/dev/zero   --lba=0x1234
551       --num=4 /dev/sdc
552
553       To send a WRITE STREAM(32) with a STR_ID of 1 use the following:
554
555         sg_write_x   --stream=1  --32  --bs=512  --in=/dev/zero  --lba=0x1234
556       --num=4 /dev/sdc
557
558       Next is a WRITE SCATTERED(16) command  with  the  scatter  list,  split
559       between the --lba= and --num= options, on the command line:
560
561         sg_write_x    --scattered=2   --lba=2,0x33   --num=4,1  -i  /dev/zero
562       /dev/sg1
563
564       Example of a WRITE SCATTERED(16) command with a  degenerate  LBA  range
565       descriptor (first element to --lba= and --num=):
566
567         sg_write_x    --scattered=2   --lba=0,0x33   --num=0,1  -i  /dev/zero
568       /dev/sg1
569
570       Example of a WRITE SCATTERED(16)  command  with  the  scatter  list  in
571       scat_file.txt
572
573         sg_write_x  --scattered=3 -q scat_file.txt -i /dev/zero /dev/sg1
574
575       Next  a WRITE SCATTERED(16) command with its scatter list and data in a
576       single file. Note that the argument to --scattered= is 0 so the  number
577       of  LBA  range  descriptors  is  calculated  by analyzing the first two
578       blocks of scat_data.bin (because the argument to --combined= is 2) :
579
580         sg_write_x  --scattered=0 --combined=2 -i scat_data.bin /dev/sg1
581
582       When the -xx option is used, a WRITE SCATTERED command is not  executed
583       but  instead  the contents of the data-out buffer are written to a file
584       called sg_write_x.bin . In the case of WRITE SCATTERED that binary file
585       is  suitable for supplying to a later invocation to do the actual write
586       to media. For example:
587
588         sg_write_x  --scattered=3 -q scat_file.txt -xx -i /dev/zero /dev/sg1
589       Wrote 8192 bytes to sg_write_x.bin, LB data offset: 1
590       Number of LBA range descriptors: 3
591         sg_write_x  --scattered=0 --combined=1 -i sg_write_x.bin /dev/sg1
592
593       Notice when the sg_write_x.bin is written (and nothing  is  written  to
594       the media), a summary of what has happened is sent to stdout. The value
595       shown for "LB data offset:" (1) should  be  given  to  the  --combined=
596       option when the write to media actually occurs (i.e. the second invoca‐
597       tion shown directly above).
598

AUTHORS

600       Written by Douglas Gilbert.
601

REPORTING BUGS

603       Report bugs to <dgilbert at interlog dot com>.
604
606       Copyright © 2017-2020 Douglas Gilbert
607       This software is distributed under a FreeBSD license. There is NO  war‐
608       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
609       POSE.
610

SEE ALSO

612       sg_readcap,sg_vpd,sg_write_same,sg_stream_ctl(sg3_utils)
613
614
615
616sg3_utils-1.45                   January 2020                    SG_WRITE_X(8)
Impressum