SG3UTILS SGWRMODE(1M)
NAME
sgwrmode - write mode page
SYNOPSIS
sgwrmode [--contents=H,H...] [--dbd] [--force] [--help]
[--len=106] [--mask=M,M...] [--page=PG[,SPG] [--save]
[--verbose] [--version] DEVICE
DESCRIPTION
Writes a modified mode page to DEVICE. 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.
If a contents argument is not given then the various com-
ponents (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 dev-
ice.
If the contents are specified, and a mask is not specified,
then the contents must match the existing mode page in vari-
ous aspects unless the --force option is given. These
include length, mode page code and subpage code if applica-
ble. If all is well then the contents string is written to
DEVICE as the new mode page.
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.
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 --dbd
option if need be.
Changing individual fields in a mode page is probably more
easily done with the sdparm utility. Fields can be
sg3utils-1.26 Last change: March 2008 1
SG3UTILS SGWRMODE(1M)
identified by acronym or by a numerical descriptor.
OPTIONS
Arguments to long options are mandatory for short options as
well.
-c, --contents=H,H...
where H,H... is a string of comma separated hex numbers
each of which should resolve to a byte value (i.e. 0 to
ff inclusive). This is the new contents of the mode
page to be written to DEVICE, potentially filtered by
the mask string.
-c, --contents=-
reads contents string from stdin. The 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 DEVICE, potentially
filtered by the mask string.
-d, --dbd
disable block descriptors (DBD flag in cdb). Some dev-
ice 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.
-f, --force
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 DEVICE may still reject the new
contents for the mode page. Cannot be given with the
--mask=M,M... option.
-h, --help
output the usage message then exit.
-l, --len=10 6
length of the SCSI commands (cdb) sent to DEVICE. 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.
-m, --mask=M,M...
where M,M... is a string of comma separated hex numbers
each of which should resolve to a byte value (i.e. 0 to
sg3utils-1.26 Last change: March 2008 2
SG3UTILS SGWRMODE(1M)
ff inclusive). 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 unal-
tered).
-p, --page=PG
where PG 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.
-p, --page=PG,SPG
where PG is the page code value and SPG 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.
-s, --save
changes the "saved" mode page when MODE SELECT is suc-
cessful. By default (i.e. when --save 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 --save option.
-v, --verbose
increase the level of verbosity, (i.e. debug output).
-V, --version
print the version string and then exit.
NOTES
This utility does not check whether the contents string is
trying to modify parts of the mode page which are change-
able. The device should do that and if some part is not
changeable then it should report: "Invalid field in parame-
ter list".
Some mode pages are not savable. If so an attempt to use the
--save option should cause an error to be reported from the
device: "Illegal field in cdb".
sg3utils-1.26 Last change: March 2008 3
SG3UTILS SGWRMODE(1M)
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.
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 'sgmodes
-p=1a -r /dev/sdb > mp1a.txt' (the power condition mode
page). The mp1a.txt file can be edited and then used as the
contents string to this utility (e.g. 'sgwrmode -p 1a -s
-c - /dev/sdb < mp1a.txt').
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 --force option is selected.
EXAMPLES
This utility can be used together with the sgmodes 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:
$ sgmodes --control=2 --page=1a -r /dev/sda > t
$ sgwrmode --page=1a --contents=- --save /dev/sda < t
Next is an example of using a mask to modify the "idle con-
dition 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 sgmodes is abridged.
$ sgmodes --page=1a /dev/hdc
>> Power condition (mmc), pagecontrol: current
00 1a 0a 00 03 00 00 00 28 00 00 01 2c
$ sgwrmode -p 1a -c 0,0,0,0,0,0,0,37 -m 0,0,0,0,0,0,0,ff
/dev/hdc
$ sgmodes -p 1a /dev/hdc
>> Power condition (mmc), pagecontrol: current
00 1a 0a 00 03 00 00 00 37 00 00 01 2c
EXIT STATUS
The exit status of sgwrmode is 0 when it is successful.
sg3utils-1.26 Last change: March 2008 4
SG3UTILS SGWRMODE(1M)
Otherwise see the sg3utils(1M) man page.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to .
COPYRIGHT
Copyright O 2004-2008 Douglas Gilbert
This software is distributed under a FreeBSD license. There
is NO warranty; not even for MERCHANTABILITY or FITNES FOR
A PARTICULAR PURPOSE.
SEE ALSO
sdparm(sdparm), sgmodes(sg3utils), sginfo(sg3utils)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWsg3utilsu
Interface Stability Committed
NOTES
Source for sg3utils is available on http:/opensolaris.org.
sg3utils-1.26 Last change: March 2008 5
|
