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]  DE‐
29       VICE
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 op‐
63       tions. Hence the SYNOPSIS, after listing all the (long) options,  lists
64       those  applicable to each supported command. For each command synopsis,
65       the option that selects the SCSI command is shown first followed by any
66       required  options.  If no command option is given then a "normal" WRITE
67       is assumed. Even though the --scat-file=SF option can be given for  ev‐
68       ery command, it is only shown for WRITE SCATTERED where it is most use‐
69       ful.  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 ex‐
94       its  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 de‐
105       vice can inform the application client of its limitations via the block
106       limits  VPD  page (0xb0), with the maximum atomic transfer length field
107       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 de‐
115       generate LBA range descriptor is valid. This may become an issue if  RD
116       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  de‐
124       scribed  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 re‐
146              quire a DEVICE formatted with type 1, 2 or 3 protection informa‐
147              tion.
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  OR‐
152              WRITE(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 ac‐
174              tual 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  ac‐
200              tual  block size which is the logical block size plus a multiple
201              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. De‐
306              faults to logical block 0 (which could be dangerous)  while  NUM
307              defaults  to 0 which makes the combination harmless.  LBA is as‐
308              sumed to be in decimal unless prefixed with '0x' or has a trail‐
309              ing '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 op‐
322              tion) then it defaults to the number of blocks derived from  the
323              size of the file named by IF (starting at byte offset OFF to the
324              end or the file or DLEN). Apart from the --combined=DOF  option,
325              an  LBA  must be explicitly given (either with I--lba=LBA or via
326              --scat-file=SF), if not NUM defaults to 0 as a safety measure.
327
328       -o, --offset=OFF[,DLEN]
329              where OFF is the byte offset within the file named IF  to  start
330              reading  from. The default value of OFF is zero which is the be‐
331              ginning of file named IF. DLEN is the maximum number of bytes to
332              read,  starting at byte offset OFF, from the file named IF. Less
333              bytes will be read if an end of file occurs before DLEN  is  ex‐
334              hausted.  If  DLEN  is  zero or not given then reading from byte
335              offset OFF to the end of the file named IF is assumed.
336
337       -O, --or
338              selects the ORWRITE command. ORWRITE(16) has similar  fields  to
339              WRITE(16)  apart  from the WRPROTECT field being named ORPROTECT
340              with slightly different semantics and the absence of the  3  DLD
341              bit  fields. ORWRITE(32) has four extra fields that are set with
342              the --bmop=OP,PGP and --generation=EOG,NOG options.  ORWRITE(32)
343              is  the  only  32 byte cdb command in this utility that does not
344              require a DEVICE formatted with type 1, 2 or 3 PI  (although  it
345              will still work if it is formatted with PI).
346
347       -Q, --quiet
348              suppress some informational messages such as the ones associated
349              with detected errors when this utility is  about  to  exit.  The
350              exit status value is still returned to the operating system when
351              this utility exits.
352
353       -r, --ref-tag=RT
354              where RT is the "expected initial logical block  reference  tag"
355              field  found in the 32 byte cdb variants of WRITE, WRITE ATOMIC,
356              WRITE SAME and WRITE STREAM.  The field is  also  found  in  the
357              WRITE  SCATTERED(32) LBA range descriptors. It is a 32 bit field
358              which means the maximum value is 0xffffffff. The  default  value
359              is 0xffffffff.
360
361       -S, --same=NDOB
362              selects  the  WRITE SAME command with the NDOB field set to NDOB
363              which stands for No Data-Out Buffer. NDOB can take values 0 or 1
364              (i.e. it is a single bit field). When --same=1 all options asso‐
365              ciated with the data-out buffer are ignored.
366
367       -q, --scat-file=SF
368              where SF is the name of an auxiliary file containing the scatter
369              list  for  the WRITE SCATTERED command. If the --scat-raw option
370              is also given then SF is assumed to contain both  the  parameter
371              list  header  (32  bytes  of zeros) followed by zero or more LBA
372              range descriptors which are also 32 bytes long each. These  com‐
373              ponents  are  as defined by SBC-4 (i.e.  in binary with integers
374              in big endian format). If the --scat-raw  option  is  not  given
375              then a file of ACSII hexadecimal is expected as described in the
376              SCATTERED FILE ASCII FORMAT section below.
377              If this option is given with the --combined=DOF option then this
378              utility will exit with a syntax error. SF must not be "-", a way
379              of stopping the user trying to redirect stdin.
380
381       -R, --scat-raw
382              this option only effects the way that the file named SF from the
383              --scat-file=SF option for WRITE SCATTERED is interpreted. By de‐
384              fault (i.e. without this option), SF is parsed as ASCII hexadec‐
385              imal  with  blank lines and line contents from and including '#'
386              to the end of line ignored. Hence it can  contain  comments  and
387              other  indications. When this option is given, the file named SF
388              is interpreted as binary.  As binary it is assumed to contain 32
389              bytes  of zeros (the WRITE SCATTERED parameter list header) fol‐
390              lowed by zero or more LBA range descriptors (which are 32  bytes
391              each).  If  the  --strict  option is given the reserved field in
392              those two items are checked with any non zero bytes  causing  an
393              error.
394
395       -S, --scattered=RD
396              selects  the WRITE SCATTERED command with RD being the number of
397              LBA range descriptors that will be placed in the  data-out  buf‐
398              fer.  If  RD  is  zero then the logic will try and determine the
399              number of range descriptors by other means (e.g. by parsing  the
400              file  named  by SF, if there is one).  The LBA range descriptors
401              differ between the 16 and 32 byte cdb variants  of  WRITE  SCAT‐
402              TERED. In the 16 byte cdb variant the 32 byte LBA range descrip‐
403              tor is made up of an 8 byte LBA,  followed  by  a  4  byte  num‐
404              ber_of_blocks  followed  by  20  bytes  of zeros. In the 32 byte
405              variant the LBA and number_of_blocks are followed  by  a  RT  (4
406              bytes),  an AT (2 bytes) and a TM (2 bytes) then 12 bytes of ze‐
407              ros.
408              This paragraph applies when RD is greater than zero.  If  RD  is
409              less than the number of LBA range descriptors built from command
410              line options, from the --scat-file=SF option or decoded from  IF
411              (when  the  --combined=DOF option is given) then RD takes prece‐
412              dence; so RD is placed in the "Number of LBA Range  Descriptors"
413              field  in the cdb. If RD is greater than the number of LBA range
414              descriptors found from the provided data and  options,  then  an
415              error is generated.
416
417       -T, --stream=ID
418              selects  the  WRITE  STREAM command with the STR_ID field set to
419              ID.  ID can take values from 0 to 0xffff (i.e. it is  a  16  bit
420              field).
421
422       -s, --strict
423              when  this  option  is  present, more things (e.g. that reserved
424              fields contain zeros) and any irregularities will terminate  the
425              utility  with a message to stderr and an indicative exit status.
426              While experimenting with these commands, especially WRITE  SCAT‐
427              TERED, it is recommended to use this option.
428
429       -t, --tag-mask=TM
430              where  TM  is  the  "logical  block  application tag mask" field
431              found in the 32 byte cdb variants of WRITE, WRITE ATOMIC,  WRITE
432              SAME  and  WRITE  STREAM.  The  field is also found in the WRITE
433              SCATTERED(32) LBA range descriptors. It is a 16 bit field  which
434              means the maximum value is 0xffff. The default value is 0xffff.
435
436       -I, --timeout=TO
437              where  TO  is  the command timeout value in seconds. The default
438              value is 120 seconds. If NUM is large on slow media  then  these
439              WRITE  commands may require considerably more time than 120 sec‐
440              onds to complete.
441
442       -u, --unmap=U_A
443              where U_A is OR-ed bit values used to set the UNMAP  and  ANCHOR
444              bit  fields  in  the WRITE SAME (16 or 32) cdb. If U_A is 1 then
445              the UNMAP bit field is set; if U_A is  2  then  the  ANCHOR  bit
446              field  is  set;  if  U_A is 3 then both the UNMAP and ANCHOR bit
447              fields are set. The default value for both bit fields  is  clear
448              (0); setting U_A to 0 will also clear both bit fields.
449
450       -v, --verbose
451              increase  the  degree  of verbosity (debug messages). These mes‐
452              sages are usually written to stderr.
453
454       -V, --version
455              output version string then exit.
456
457       -w, --wrprotect=WPR
458              sets the WRPROTECT field (3 bits)  in  all  sg_write_x  commands
459              apart  from  ORWRITE  which has a 3 bit ORPROTECT field (and the
460              synopsis shows OPR to highlight the difference).  In  all  cases
461              WPR  is  placed  in  that 3 bit field. The default value is zero
462              which does not send any PI in the data-out buffer. WPR should be
463              a value between 0 and 7.
464

SCATTERED FILE ASCII FORMAT

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

NOTES

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

EXIT STATUS

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

EXAMPLES

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

AUTHORS

603       Written by Douglas Gilbert.
604

REPORTING BUGS

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

SEE ALSO

615       sg_readcap,sg_vpd,sg_write_same,sg_stream_ctl(sg3_utils)
616
617
618
619sg3_utils-1.45                     June 2020                     SG_WRITE_X(8)
Impressum