1SG_WR_MODE(8)                      SG3_UTILS                     SG_WR_MODE(8)
2
3
4

NAME

6       sg_wr_mode - write (modify) SCSI mode page
7

SYNOPSIS

9       sg_wr_mode  [--contents=H,H...] [--dbd] [--force] [--help] [--len=10|6]
10       [--mask=M,M...]   [--page=PG[,SPG]]  [--save]  [--verbose]  [--version]
11       DEVICE
12

DESCRIPTION

14       Writes  a  modified mode page to DEVICE. Uses the SCSI MODE SENSE (6 or
15       10 byte variant) command to fetch the existing mode data which includes
16       a  mode  page  (or  subpage).  It then combines that with the contents,
17       potentially masked, and writes the modified mode  page  with  the  SCSI
18       MODE  SELECT (6 or 10 byte variant) command. This utility does not mod‐
19       ify the block descriptor(s); if any block descriptors  are  fetched  by
20       the MODE SENSE command then the same block descriptors are written back
21       with the following MODE SELECT command.
22
23       If a contents argument is not given then the various  components  (i.e.
24       header,  block  descriptor(s) and mode page) of the "current" values of
25       the existing mode page are printed out. In this case the mode  page  is
26       not altered on the device.
27
28       If  the  contents  are specified, and a mask is not specified, then the
29       contents must match the existing mode page in  various  aspects  unless
30       the  --force  option is given. These include length, mode page code and
31       subpage code if applicable. If all is well then the contents string  is
32       written to DEVICE as the new mode page.
33
34       If both contents and mask strings are specified then only bit positions
35       in the contents corresponding to set bits in the mask are  taken  while
36       the  existing  mode  page supplies bit positions corresponding to clear
37       bits.  When a mask is given then the mask and/or the  contents  may  be
38       shorter  than  the  existing mode page. If the mask is shorter than the
39       contents then the remaining bytes are taken from the contents.  If  the
40       contents  are  shorter  than  the existing mode page then the remaining
41       bytes are taken from the existing mod page.
42
43       The force option allows the contents string to be written  as  the  new
44       mode  page  without  any  prior  checks on the existing mode page. This
45       should only be required for vendor specific mode  pages.  The  existing
46       mode data is ignored apart from the block descriptors which can be sup‐
47       pressed with the --dbd option if need be.
48
49       Changing individual fields in a mode page is probably more easily  done
50       with  the  sdparm  utility. Fields can be identified by acronym or by a
51       numerical descriptor.
52

OPTIONS

54       Arguments to long options are mandatory for short options as well.
55
56       -c, --contents=H,H...
57              where H,H... is a string of comma separated hex numbers each  of
58              which should resolve to a byte value (i.e. 0 to ff inclusive). A
59              (single) space separated string of hex numbers is  also  allowed
60              but  the list needs to be in quotes. This is the new contents of
61              the mode page to be written to DEVICE, potentially  filtered  by
62              the mask string.
63
64       -c, --contents=-
65              reads  contents string from stdin. The hex numbers in the string
66              may be comma, space, tab or linefeed (newline) separated.  If  a
67              line contains "#" then the remaining characters on that line are
68              ignored. Otherwise each non separator character  should  resolve
69              to  a  byte  value  (i.e. 0 to ff inclusive). This forms the new
70              contents of the mode page to be written to  DEVICE,  potentially
71              filtered by the mask string.
72
73       -d, --dbd
74              disable  block  descriptors (DBD flag in cdb). Some device types
75              include block descriptors in the mode data returned  by  a  MODE
76              SENSE  command.  If so the same block descriptors are written by
77              the MODE SELECT command.  This option instructs the  MODE  SENSE
78              command  not  to  return  any block descriptors. This would be a
79              sensible default for this utility apart from the fact  that  not
80              all SCSI devices support the DBD bit in the cdb.
81
82       -f, --force
83              force  the  contents string to be taken as the new mode page, or
84              at least doesn't do checks on the existing mode page. Note  that
85              DEVICE may still reject the new contents for the mode page. Can‐
86              not be given with the --mask=M,M... option.
87
88       -h, --help
89              output the usage message then exit.
90
91       -l, --len=10 | 6
92              length of the SCSI commands (cdb) sent to DEVICE. The default is
93              10  so  10  byte MODE SENSE and MODE SELECT commands are issued.
94              Some old devices don't support the 10 byte variants  hence  this
95              option.
96
97       -m, --mask=M,M...
98              where  M,M... is a string of comma separated hex numbers each of
99              which should resolve to a byte value (i.e. 0 to ff inclusive). A
100              (single)  space  separated string of hex numbers is also allowed
101              but the list needs to be in quotes. The  mask  chooses  (bit  by
102              bit) whether the new mode page comes from the contents (mask bit
103              set) or from the existing mode page (mask bit  clear).   If  the
104              mask string is shorter than the contents string then the remain‐
105              ing bytes are taken from the contents string.  If  the  contents
106              string is shorter than the existing mode page then the remaining
107              bytes are taken from the existing mode page (i.e. they are  left
108              unaltered).
109
110       -p, --page=PG
111              where  PG  is  the page code value to fetch and modify. The page
112              code is in hex and should be between 0 and 3e inclusive.  Notice
113              that page code 3f to fetch all mode pages is disallowed.
114
115       -p, --page=PG,SPG
116              where  PG  is  the  page  code value and SPG is the subpage code
117              value to fetch and modify. Both values are in hex.  The  subpage
118              code  should  be between 0 and fe inclusive. Notice that subpage
119              code ff to fetch all mode subpages (for a given mode page or all
120              mode pages in the case of 3f,ff) is disallowed.
121
122       -s, --save
123              changes the "saved" mode page when MODE SELECT is successful. By
124              default (i.e. when --save is not used) only the  "current"  mode
125              page  values are changed when MODE SELECT is successful. In this
126              case the new mode page will stay in effect until the  device  is
127              reset (e.g.  power cycled).  When it restarts the "saved" values
128              for the mode page will be re-instated.  So to make changes  per‐
129              manent use the --save option.
130
131       -v, --verbose
132              increase the level of verbosity, (i.e. debug output).
133
134       -V, --version
135              print the version string and then exit.
136

NOTES

138       This  utility  does  not check whether the contents string is trying to
139       modify parts of the mode page which are changeable. The  device  should
140       do  that  and  if  some  part  is not changeable then it should report:
141       "Invalid field in parameter list".
142
143       Some mode pages are not saveable. If so an attempt to  use  the  --save
144       option  should  cause an error to be reported from the device: "Illegal
145       field in cdb".
146
147       The device is required to do various checks before  it  accepts  a  new
148       mode  page.  If these checks fail then the mode page is not altered and
149       either a "parameter list length error" or an "invalid field in  parame‐
150       ter list" error is returned by the device in the sense data.
151
152       The  recommended  way  to  modify a mode page is to read it with a MODE
153       SENSE, modify some part of it then write it back to the device  with  a
154       MODE  SELECT command. For example, reading an existing mode page can be
155       accomplished with 'sg_modes -p=1a -r /dev/sdb > mp_1a.txt'  (the  power
156       condition mode page). The mp_1a.txt file can be edited and then used as
157       the contents string to this utility (e.g. 'sg_wr_mode -p  1a  -s  -c  -
158       /dev/sdb < mp_1a.txt').
159
160       Two  fields differ between what is read from the device with MODE SENSE
161       and what is written to the device  with  MODE  SELECT:  the  mode  data
162       length  is  reserved (i.e. zero(es)) in a MODE SELECT command while the
163       PS bit ((sub)page byte 0 bit 7) in  each  mode  (sub)page  is  reserved
164       (zero)  in  a  MODE  SELECT  command.  The PS bit given in the contents
165       string is zeroed unless the --force option is selected.
166

EXAMPLES

168       This utility can  be  used  together  with  the  sg_modes  utility.  To
169       re-instate the default mode page values (i.e. the mode page values cho‐
170       sen by the manufacturer of the device) as both the  current  and  saved
171       mode page values the following sequence could be used:
172
173         $ sg_modes --control=2 --page=1a -r /dev/sda > t
174         $ sg_wr_mode --page=1a --contents=- --save /dev/sda < t
175
176       Next  is  an  example  of  using  a  mask to modify the "idle condition
177       counter" of the "power condition" mode page (0x1a) from 0x28  to  0x37.
178       Note  that the change is not saved so the "idle condition counter" will
179       revert to 0x28 after the next power cycle. The output from sg_modes  is
180       abridged.
181
182        $ sg_modes --page=1a /dev/hdc
183        >> Power condition (mmc), page_control: current
184        00     1a 0a 00 03 00 00 00 28  00 00 01 2c
185
186        $ 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
187
188        $ sg_modes -p 1a /dev/hdc
189        >> Power condition (mmc), page_control: current
190        00     1a 0a 00 03 00 00 00 37  00 00 01 2c
191

EXIT STATUS

193       The exit status of sg_wr_mode is 0 when it is successful. Otherwise see
194       the sg3_utils(8) man page.
195

AUTHORS

197       Written by Douglas Gilbert.
198

REPORTING BUGS

200       Report bugs to <dgilbert at interlog dot com>.
201
203       Copyright © 2004-2012 Douglas Gilbert
204       This software is distributed under a FreeBSD license. There is NO  war‐
205       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
206       POSE.
207

SEE ALSO

209       sdparm(sdparm), sg_modes(sg3_utils), sginfo(sg3_utils)
210
211
212
213sg3_utils-1.35                   November 2012                   SG_WR_MODE(8)
Impressum