Provided by: sg3-utils_1.17-2_i386 bug

NAME

       sg_wr_mode - write mode page to given device

SYNOPSIS

       sg_wr_mode    [--contents=<h>,<h>...]    [--dbd]   [--force]   [--help]
       [--len=<10|6>]   [--mask=<h>,<h>...]   [--page=<page_code>]    [--save]
       [--verbose] [--version] <scsi_device>

DESCRIPTION

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

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

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

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

       --force | -f
              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.

       --help | -h
              output the usage message then exit.

       --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 don’t support the 10 byte variants  hence  this
              option.

       --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 mode page then
              the remaining bytes are taken from the existing mode page  (i.e.
              they are left unaltered).

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

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

       --save | -s
              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.

       --verbose | -v
              increase the level of verbosity, (i.e. debug output).

       --version | -V
              print the version string and then exit.

       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 savable. If so an attempt to use  the  ’--save’
       option  should  cause an error to be reported from the device: "Illegal
       field in cdb".

NOTES

       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 -c=2 -p=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 -p=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

AUTHORS

       Written by Douglas Gilbert.

REPORTING BUGS

       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

       Copyright © 2004 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)