diff options
Diffstat (limited to 'doc/sg_modes.8')
| -rw-r--r-- | doc/sg_modes.8 | 314 |
1 files changed, 314 insertions, 0 deletions
diff --git a/doc/sg_modes.8 b/doc/sg_modes.8 new file mode 100644 index 00000000..4fef24ad --- /dev/null +++ b/doc/sg_modes.8 @@ -0,0 +1,314 @@ +.TH SG_MODES "8" "July 2022" "sg3_utils\-1.45" SG3_UTILS +.SH NAME +sg_modes \- reads mode pages with SCSI MODE SENSE command +.SH SYNOPSIS +.B sg_modes +[\fI\-\-all\fR] [\fI\-\-control=PC\fR] [\fI\-\-dbd\fR] [\fI\-\-dbout\fR] +[\fI\-\-examine\fR] [\fI\-\-flexible\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] +[\fI\-\-list\fR] [\fI\-\-llbaa\fR] [\fI\-\-maxlen=LEN\fR] +[\fI\-\-page=PG[,SPG]\fR] [\fI\-\-raw\fR] [\fI\-R\fR] [\fI\-\-readwrite\fR] +[\fI\-\-six\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fIDEVICE\fR] +.PP +.B sg_modes +[\fI\-6\fR] [\fI\-a\fR] [\fI\-A\fR] [\fI\-c=PC\fR] [\fI\-d\fR] [\fI\-D\fR] +[\fI\-e\fR] [\fI\-f\fR] [\fI\-h\fR] [\fI\-H\fR] [\fI\-l\fR] [\fI\-L\fR] +[\fI\-m=LEN\fR] [\fI\-p=PG[,SPG]\fR] [\fI\-r\fR] [\fI\-subp=SPG\fR] +[\fI\-v\fR] [\fI\-V\fR] [\fI\-w\fR] [\fI\-?\fR] [\fIDEVICE\fR] +.SH DESCRIPTION +.\" Add any additional description here +.PP +This utility sends a MODE SENSE SCSI command to the \fIDEVICE\fR and +outputs the response. There is a 6 byte and 10 byte (cdb) variant of the +MODE SENSE command, this utility defaults to the 10 byte variant. The SPC\-4 +standard (and the SPC\-5 standard) include a note stating that implementers +should migrate away from the SCSI MODE SELECT(6) and MODE SENSE(6) commands +in favour of the 10 byte variants (e.g. MODE SENSE(10)). +.PP +This utility decodes mode page headers and block descriptors but outputs +the contents of each mode page in hex. It also has no facility to change +the mode page contents or block descriptor data. Mode page contents are +decoded and can be changed by the +.B sdparm +utility. +.PP +This utility supports two command line syntaxes, the preferred one is +shown first in the synopsis and explained in this section. A later +section on the old command line syntax outlines the second group of +options. +.PP +If no page is given (and \fI\-\-list\fR is not selected) then \fI\-\-all\fR +is assumed. The \fI\-\-all\fR option requests all mode pages (but not +subpages) in a single response. +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +.TP +\fB\-a\fR, \fB\-\-all\fR +output all the mode pages reported by the \fIDEVICE\fR. This is what the +page code 63 (0x3f) is defined to do. When used once, mode subpages are +not fetched. When used twice (e.g. '\-aa'), all mode pages and subpages +are requested which is equivalent to '\-\-page=63,255'. +.TP +\fB\-c\fR, \fB\-\-control\fR=\fIPC\fR +\fIPC\fR is the page control value. Up to four different versions of each +page are held by the device: +.br + \fB0\fR : current values (i.e. those active at present) +.br + \fB1\fR : changeable values +.br + \fB2\fR : default values (i.e. the manufacturer's settings) +.br + \fB3\fR : saved values +.br +The changeable values are bit masks showing which fields could be changed +with a MODE SELECT. The saved values will be re\-instated the next time +the device is power cycled or reset. If this option is not given then +current values [0] are assumed. +.TP +\fB\-d\fR, \fB\-\-dbd\fR +disable block descriptors. By default, block descriptors (usually +one (for disks) or none) are returned in a MODE SENSE response. This option +sets the "disable block descriptors" (DBD) bit in the cdb which instructs +the device not to return any block descriptors in its response. Older +devices may not support this setting and may return an "illegal request" +sense key; alternatively they may ignore it. Oddly the Reduced Block Command +set (RBC) requires this bit set. +.TP +\fB\-D\fR, \fB\-\-dbout\fR +disable outputting block descriptors. Irrespective of whether block +descriptors are present in the response or not, they are not output. +.TP +\fB\-e\fR, \fB\-\-examine\fR +examine each mode page in the range 0 through to 62 (inclusive). +If some response is given then print out the mode page name or +number (in hex) if the name is not known. +.br +The sdparm utility which lists mode and VPD pages also has a \fB\-\-examine\fR +option will similar functionility. +.TP +\fB\-f\fR, \fB\-\-flexible\fR +Some devices, bridges and/or drivers attempt crude translations between +MODE SENSE 6 and 10 byte commands without correcting the response. This +will cause the response to be mis\-interpreted (usually with an error saying +the response is malformed). With this option, the length of the response +is checked, and if it looks wrong, the response is then decoded as if the +other mode sense (cdb length) was sent. +.TP +\fB\-h\fR, \fB\-\-help\fR +print out the usage message then exit. +.TP +\fB\-H\fR, \fB\-\-hex\fR +The default action is to decode known mode page numbers (and subpage +numbers) into text. When this option is used once, the response is output +in hexadecimal to stdout. When this option is used twice, mode page numbers +and page control values are output in hex. +.br +When this option is used three times, the full response to the MODE SENSE +command is output in hex to stdout without any decoding. This form can +be redirected to a file (or piped) and then used 'sdparm \-\-inhex=' to +decode. +.TP +\fB\-l\fR, \fB\-\-list\fR +lists all common page and subpage codes and their names that are found in +the command set that matches the peripheral type of the given \fIDEVICE\fR. +If no \fIDEVICE\fR and no \fI\-\-page=PG\fR is given then the common page and +subpage codes and their names are listed for SBC (e.g. a disk). If no +\fIDEVICE\fR is given and a \fI\-\-page=PG\fR is given then the +common page and subpage codes and their names are listed for the command set +whose peripheral device type matches the value given to \fIPG\fR. For +example 'sg_mode \-\-list \-\-page=1' lists the command mode pages and +subpages for tape devices. Additionally if a sub_page_code is given then it +is interpreted as a transport identifier and command transport specific mode +page codes and their names are listed following the main mode page list. +Other options are ignored. +.TP +\fB\-L\fR, \fB\-\-llbaa\fR +set the Long LBA Accepted (LLBAA) bit in the MODE SENSE (10) cdb. This +bit is not defined in the MODE SENSE (6) cdb so setting the '\-L' +and '\-\-six' options is reported as an error. When set the \fIDEVICE\fR +may respond with 16 byte block descriptors as indicated by +the 'LongLBA' field in the response. In most cases setting this option +is not needed. +.TP +\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR +The \fILEN\fR argument is the maximum response length in bytes. It is +the 'allocation length' field in the cdb. When not given (or \fILEN\fR is +zero) then the allocation length field is set to 4096 for MODE SENSE (10) +or 252 for MODE SENSE (6). The \fILEN\fR argument must be non\-negative +and no greater than 65535 for MODE SENSE (10) and not greater than 255 +for MODE SENSE (6). +.TP +\fB\-O\fR, \fB\-\-old\fR +Switch to older style options. Please use as first option. +.TP +\fB\-p\fR, \fB\-\-page\fR=\fIPG\fR +page code to fetch. The \fIPG\fR is assumed to be a decimal value unless +prefixed by '0x' or has a trailing 'h'. It should be a value between 0 +and 63 (inclusive). When not given and a default is required then +a value of 63 (0x3f), which fetches all mode pages, is used. +.br +Alternatively an acronym for the mode page can be given. The available +acronyms can be listed out with the \fI\-\-page=xxx\fR option. They are +almost the same as the acronyms used for mode pages in the sdparm utility. +.TP +\fB\-p\fR, \fB\-\-page\fR=\fIPG,SPG\fR +page code and subpage code values to fetch. Both arguments are assumed +to be decimal unless flagged as hexadecimal. The page code should be +between 0 and 63 inclusive. The subpage code should be between 0 and 255 +inclusive. The default value for the subpage code is 0. +.TP +\fB\-r\fR, \fB\-\-raw\fR +output the response in binary to stdout. Error messages and warnings, if +any, are sent to stderr. When this option is used twice (e.g. '\-rr') +then has the same action as '\-R' +.TP +\fB\-R\fR +output the selected mode page to stdout a byte per line. Each line contains +two hexadecimal digits (e.g. "3e"). Useful as input (after editing) to +the sg_wr_mode(8) utility. +.TP +\fB\-w\fR, \fB\-\-readwrite\fR +open \fIDEVICE\fR in "read\-write" mode. Default is to open it in read\-only +mode. +.TP +\fB\-6\fR, \fB\-s\fR, \fB\-\-six\fR +by default this utility sends a 10 byte MODE SENSE command to the +\fIDEVICE\fR. However some SCSI devices only support 6 byte MODE SENSE +commands (e.g. SCSI\-2 tape drives). This parameter forces the use of 6 +byte MODE SENSE commands. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +increase level of verbosity. Can be used multiple times. +.TP +\fB\-V\fR, \fB\-\-version\fR +print out version string then exit. +.SH NOTES +If the normal sg_modes utility fails with "illegal command +operation code" then try the '\-\-six' (or '\-6') option. +.PP +This utility performs a SCSI INQUIRY command to determine the peripheral +type of the device (e.g. 0 \-> Direct Access Device (disk)) prior to +sending a MODE SENSE command. This helps in decoding the block +descriptor and mode pages. +.PP +This utility opens \fIDEVICE\fR in read\-only mode (e.g. in Unix, with +the O_RDONLY flag) by default. It will open \fIDEVICE\fR in read\-write +mode if the \fI\-\-readwrite\fR option is given. +.PP +In the 2.4 series of Linux kernels the \fIDEVICE\fR must be a SCSI +generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks +and DVD drives) can also be specified. For example "sg_modes \-a /dev/sda" +will work in the 2.6 series kernels. +.SH EXIT STATUS +The exit status of sg_modes is 0 when it is successful. Otherwise see +the sg3_utils(8) man page. +.SH OLDER COMMAND LINE OPTIONS +The options in this section were the only ones available prior to sg3_utils +version 1.23 . Since then this utility defaults to the newer command line +options which can be overridden by using \fI\-\-old\fR (or \fI\-O\fR) as the +first option. See the ENVIRONMENT VARIABLES section for another way to +force the use of these older command line options. +.TP +\fB\-6\fR +by default this utility sends a 10 byte MODE SENSE command to +the \fIDEVICE\fR. This parameter forces the use of 6 byte MODE SENSE commands. +See \fI\-\-six\fR in the main description. +.TP +\fB\-a\fR +see \fI\-\-all\fR in the main description. +.TP +\fB\-A\fR +output all the mode pages and subpages supported by the \fIDEVICE\fR. Same +as '\-\-all \-\-all' in the new syntax. +.TP +\fB\-c\fR=\fIPC\fR +\fIPC\fR is the page control value. See \fB\-\-control\fR=\fIPC\fR in +the main description. +.TP +\fB\-d\fR +see \fB\-\-dbd\fR in the main description. +.TP +\fB\-D\fR +see \fB\-\-dbout\fR in the main description. +.TP +\fB\-e\fR +see \fB\-\-examine\fR in the main description. +.TP +\fB\-f\fR +see \fB\-\-flexible\fR in the main description. +.TP +\fB\-h\fR +The default action is to decode known mode page numbers (and subpage +numbers) into text. With this option mode page numbers (and subpage +numbers) are output in hexadecimal. +.TP +\fB\-H\fR +same action as the '\-h' option. +.TP +\fB\-l\fR +see \fB\-\-list\fR in the main description. +.TP +\fB\-L\fR +see \fB\-\-llbaa\fR in the main description. +.TP +\fB-N\fR, \fB\-\-new\fR +Switch to the newer style options. +.TP +\fB\-m\fR=\fILEN\fR +see \fB\-\-maxlen\fR=\fILEN\fR in the main description. +.TP +\fB\-p\fR=\fIPG\fR +\fIPG\fR is page code to fetch. Should be a hexadecimal number between 0 +and 3f inclusive (0 to 63 decimal). The default value when required is +3f (fetch all mode pages). Note that an acronym for the page and/or +subpage values is not accepted in this older format (because any acronym +starting with the letters 'a' to 'f' is ambiguous; it could either be a hex +number or an acronym). +.TP +\fB\-p\fR=\fIPG,SPG\fR +page code and subpage code values to fetch. The page code should be a +hexadecimal number between 0 and 3f inclusive. The subpage code should +be a hexadecimal number between 0 and ff inclusive. The default value +for the subpage code is 0. +.TP +\fB\-r\fR +output the selected mode page to stdout a byte per line. Each line contains +two hexadecimal digits (e.g. "3e"). Useful as input (after editing) to +the sg_wr_mode(8) utility. +.TP +\fB\-subp\fR=\fISPG\fR +sub page code to fetch. Should be a hexadecimal number between 0 and +0xff inclusive. The default value is 0. +.TP +\fB\-v\fR +increase verbosity of output. +.TP +\fB\-V\fR +print out version string then exit. +.TP +\fB\-w\fR +see \fB\-\-readwrite\fR in the main description. +.TP +\fB\-?\fR +output usage message then exit. Ignore all other parameters. +.SH ENVIRONMENT VARIABLES +Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS +can be given. When it is present this utility will expect the older command +line options. So the presence of this environment variable is equivalent to +using \fI\-\-old\fR (or \fI\-O\fR) as the first command line option. +.SH AUTHOR +Written by Douglas Gilbert +.SH "REPORTING BUGS" +Report bugs to <dgilbert at interlog dot com>. +.SH COPYRIGHT +Copyright \(co 2000\-2022 Douglas Gilbert +.br +This software is distributed under the GPL version 2. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH "SEE ALSO" +.B sdparm(8), sg_wr_mode(8), sginfo(8), +.B sgmode(scsirastools), scsiinfo(net), scu(net), +.B seatools(seagate) +.PP +All these utilities offer some facility to change mode page (or block +descriptor) parameters. |