.TH SG_MODES "8" "May 2023" "sg3_utils\-1.48" SG3_UTILS
.SH NAME
sg_modes \- reads mode pages with SCSI MODE SENSE command
.SH SYNOPSIS
.B sg_modes
[\fI\-\-all\fR] [\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\-\-multiple\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\-M\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
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) stated 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)). In draft SPC\-6 revision 7 the
SCSI MODE SELECT(6) and MODE SENSE(6) commands have been removed.
.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 with 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\-A\fR, \fB\-\-ALL\fR
same meaning as using the \fI\-\-all\fR option twice. That is, all mode
pages and subpages are fetched. The default is to fetch all the mode
pages but not mode subpages.
.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:
    \fB0\fR : current values (i.e. those active at present)
    \fB1\fR : changeable values
    \fB2\fR : default values (i.e. the manufacturer's settings)
    \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
if the \fI\-\-page=PG[,SPG]\fR option is not given, examine each mode
page in the range 0 through to 62 (inclusive). If the
\fI\-\-page=PG[,SPG]\fR option is give, then all subpages whose page code is
\fIPN\fR are examined (subpages 0 through 254 (inclusive)). If some response
is given then print out the mode (sub)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
Since this utility shows the structure of a MODE SENSE command response (i.e.
its parameter header, zero or more block descriptors followed by zero or
more mode pages) but outputs most of the contents of the response in
hexadecimal. When this option is used once, the only difference is that
the mode page name, if known, is followed by it page number (and subpage
number) bracketed in hex.
.br
When this option is given twice, then each line of hex output has an ASCII
rendering of that hex place at the end of each line. When this option is
given three times, then the hexadimal address, shown at the start of each
hexadecimal line is dropped, there is no ASCII rendering of hex, and all
test lines are removed. This leaves simple hex that is parsable that
represents the MODE SENSE command response. The component parts of that
response are put on separate line.
.br
When the option is given four or more times (recommended for a parsable
form), the ASCII informational lines are back, but they all start
with "#" which a parser needs to ignore.
The output is sent to stdout while any error messages or warning are
sent to stderr. So simple Unix command line redirection of stdout to a
file (done with '>' in most Unix shells) should be sufficient to capture
the output. As noted above, the sdparm utility can be used to decode
that hex file later with its '\-\-inhex=FN' option.
.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\-M\fR, \fB\-\-multiple\fR
for each mode page (and mode subpage), fetch all available page controls.
There may be up to four page controls as outlined in the \fI\-\-control=PC\fR
option. The mode parameter header, and block descriptors are output that
same way as without this option. After the mode page name (and numbers)
are output, there is a line with either current, changeable, default or
saved page control on it followed by that page control in hex.
.br
If the \fI\-\-control=PC\fR option is given, it is overridden by this option.
.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.
.PP
There is no JSON output from this utility because its primary output is
mode pages in hexadecimal. So apart from the mode page name and its
structure, nothing is decoded. The sdparm utility does decode mode
page contents and it does support JSON output.
.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\-M\fR
see \fB\-\-multiple\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 EXAMPLES
All mode pages, but not mode subpages, can be dumped in hex to a file
like this:
.PP
   # sg_modes \-a \-HHHH /dev/sdb > modes_sdeb.hex
.PP
If there are any errors then they are sent to stderr so they will appear
on the console and not within the modes_sdeb.hex file. Nonetheless the
contents of modes_sdeb.hex may not be useful if an error has occurred.
.PP
The '\-HHHH' option produces hex output with comment lines starting with
a '#' character. Each comment describes the following block.
If all is well, the modes_sdeb.hex file will be suitable for the sdparm
utility to decode:
.PP
   # sdparm \-a \-\-inhex=modes_sdeb.hex
.PP
See the sdparm(8) manpage for further information.
.br
To dump both mode pages and subpages, use this invocation:
.PP
   # sg_modes -aa -HHHH /dev/sdb > modes_sdeb.hex
.PP
No change is needed in the associated sdparm call. There is some example
output in the inhex directory in the sg3_utils package, in a file called:
modes_sdeb.hex . The file was produced by using this utility on the
scsi_debug driver in Linux.
.PP
Each mode page (and subpage) has up to four 'page controls': current,
changeable, default and saved. The last three may or may not be supported
by the device. All available page controls for all mode pages and subpages
can be placed in a hex file with this invocation:
.PP
   # sg_modes \-aa \-M \-HHHH /dev/sdb > modes_mm_sdeb.hex
.PP
Again, no change is needed in the associated sdparm call. There is some
example output in the inhex directory in the sg3_utils package, in a file
called: modes_mm_sdeb.hex .
.SH AUTHOR
Written by Douglas Gilbert
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2000\-2023 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.