sg_write_attr - send SCSI WRITE ATTRIBUTE command

       Written by Douglas Gilbert and Boris Fox.

       Copyright © 2016-2020 Douglas Gilbert, 2022-2023 Boris Fox
       This  software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY
       or FITNESS FOR A PARTICULAR PURPOSE.

       Sends a SCSI WRITE ATTRIBUTE command to DEVICE among with attribute-value pairs specified in command line
       arguments or read from the input file.  This command was introduced in  SPC-3  revision  1  and  thus  is
       applicable  to all SCSI devices. In practice it is used mainly for tape systems. This utility is based on
       the SPC-5 draft standard, revision 17 (spc5r17.pdf).

       Set a tape barcode ASCII attribute specified by acronym and a string value:

       #sg_write_attr/dev/sg1BarCode=BARCODE01

       Set a tape barcode ASCII attribute specified by hexadecimal identifier and a string value:

       #sg_write_attr/dev/sg10x806=BARCODE01

       Set a user label text attribute with string value containing spaces in quoted command line argument:

       #sg_write_attr/dev/sg1"UserLabel=Userlabel1"

       Set a user label text attribute with hex sequence value:

       #sg_write_attr/dev/sg1UserLabel:42,41,52,43,4F,44,45,30,32
       or
       #sg_write_attr/dev/sg1"0x803:424152434F44453032"

       Set a locale identifier attribute with values specified by acronyms or numbers:

       #sg_write_attr/dev/sg1LocaleId=ascii#sg_write_attr/dev/sg1LocaleId=utf-8#sg_write_attr/dev/sg1LocaleId=0x80#sg_write_attr/dev/sg1LocaleId:81#sg_write_attr/dev/sg10x805=iso-8859-9

       Set multiple attributes specified in command line arguments:

       #sg_write_attr/dev/sg1BarCode=BARCODE01"UserLabel=MyUserLabel"LocaleId=iso-8859-1

       Set variable-length binary attribute with values in numerical or hex sequence formats:

       #sg_write_attr/dev/sg1VCI=1#sg_write_attr/dev/sg1VCI=65535#sg_write_attr/dev/sg1VCI=0x012345#sg_write_attr/dev/sg1VCI=0x0123456789abcdef#sg_write_attr/dev/sg1VCI:01,23,45,67,89,ab,cd,ef,20,21,22,23,24,25,26,27,28,29,2a,2b,2c,2d,2e,2f

       Set fixed-length binary attribute using value in hex sequence format:

       #sg_write_attr/dev/sg1"MediumGUID:63386636623932322d373838392d313165642d386535312d663736656232633938386431"

       Delete an attribute using empty value:

       #sg_write_attr/dev/sg1BarCode=
       or
       #sg_write_attr/dev/sg1BarCode:

       Delete multiple attributes:

       #sg_write_attr/dev/sg1UserLabel=BarCode=0x805=

       Set attributes specified in the text input file:

       #sg_write_attr--in=attrs.txt/dev/sg1
       Contents of the "attrs.txt" file:
       AppVersion=1.02.15UserLabel=UserLabel1LastWritten=251120221637Barcode=BARCODE02OwningHost=backup_serverMediaPoolName=FirstMediaPoolPartUserLabel=PART01LUatPart=1AppFmtVersion=MTF0125VCI=0x0123456789abcdefMediumGUID:62646136623035342d373838392d313165642d396564302d623731306332626330343039

       Set attribute list specified in the hexadecimal format input file:

       #sg_write_attr--in=attrs_hex.txt--hex/dev/sg1
       Contents of the "attrs_hex.txt" file:
       000000250806010020424152434f44452d303220202020202020202020202020202020202020202020

       Set attribute list specified in the raw binary input file:

       #sg_write_attr--in=attrs_raw.bin--raw/dev/sg1
       Contents of the "attrs_raw.bin" file:
       $od-Ax-tx1z-vattrs_raw.bin000000000000250806010020424152434f4445>...%....BARCODE<0000102d303220202020202020202020202020>-02<000020202020202020202020><000029

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

       sg_write_attr - send SCSI WRITE ATTRIBUTE command

       Only tape systems seem to implement the SCSI WRITE ATTRIBUTE command. The vast majority of its definition
       is in the SPC standard so other device types could use it.
       Total  buffer  length  for  the attribute list in the SCSI WRITE ATTRIBUTE command payload is 1 MiB (1024
       KiB).

       Arguments to long options are mandatory for short options as well.

       -e, --enumerate
              enumerates all known attributes. Attributes include an identifier, length, format and  a  name  as
              defined  by  T10,  with  supplementary  acronym  which  may  be  used  instead of identifier. Some
              attributes may also include predefined set of values.  If  DEVICE  or  attribute=value  pairs  are
              given then they are ignored.

       -E, --element=EA
              where  EA  is  an  element  address which is placed in the WRITE ATTRIBUTE cdb. This field is only
              found in SMC-2 and SMC-3 drafts for medium changers usually associated  with  tape  libraries.  By
              default this field is set to zero.

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

       -H, --hex
              used  together  with  the  input  file  (-i, --in=FN) to indicate input contents is in hexadecimal
              format with no leading address (on each line),  similar  to  one  produced  by  sg_read_attr-HHH
              output.

       -i, --in=FNFN is treated as a file name (or '-' for stdin) which contains attribute-value pairs one per line,
              ASCII  hexadecimal  or  binary  representing the payload of the WRITE ATTRIBUTE command. When this
              option is given then attribute=value pairs (if also given) are ignored.
              By default FN is assumed to contain a list of attribute-value pairs, one per  line.   Empty  lines
              and  lines  starting  from "#" are ignored.  If the --hex is given, FN is assumed to contain ASCII
              hexadecimal arranged as bytes which a space, tab or comma  delimited.  All  characters  from  (and
              including)  "#"  to  the  end of line are ignored. If the --raw option given then FN is assumed to
              contain binary data. When both --hex and --raw options are given, latter takes precedence.

       -l, --lvn=LVN
              where LVN is placed in the "logical volume number" field of the cdb.  The default  value  is  zero
              which is required to be the logical volume number if the device only has one volume.

       -p, --pn=PN
              where  PN  is  placed  in  the  "partition  number"  field  of the cdb. If the DEVICE only has one
              partition then its partition number must be zero. The default value of PN is zero.

       -r, --raw
              used together with the input file (-i, --in=FN) to indicate input format is binary, similar to one
              produced by sg_read_attr--raw output.

       -c, --wtc
              sets the WRITE THROUGH CACHE bit in the WRITE ATTRIBUTE cdb.  This instructs the device server  to
              return successful status only when the attributes have been synchronized with the medium auxiliary
              memory.  By default the WTC bit is not set.

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

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

   Attribute-valuepairformat
       An  attribute-value pair comprised of the attribute identifier and attribute value, delimited by an equal
       sign '=' or a colon ':'.  Attribute identifier can be specified as a number in decimal,  octal  (prefixed
       by  '0')  or  hexadecimal (prefixed by '0x') representation, or with an acronym if the attribute provides
       one.  Delimiter sign determines value representation: an equal sign denotes values in string or numerical
       format, or acronym, while a colon sign denotes a hex sequence comprised  of  bytes  in  hexadecimal  form
       separated by a space or comma.
       String  values  can  be  used  with  attributes  in  ASCII or text format, while numbers and acronyms are
       suitable for binary attributes.  Available acronyms can be listed by the  --enumerate  options.  Acronyms
       are case-insensitive.
       For  the fixed-length binary attributes, value length must match attribute length exactly. Maximum binary
       attribute value in numerical representation is restricted by the unsigned long long type size on a  given
       platform (8 bytes typically), while hexadecimal sequence can be of arbitrary length.
       Values of ASCII format attributes are left aligned padded with spaces to attribute length.
       Empty value (a delimiter followed by nothing) is used to delete a given attribute in device server.
       Attribute-value pairs in command line arguments containing spaces should be quoted or escaped.

       Report bugs to <dgilbert at interlog dot com>.

sg_read_attrs(sg3_utils)

sg3_utils-1.48                                    January 2023                                  SG_WRITE_ATTR(8)

sg_write_attr  [--enumerate]  [--element=EA]  [--help]  [--hex]  [--in=FN]  [--lvn=LVN] [--pn=PN] [--raw]
       [--wtc] [--verbose] [--version] DEVICE [attribute=value [attribute:value...]]