Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sg_wr_mode (8)

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]] [--save] [--verbose] [--version]
DEVICE

Description

SG_WR_MODE(8)                      SG3_UTILS                     SG_WR_MODE(8)



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]] [--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 mod-
       ify 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 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 sup-
       pressed 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. Can-
              not 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 remain-
              ing 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.

       -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  per-
              manent use the --save option.

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

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


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+--------------------------+
       |ATTRIBUTE TYPE |     ATTRIBUTE VALUE      |
       +---------------+--------------------------+
       |Availability   | system/storage/sg3_utils |
       +---------------+--------------------------+
       |Stability      | Pass-through uncommitted |
       +---------------+--------------------------+
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  parame-
       ter 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 cho-
       sen 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 (C) 2004-2016 Douglas Gilbert
       This software is distributed under a FreeBSD license. There is NO  war-
       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
       POSE.

SEE ALSO
       sdparm(sdparm), sg_modes(sg3_utils), sginfo(sg3_utils)


       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was downloaded from  http://sg.danny.cz/sg/p/sg3_utils-1.42.tgz

       Further information about this software can be found on the open source
       community website at http://sg.danny.cz/sg/sg3_utils.html.



sg3_utils-1.42                   February 2016                   SG_WR_MODE(8)