path: root/doc/sg_wr_mode.8

.TH SG_WR_MODE "8" "April 2018" "sg3_utils\-1.43" SG3_UTILS
.SH NAME
sg_wr_mode \- write (modify) SCSI mode page
.SH SYNOPSIS
.B sg_wr_mode
[\fI\-\-contents=H,H...\fR] [\fI\-\-dbd\fR] [\fI\-\-force\fR] [\fI\-\-help\fR]
[\fI\-\-len=10|6\fR] [\fI\-\-mask=M,M...\fR] [\fI\-\-page=PG_H[,SPG_H]\fR]
[\fI\-\-rtd\fR] [\fI\-\-save\fR] [\fI\-\-six\fR] [\fI\-\-verbose\fR]
[\fI\-\-version\fR] \fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
Writes a modified mode page to \fIDEVICE\fR. Uses the SCSI MODE SENSE (6
or 10 byte variant) command to fetch the existing mode data which includes
a mode page (or subpage). It then combines that with the contents,
potentially masked, and writes the modified mode page with the SCSI MODE
SELECT (6 or 10 byte variant) command. This utility does not modify
the block descriptor(s); if any block descriptors are fetched by the MODE
SENSE command then the same block descriptors are written back with the
following MODE SELECT command.
.PP
If the \fI\-\-rtd\fR option is given then most other options apart from
\fI\-\-save\fR, \fI\-\-len=\fR10|6\fR and \fI\-\-six\fR are ignored. In this
case only a MODE SELECT command is sent to the \fIDEVICE\fR with the RTD
bit (Revert To Defaults) set. This bit was added to this command in SPC\-5
revision 11, so older devices may not support it. The Extended Inquiry VPD
page has the RTD_SUP bit to indicate whether the \fIDEVICE\fR supports the
RTD bit in the MODE SELECT(6 and 10) commands. When the \fI\-\-rtd\fR option
is given the rest of this section can be ignored.
.PP
If a contents argument is not given then the various components (i.e.
header, block descriptor(s) and mode page) of the "current" values of
the existing mode page are printed out. In this case the mode page is
not altered on the device.
.PP
If the contents are specified, and a mask is not specified, then the contents
must match the existing mode page in various aspects unless the
\fI\-\-force\fR option is given. These include length, mode page code and
subpage code if applicable. If all is well then the contents string is
written to \fIDEVICE\fR as the new mode page.
.PP
If both contents and mask strings are specified then only bit positions
in the contents corresponding to set bits in the mask are taken while the
existing mode page supplies bit positions corresponding to clear bits.
When a mask is given then the mask and/or the contents may be shorter
than the existing mode page. If the mask is shorter than the contents then
the remaining bytes are taken from the contents. If the contents are shorter
than the existing mode page then the remaining bytes are taken from the
existing mod page.
.PP
The force option allows the contents string to be written as the new
mode page without any prior checks on the existing mode page. This should
only be required for vendor specific mode pages. The existing mode data
is ignored apart from the block descriptors which can be suppressed with
the \fI\-\-dbd\fR option if need be.
.PP
Changing individual fields in a mode page is probably more easily done
with the sdparm utility. Fields can be identified by acronym or by a
numerical descriptor.
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
.TP
\fB\-c\fR, \fB\-\-contents\fR=\fIH,H...\fR
where \fIH,H...\fR is a string of comma separated hex numbers each of
which should resolve to a byte value (i.e. 0 to ff inclusive). A (single)
space separated string of hex numbers is also allowed but the list needs to
be in quotes. This is the new contents of the mode page to be written to
\fIDEVICE\fR, potentially filtered by the mask string.
.TP
\fB\-c\fR, \fB\-\-contents\fR=-
reads contents string from stdin. The hex numbers in the string may be comma,
space, tab or linefeed (newline) separated. If a line contains "#" then the
remaining characters on that line are ignored. Otherwise each non separator
character should resolve to a byte value (i.e. 0 to ff inclusive). This
forms the new contents of the mode page to be written to \fIDEVICE\fR,
potentially filtered by the mask string.
.TP
\fB\-d\fR, \fB\-\-dbd\fR
disable block descriptors (DBD flag in cdb). Some device types include
block descriptors in the mode data returned by a MODE SENSE command. If
so the same block descriptors are written by the MODE SELECT command.
This option instructs the MODE SENSE command not to return any block
descriptors. This would be a sensible default for this utility apart
from the fact that not all SCSI devices support the DBD bit in the cdb.
.TP
\fB\-f\fR, \fB\-\-force\fR
force the contents string to be taken as the new mode page, or at least
doesn't do checks on the existing mode page. Note that \fIDEVICE\fR may
still reject the new contents for the mode page. Cannot be given with
the \fI\-\-mask=M,M...\fR option.
.TP
\fB\-h\fR, \fB\-\-help\fR
output the usage message then exit.
.TP
\fB\-l\fR, \fB\-\-len\fR=10 | 6
length of the SCSI commands (cdb) sent to \fIDEVICE\fR. The default is 10
so 10 byte MODE SENSE and MODE SELECT commands are issued. Some old devices
don't support the 10 byte variants hence this option.
.TP
\fB\-m\fR, \fB\-\-mask\fR=\fIM,M...\fR
where \fIM,M...\fR is a string of comma separated hex numbers each of which
should resolve to a byte value (i.e. 0 to ff inclusive). A (single) space
separated string of hex numbers is also allowed but the list needs to be in
quotes. The mask chooses (bit by bit) whether the new mode page comes from
the contents (mask bit set) or from the existing mode page (mask bit clear).
If the mask string is shorter than the contents string then the remaining
bytes are taken from the contents string. If the contents string is shorter
than the existing mode page then the remaining bytes are taken from the
existing mode page (i.e. they are left unaltered).
.TP
\fB\-p\fR, \fB\-\-page\fR=\fIPG_H\fR
where \fIPG_H\fR is the page code value to fetch and modify. The page code
is in hex and should be between 0 and 3e inclusive. Notice that page code
3f to fetch all mode pages is disallowed.
.TP
\fB\-p\fR, \fB\-\-page\fR=\fIPG_H,SPG_H\fR
where \fIPG_H\fR is the page code value and \fISPG_H\fR is the subpage code
value to fetch and modify. Both values are in hex. The subpage code should
be between 0 and fe inclusive. Notice that subpage code ff to fetch all
mode subpages (for a given mode page or all mode pages in the case of 3f,ff)
is disallowed.
.TP
\fB\-R\fR, \fB\-\-rtd\fR
when this option is given most other actions are bypassed and a MODE
SELECT(6 or 10) command is sent to the \fIDEVICE\fR with the RTD bit set.
This will cause all current values (and saved values if the \fI\-\-save\fR
option is also given) of all mode pages to be reverted to their default
values.
.TP
\fB\-s\fR, \fB\-\-save\fR
changes the "saved" mode page when MODE SELECT is successful. By
default (i.e. when \fI\-\-save\fR is not used) only the "current" mode page
values are changed when MODE SELECT is successful. In this case the new mode
page will stay in effect until the device is reset (e.g.  power cycled).
When it restarts the "saved" values for the mode page will be re\-instated.
So to make changes permanent use the \fI\-\-save\fR option.
.br
When used with the \fI\-\-rtd\fR option then both the current and saved
values in each mode page are reverted to their default values. In the
absence of \fI\-\-save\fR option only the current values in each mode page
are reverted to their default values.
.TP
\fB\-6\fR, \fB\-\-six\fR
this option will cause the 6 byte variants of MODE SENSE and MODE SELECT
commands to be used. The default is to use the 10 byte options. This option
is equivalent to using the \fI\-\-len=6\fR option.

.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
This utility does not check whether the contents string is trying to
modify parts of the mode page which are changeable. The device should
do that and if some part is not changeable then it should
report: "Invalid field in parameter list".
.PP
Some mode pages are not saveable. If so an attempt to use the \fI\-\-save\fR
option should cause an error to be reported from the device: "Illegal field
in cdb".
.PP
The device is required to do various checks before it accepts a new
mode page. If these checks fail then the mode page is not altered and
either a "parameter list length error" or an "invalid field in
parameter list" error is returned by the device in the sense data.
.PP
The recommended way to modify a mode page is to read it with a
MODE SENSE, modify some part of it then write it back to the
device with a MODE SELECT command. For example, reading an existing mode
page can be accomplished with 'sg_modes \-p=1a \-r /dev/sdb > mp_1a.txt' (the
power condition mode page). The mp_1a.txt file can be edited and then used
as the contents string to this
utility (e.g. 'sg_wr_mode \-p 1a \-s \-c \- /dev/sdb < mp_1a.txt').
.PP
Two fields differ between what is read from the device with MODE SENSE and
what is written to the device with MODE SELECT:
the mode data length is reserved (i.e. zero(es)) in a MODE
SELECT command while the PS bit ((sub)page byte 0 bit 7) in each
mode (sub)page is reserved (zero) in a MODE SELECT command.
The PS bit given in the contents string is zeroed unless
the \fI\-\-force\fR option is selected.
.SH EXAMPLES
This utility can be used together with the sg_modes utility. To re\-instate
the default mode page values (i.e. the mode page values chosen by the
manufacturer of the device) as both the current and saved mode page
values the following sequence could be used:
.PP
  $ sg_modes \-\-control=2 \-\-page=1a \-r /dev/sda > t
.br
  $ sg_wr_mode \-\-page=1a \-\-contents=\- \-\-save /dev/sda < t
.PP
Next is an example of using a mask to modify the "idle condition counter"
of the "power condition" mode page (0x1a) from 0x28 to 0x37. Note that the
change is not saved so the "idle condition counter" will revert to 0x28
after the next power cycle. The output from sg_modes is abridged.
.PP
 $ sg_modes \-\-page=1a /dev/hdc
.br
 >> Power condition (mmc), page_control: current
.br
 00     1a 0a 00 03 00 00 00 28  00 00 01 2c
.PP
 $ sg_wr_mode \-p 1a \-c 0,0,0,0,0,0,0,37 \-m 0,0,0,0,0,0,0,ff /dev/hdc
.PP
 $ sg_modes \-p 1a /dev/hdc
.br
 >> Power condition (mmc), page_control: current
.br
 00     1a 0a 00 03 00 00 00 37  00 00 01 2c
.SH EXIT STATUS
The exit status of sg_wr_mode is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH AUTHORS
Written by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2004\-2018 Douglas Gilbert
.br
This software is distributed under a BSD\-2\-Clause license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sdparm(sdparm), sg_modes(sg3_utils), sginfo(sg3_utils)