Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

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]] [--rtd] [--save] [--six]  [--ver-
bose] [--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]] [--rtd] [--save] [--six]  [--ver-
       bose] [--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 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 com-
       mand 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 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.

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


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.

       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

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

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

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




sg3_utils-1.43                    April 2018                     SG_WR_MODE(8)