1SG_WRITE_X(8) SG3_UTILS SG_WRITE_X(8)
2
6 sg_write_x - SCSI WRITE normal/ATOMIC/SAME/SCATTERED/STREAM, ORWRITE
7 commands
8
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 Synopsis per supported command:
20 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 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 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 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 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 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
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 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 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 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 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 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 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
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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -h, --help
265 output the usage message then exit. Use multiple times for more
266 help. Currently '-h' to '-hhhh' provide different output.
267 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -v, --verbose
451 increase the degree of verbosity (debug messages). These mes‐
452 sages are usually written to stderr.
453 -V, --version
455 output version string then exit.
456 -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
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 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 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 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
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 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
520 The exit status of sg_write_x is 0 when it is successful. Otherwise see
521 the sg3_utils(8) man page.
522
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 sg_write_x --atomic=0 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc
530 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 sg_write_x --atomic=0 --bs=512 --in=/dev/zero --lba=0x1234 --num=4
541 /dev/sdc
542 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 sg_write_x --atomic=0 --32 --bs=512 --in=/dev/zero --lba=0x1234
550 --num=4 /dev/sdc
551 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 To send a WRITE STREAM(32) with a STR_ID of 1 use the following:
557 sg_write_x --stream=1 --32 --bs=512 --in=/dev/zero --lba=0x1234
559 --num=4 /dev/sdc
560 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 sg_write_x --scattered=2 --lba=2,0x33 --num=4,1 -i /dev/zero
565 /dev/sg1
566 Example of a WRITE SCATTERED(16) command with a degenerate LBA range
568 descriptor (first element to --lba= and --num=):
569 sg_write_x --scattered=2 --lba=0,0x33 --num=0,1 -i /dev/zero
571 /dev/sg1
572 Example of a WRITE SCATTERED(16) command with the scatter list in
574 scat_file.txt
575 sg_write_x --scattered=3 -q scat_file.txt -i /dev/zero /dev/sg1
577 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 sg_write_x --scattered=0 --combined=2 -i scat_data.bin /dev/sg1
584 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 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 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
603 Written by Douglas Gilbert.
604
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
615 sg_readcap,sg_vpd,sg_write_same,sg_stream_ctl(sg3_utils)
616sg3_utils-1.45 June 2020 SG_WRITE_X(8)