sg_write_buffer(8)

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

NAME

6       sg_write_buffer - send SCSI WRITE BUFFER command
7

SYNOPSIS

9       sg_write_buffer    [--help]    [--id=ID]   [--in=FILE]   [--length=LEN]
10       [--mode=MO]  [--offset=OFF]   [--raw]   [--skip=SKIP]   [--specific=MS]
11       [--verbose] [--version] DEVICE
12

DESCRIPTION

14       Sends  a  SCSI WRITE BUFFER command to DEVICE, along with data provided
15       by the user. In some cases no data is required, or  data  can  be  read
16       from the file given in the --in=FILE option, or data is read from stdin
17       when either --raw or --in=- is given.
18
19       Some WRITE BUFFER command variants do not have associated data to  send
20       to   the   device,   for   example  "activate_mc"  ("activate  deferred
21       microcode").
22

OPTIONS

24       Arguments to long options are mandatory for short options as well.
25
26       -h, --help
27              output the usage message then exit. If used multiple times  also
28              prints the mode names and their acronyms.
29
30       -i, --id=ID
31              this  option  sets the buffer id field in the cdb. ID is a value
32              between 0 (default) and 255 inclusive.
33
34       -I, --in=FILE
35              read data from file FILE that will be sent with the WRITE BUFFER
36              command.   If  FILE  is  '-'  then stdin is read until an EOF is
37              detected (this is the same action as --raw).
38
39       -l, --length=LEN
40              where LEN is the length, in bytes, of data to be written to  the
41              device.   If  not  given  (and  length  cannot  be  deduced from
42              --in=FILE or --raw) then defaults to  zero.  If  the  option  is
43              given and the length deduced from --in=FILE or --raw is less (or
44              no data is provided), then bytes of 0xff are used as fill bytes.
45
46       -m, --mode=MO
47              this option sets the mode field  in  the  cdb.  MO  is  a  value
48              between 0 (default) and 31 inclusive. Alternatively an abbrevia‐
49              tion can be given.  To list  the  available  mode  abbreviations
50              give an invalid one (e.g. '--mode=xxx') or use the '-hh' option.
51
52       -o, --offset=OFF
53              this  option  sets  the buffer offset field in the cdb. OFF is a
54              value between 0 (default) and 2**24-1 . It is a byte offset.
55
56       -r, --raw
57              read data from stdin until an EOF is detected. This data is sent
58              with  the  WRITE  BUFFER  command  to DEVICE. The action of this
59              option is the same as using '--in=-'.
60
61       -s, --skip=SKIP
62              this option is only active when --in=FILE is given and FILE is a
63              regular  file,  rather than stdin. Data is read starting at byte
64              offset SKIP  to  the  end  of  file  (or  the  amount  given  by
65              --length=LEN).  If not given the byte offset defaults to 0 (i.e.
66              the start of the file).
67
68       -S, --specific=MS
69              MS is the mode specific field in the cdb. This is a 3-bit  field
70              so  the values 0 to 7 are accepted. This field was introduced in
71              SPC-4 revision 32 and can be used to specify  additional  events
72              that activate deferred microcode (when MO is 0xD).
73
74       -v, --verbose
75              increase the level of verbosity, (i.e. debug output).
76
77       -V, --version
78              print the version string and then exit.
79

NOTES

81       If no --length=LEN is given this utility reads up to 8 MiB of data from
82       the given file FILE (or stdin). If a larger amount of data is  required
83       then  the --length=LEN option should be given. The user should be aware
84       that most operating systems have limits on the amount of data that  can
85       be  sent  with  one  SCSI  command.  In  Linux this depends on the pass
86       through mechanism used (e.g. block SG_IO or the sg driver) and  various
87       setting    in    sysfs    in    the   Linux   lk   2.6   series   (e.g.
88       /sys/block/sda/queue/max_sectors_kb).
89
90       Downloading incorrect microcode into a device has the ability to render
91       that  device inoperable. One would hope that the device vendor verifies
92       the data before activating it. If the  SCSI  WRITE  BUFFER  command  is
93       given  values  in  its  cdb (e.g. LEN) that are inappropriate (e.g. too
94       large) then the device should respond  with  a  sense  key  of  ILLEGAL
95       REQUEST  and  an  additional  sense  code of INVALID FIELD in CDB. If a
96       WRITE BUFFER command (or a sequence of them) fails due to device vendor
97       verification  checks then it should respond with a sense key of ILLEGAL
98       REQUEST and an additional sense code of COMMAND SEQUENCE ERROR.
99
100       All numbers given with options are assumed  to  be  decimal.   Alterna‐
101       tively  numerical values can be given in hexadecimal preceded by either
102       "0x" or "0X" (or has a trailing "h" or "H").
103

EXIT STATUS

105       The exit status of sg_write_buffer is 0 when it is  successful.  Other‐
106       wise see the sg3_utils(8) man page.
107

AUTHORS

109       Written by Luben Tuikov and Douglas Gilbert.
110

REPORTING BUGS

112       Report bugs to <dgilbert at interlog dot com>.
113

COPYRIGHT

115       Copyright © 2006-2012 Luben Tuikov and Douglas Gilbert
116       This  software is distributed under a FreeBSD license. There is NO war‐
117       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
118       POSE.
119