diff options
Diffstat (limited to 'sg_wr_mode.8')
| -rw-r--r-- | sg_wr_mode.8 | 151 |
1 files changed, 77 insertions, 74 deletions
diff --git a/sg_wr_mode.8 b/sg_wr_mode.8 index 9bd2de7c..639f7bb1 100644 --- a/sg_wr_mode.8 +++ b/sg_wr_mode.8 @@ -1,19 +1,20 @@ -.TH SG_WR_MODE "8" "June 2006" "sg3_utils-1.21" SG3_UTILS +.TH SG_WR_MODE "8" "January 2007" "sg3_utils\-1.23" SG3_UTILS .SH NAME -sg_wr_mode \- write mode page to given device +sg_wr_mode \- write 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=<h>,<h>...\fR] [\fI--page=<page_code>\fR] -[\fI--save\fR] [\fI--verbose\fR] [\fI--version\fR] \fI<scsi_device>\fR +[\fI\-\-contents=H,H...\fR] [\fI\-\-dbd\fR] [\fI\-\-force\fR] +[\fI\-\-help\fR] [\fI\-\-len=\fR10|6\fR] [\fI\-\-mask=M,M...\fR] +[\fI\-\-page=PG[,SPG]\fR] [\fI\-\-save\fR] [\fI\-\-verbose\fR] +[\fI\-\-version\fR] \fIDEVICE\fR .SH DESCRIPTION .\" Add any additional description here .PP -Writes a modified mode page to the given device. Uses the MODE SENSE (6 or -10 byte variant) SCSI 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 MODE -SELECT (6 or 10 byte variant) SCSI command. This utility does not modify +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. @@ -24,10 +25,10 @@ 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 '--force' -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 the device -as the new mode page. +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 @@ -42,27 +43,29 @@ 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. +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 ---contents=<h>,<h>... | -c <h>,<h>... -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 the device, potentially filtered by the mask -string. +\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). This is the +new contents of the mode page to be written to \fIDEVICE\fR, potentially +filtered by the mask string. .TP ---contents=- | -c - -reads contents string from stdin. 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 the device, potentially filtered -by the mask string. +\fB\-c\fR, \fB\-\-contents\fR=- +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 \fIDEVICE\fR, +potentially filtered by the mask string. .TP ---dbd | -d +\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. @@ -70,65 +73,65 @@ 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 ---force | -f +\fB\-f\fR, \fB\-\-force\fR force the contents string to be taken as the new mode page, or at least -don't do checks on the existing mode page. Note that the device may still -reject the new contents for the mode page. Cannot be given with -the '--mask' option. +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 ---help | -h +\fB\-h\fR, \fB\-\-hex\fR output the usage message then exit. .TP ---len=<10|6> | -l <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 +\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 ---mask=<h>,<h>... | -m <h>,<h>... -string of comma separated hex numbers each of which should resolve to -a byte value (i.e. 0 to 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 +\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). 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 ---page=<page_code> | -p <page_code> -the page code to fetch and modify. The page code is in hex and should -be between 0 and 3e inclusive. Notice that the page code 3f to fetch -all mode pages is disallowed. +\fB\-p\fR, \fB\-\-page\fR=\fIPG\fR +where \fIPG\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 ---page=<page_code>,<subpage_code> | -p <page_code>,<subpage_code> -the page and subpage code to fetch and modify. Both values are in hex. -The subpage code should be between 0 and fe inclusive. Notice that the -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. +\fB\-p\fR, \fB\-\-page\fR=\fIPG,SPG\fR +where \fIPG\fR is the page code value and \fISPG\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 ---save | -s +\fB\-s\fR, \fB\-\-save\fR changes the "saved" mode page when MODE SELECT is successful. 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. To make changes permanent then use the '--save' -option. +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. .TP ---verbose | -v +\fB\-v\fR, \fB\-\-verbose\fR increase the level of verbosity, (i.e. debug output). .TP ---version | -V +\fB\-V\fR, \fB\-\-version\fR print the version string and then exit. -.PP +.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 savable. If so an attempt to use the '--save' +Some mode pages are not savable. 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". -.SH NOTES +.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 @@ -137,10 +140,10 @@ 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 'sg_modes -p=1a -r /dev/sdb > mp_1a.txt' (the +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'). +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: @@ -148,31 +151,31 @@ 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. +the \fI\-\-force\fR option is selected. .SH EXAMPLES -This utility can be used together with the sg_modes utility. To re-instate +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 -c=2 -p=1a -r /dev/sda > t + $ sg_modes \-c=2 \-p=1a \-r /dev/sda > t .br - $ sg_wr_mode --page=1a --contents=- --save /dev/sda < t + $ 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 -p=1a /dev/hdc + $ sg_modes \-p=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 + $ 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 + $ sg_modes \-p=1a /dev/hdc .br >> Power condition (mmc), page_control: current .br @@ -185,7 +188,7 @@ Written by Douglas Gilbert. .SH "REPORTING BUGS" Report bugs to <dgilbert at interlog dot com>. .SH COPYRIGHT -Copyright \(co 2004-2006 Douglas Gilbert +Copyright \(co 2004\-2007 Douglas Gilbert .br This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |