Ubuntu Manpage: sg_modes - reads mode pages with SCSI MODE SENSE command

Provided by: sg3-utils_1.48-0ubuntu1_amd64

NAME

       sg_modes - reads mode pages with SCSI MODE SENSE command

SYNOPSIS

       sg_modes  [--all]  [--ALL]  [--control=PC]  [--dbd]  [--dbout]  [--examine] [--flexible] [--help] [--hex]
       [--list] [--llbaa] [--maxlen=LEN]  [--multiple]  [--page=PG[,SPG]]  [--raw]  [-R]  [--readwrite]  [--six]
       [--verbose] [--version] [DEVICE]

       sg_modes  [-6] [-a] [-A] [-c=PC] [-d] [-D] [-e] [-f] [-h] [-H] [-l] [-L] [-m=LEN] [-M] [-p=PG[,SPG]] [-r]
       [-subp=SPG] [-v] [-V] [-w] [-?]  [DEVICE]

DESCRIPTION

       This utility sends a MODE SENSE SCSI command to the DEVICE 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.

       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 sdparm utility.

       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.

       If no page is given (and --list is not selected) then --all is assumed. The  --all  option  requests  all
       mode pages (but not subpages) in a single response.

OPTIONS

Arguments to long options are mandatory for short options as well.

-a, --all
output all the mode pages reported by the DEVICE. 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'.

-A, --ALL
same meaning as using the --all option twice. That is, all mode pages and subpages are fetched.
The default is to fetch all the mode pages but not mode subpages.

-c, --control=PC
PC is the page control value. Up to four different versions of each page are held by the device:
0 : current values (i.e. those active at present)
1 : changeable values
2 : default values (i.e. the manufacturer's settings)
3 : saved values
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.

-d, --dbd
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.

-D, --dbout
disable outputting block descriptors. Irrespective of whether block descriptors are present in the
response or not, they are not output.

-e, --examine
if the --page=PG[,SPG] option is not given, examine each mode page in the range 0 through to 62
(inclusive). If the --page=PG[,SPG] option is give, then all subpages whose page code is PN 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.
The sdparm utility which lists mode and VPD pages also has a --examine option will similar
functionility.

-f, --flexible
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.

-h, --help
print out the usage message then exit.

-H, --hex
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.
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.
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.

-l, --list
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 DEVICE. If no DEVICE and no --page=PG is given then the
common page and subpage codes and their names are listed for SBC (e.g. a disk). If no DEVICE is
given and a --page=PG 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 PG. 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.

-L, --llbaa
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
DEVICE 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.

-m, --maxlen=LEN
The LEN argument is the maximum response length in bytes. It is the 'allocation length' field in
the cdb. When not given (or LEN is zero) then the allocation length field is set to 4096 for MODE
SENSE (10) or 252 for MODE SENSE (6). The LEN argument must be non-negative and no greater than
65535 for MODE SENSE (10) and not greater than 255 for MODE SENSE (6).

-M, --multiple
for each mode page (and mode subpage), fetch all available page controls. There may be up to four
page controls as outlined in the --control=PC 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.
If the --control=PC option is given, it is overridden by this option.

-O, --old
Switch to older style options. Please use as first option.

-p, --page=PG
page code to fetch. The PG 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.
Alternatively an acronym for the mode page can be given. The available acronyms can be listed out
with the --page=xxx option. They are almost the same as the acronyms used for mode pages in the
sdparm utility.

-p, --page=PG,SPG
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.

-r, --raw
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'

-R 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.

-w, --readwrite
open DEVICE in "read-write" mode. Default is to open it in read-only mode.

-6, -s, --six
by default this utility sends a 10 byte MODE SENSE command to the DEVICE. 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.

-v, --verbose
increase level of verbosity. Can be used multiple times.

-V, --version
print out version string then exit.

NOTES

       If the normal sg_modes utility fails with "illegal command operation code" then try the '--six' (or '-6')
       option.

       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.

       This utility opens DEVICE in read-only mode (e.g. in Unix, with the O_RDONLY flag) by  default.  It  will
       open DEVICE in read-write mode if the --readwrite option is given.

       In the 2.4 series of Linux kernels the DEVICE 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.

       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.

EXIT STATUS

       The exit status of sg_modes is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

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 --old (or -O) as
the first option. See the ENVIRONMENT VARIABLES section for another way to force the use of these older
command line options.

-6 by default this utility sends a 10 byte MODE SENSE command to the DEVICE. This parameter forces
the use of 6 byte MODE SENSE commands. See --six in the main description.

-a see --all in the main description.

-A output all the mode pages and subpages supported by the DEVICE. Same as '--all --all' in the new
syntax.

-c=PC PC is the page control value. See --control=PC in the main description.

-d see --dbd in the main description.

-D see --dbout in the main description.

-e see --examine in the main description.

-f see --flexible in the main description.

-h 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.

-H same action as the '-h' option.

-l see --list in the main description.

-L see --llbaa in the main description.

-N, --new
Switch to the newer style options.

-m=LEN see --maxlen=LEN in the main description.

-M see --multiple in the main description.

-p=PG PG 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).

-p=PG,SPG
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.

-r 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.

-subp=SPG
sub page code to fetch. Should be a hexadecimal number between 0 and 0xff inclusive. The default
value is 0.

-v increase verbosity of output.

-V print out version string then exit.

-w see --readwrite in the main description.

-? output usage message then exit. Ignore all other parameters.

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 --old (or -O) as the first command line option.

EXAMPLES

All mode pages, but not mode subpages, can be dumped in hex to a file like this:

# sg_modes -a -HHHH /dev/sdb > modes_sdeb.hex

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.

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:

# sdparm -a --inhex=modes_sdeb.hex

See the sdparm(8) manpage for further information.
To dump both mode pages and subpages, use this invocation:

# sg_modes -aa -HHHH /dev/sdb > modes_sdeb.hex

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.

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:

# sg_modes -aa -M -HHHH /dev/sdb > modes_mm_sdeb.hex

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 .

AUTHOR

       Written by Douglas Gilbert

REPORTING BUGS

       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

       Copyright © 2000-2023 Douglas Gilbert
       This software is distributed under the GPL version 2. There is NO warranty; not even for  MERCHANTABILITY
       or FITNESS FOR A PARTICULAR PURPOSE.