Provided by: sg3-utils_1.46-1ubuntu0.22.04.1_amd64 bug

NAME

       sg_wr_mode - write (modify) SCSI mode page

SYNOPSIS

       sg_wr_mode  [--contents=H,H...]  [--dbd]  [--force]  [--help] [--len=10|6] [--mask=M,M...]
       [--page=PG_H[,SPG_H]] [--rtd] [--save] [--six] [--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  the  --rtd  option  is given then most other options apart from --save, --len=10|6 and
       --six are ignored. In this case only a MODE SELECT command is sent to the DEVICE 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  DEVICE supports the RTD bit in the MODE SELECT(6 and 10) commands.
       When the --rtd option is given the rest of this section can be ignored.

       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.

       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 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 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). 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 DEVICE, potentially filtered by the mask
              string.

       -c, --contents=-
              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 DEVICE, potentially filtered by  the
              mask string.

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

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

       -p, --page=PG_H
              where  PG_H 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_H,SPG_H
              where  PG_H is the page code value and SPG_H 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.

       -R, --rtd
              when this option is given most other actions are bypassed and a  MODE  SELECT(6  or
              10)  command  is  sent  to  the  DEVICE  with the RTD bit set.  This will cause all
              current values (and saved values if the --save option is also given)  of  all  mode
              pages to be reverted to their default values.

       -s, --save
              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.  So to make changes permanent use the --save option.
              When used with the --rtd option then both the current and saved values in each mode
              page are reverted to their default values. In the absence of --save option only the
              current values in each mode page are reverted to their default values.

       -6, --six
              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 --len=6 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 changeable. The device  should  do  that  and  if  some  part  is  not
       changeable then it should report: "Invalid field in parameter list".

       Some  mode  pages are not saveable. If so an attempt to use the --save option should cause
       an error to be reported from the device: "Illegal field in cdb".

       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  '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').

       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 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:

         $ sg_modes --control=2 --page=1a -r /dev/sda > t
         $ sg_wr_mode --page=1a --contents=- --save /dev/sda < t

       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.

        $ sg_modes --page=1a /dev/hdc
        >> Power condition (mmc), page_control: current
        00     1a 0a 00 03 00 00 00 28  00 00 01 2c

        $ 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_modes -p 1a /dev/hdc
        >> Power condition (mmc), page_control: current
        00     1a 0a 00 03 00 00 00 37  00 00 01 2c

EXIT STATUS

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

AUTHORS

       Written by Douglas Gilbert.

REPORTING BUGS

       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

       Copyright © 2004-2018 Douglas Gilbert
       This  software  is distributed under a FreeBSD license. There is NO warranty; not even for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       sdparm(sdparm), sg_modes(sg3_utils), sginfo(sg3_utils)