diff options
Diffstat (limited to 'sg_write_buffer.8')
| -rw-r--r-- | sg_write_buffer.8 | 106 |
1 files changed, 106 insertions, 0 deletions
diff --git a/sg_write_buffer.8 b/sg_write_buffer.8 new file mode 100644 index 00000000..77b0d2a7 --- /dev/null +++ b/sg_write_buffer.8 @@ -0,0 +1,106 @@ +.TH SG_WRITE_BUFFER "8" "January 2007" "sg3_utils\-1.23" SG3_UTILS +.SH NAME +sg_write_buffer \- send a SCSI WRITE BUFFER command +.SH SYNOPSIS +.B sg_write_buffer +[\fI\-\-help\fR] [\fI\-\-id=ID\fR] [\fI\-\-in=FILE\fR] [\fI\-\-length=LEN\fR] +[\fI\-\-mode=MO\fR] [\fI\-\-offset=OFF\fR] [\fI\-\-raw\fR] +[\fI\-\-skip=SKIP\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Sends a SCSI WRITE BUFFER command to \fIDEVICE\fR, along with data provided +by the user. In some cases no data is required, or data can be read from the +file given in the \fI\-\-in=FILE\fR option, or data is read from stdin when +either \fI\-\-raw\fR or \fI\-\-in=\-\fR is given. +.PP +Some WRITE BUFFER command variants do not have associated data to send to the +device, for example "activate_mc" ("activate deferred microcode"). +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +.TP +\fB\-h\fR, \fB\-\-help\fR +output the usage message then exit. If used multiple times also prints +the mode names and their acronyms. +.TP +\fB\-i\fR, \fB\-\-id\fR=\fIID\fR +this option sets the buffer id field in the cdb. \fIID\fR is a value between +0 (default) and 255 inclusive. +.TP +\fB\-I\fR, \fB\-\-in\fR=\fIFILE\fR +read data from file \fIFILE\fR that will be sent with the WRITE BUFFER +command. If \fIFILE\fR is '\-' then stdin is read until an EOF is +detected (this is the same action as \fI\-\-raw\fR). +.TP +\fB\-l\fR, \fB\-\-length\fR=\fILEN\fR +where \fILEN\fR is the length, in bytes, of data to be written to the device. +If not given (and length cannot be deduced from \fI\-\-in=FILE\fR or +\fI\-\-raw\fR) then defaults to zero. If the option is given and the length +deduced from \fI\-\-in=FILE\fR or \fI\-\-raw\fR is less (or no data is +provided), then bytes of 0xff are used as fill bytes. +.TP +\fB\-m\fR, \fB\-\-mode\fR=\fIMO\fR +this option sets the mode field in the cdb. \fIMO\fR is a value between +0 (default) and 31 inclusive. Alternatively an abbreviation can be given. +To list the available mode abbreviations give an invalid +one (e.g. '\-\-mode=xxx') or use the '\-hh' option. + +.TP +\fB\-o\fR, \fB\-\-offset\fR=\fIOFF\fR +this option sets the buffer offset field in the cdb. \fIOFF\fR is a value +between 0 (default) and 2**24-1 . It is a byte offset. +.TP +\fB\-r\fR, \fB\-\-raw\fR +read data from stdin until an EOF is detected. This data is sent with +the WRITE BUFFER command to \fIDEVICE\fR. The action of this option is the +same as using '\-\-in=\-'. +.TP +\fB\-s\fR, \fB\-\-skip\fR=\fISKIP\fR +this option is only active when \fI\-\-in=FILE\fR is given and +\fIFILE\fR is a regular file, rather than stdin. Data is read +starting at byte offset \fISKIP\fR to the end of file (or the amount +given by \fI\-\-length=LEN\fR). If not given the byte offset defaults to +0 (i.e. the start of the file). +.TP +\fB\-v\fR, \fB\-\-verbose\fR +increase the level of verbosity, (i.e. debug output). +.TP +\fB\-V\fR, \fB\-\-version\fR +print the version string and then exit. +.SH NOTES +If no \fI\-\-length=LEN\fR is given this utility reads up to 8 MiB of data +from the given file \fIFILE\fR (or stdin). If a larger amount of data is +required then the \fI\-\-length=LEN\fR option should be given. The user +should be aware that most operating systems have limits on the amount +of data that can be sent with one SCSI command. In Linux this +depends on the pass through mechanism used (e.g. block SG_IO or +the sg driver) and various setting in sysfs in the linux lk 2.6 +series (e.g. /sys/block/sda/queue/max_sectors_kb). +.PP +Downloading incorrect microcode into a device has the ability to render +that device inoperable. One would hope that the device vendor verifies +the data before activating it. If the SCSI WRITE BUFFER command is given +values in its cdb (e.g. \fILEN\fR) that are inappropriate (e.g. too large) +then the device should respond with a sense key of ILLEGAL REQUEST and +an additional sense code of INVALID FIELD in CDB. If a WRITE BUFFER +command (or a sequence of them) fails due to device vendor verification +checks then it should respond with a sense key of ILLEGAL REQUEST and +an additional sense code of COMMAND SEQUENCE ERROR. +.PP +All numbers given with options are assumed to be decimal. +Alternatively numerical values can be given in hexadecimal preceded by +either "0x" or "0X" (or has a trailing "h" or "H"). +.SH EXIT STATUS +The exit status of sg_write_buffer is 0 when it is successful. Otherwise +see the sg3_utils(8) man page. +.SH AUTHORS +Written by Luben Tuikov and Douglas Gilbert. +.SH "REPORTING BUGS" +Report bugs to <dgilbert at interlog dot com>. +.SH COPYRIGHT +Copyright \(co 2006\-2007 Luben Tuikov and Douglas Gilbert +.br +This software is distributed under a FreeBSD license. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH "SEE ALSO" +.B sg_read_buffer(sg3_utils) |