sg_write_attr - Man Page
send SCSI WRITE ATTRIBUTE command
Synopsis
sg_write_attr [--enumerate] [--element=EA] [--help] [--hex] [--in=FN] [--lvn=LVN] [--pn=PN] [--raw] [--wtc] [--verbose] [--version] DEVICE [attribute=value [attribute:value...]]
Description
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).
Options
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=FN
FN 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-value pair format
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.
Notes
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).
Examples
Set a tape barcode ASCII attribute specified by acronym and a string value:
# sg_write_attr /dev/sg1 BarCode=BARCODE01
Set a tape barcode ASCII attribute specified by hexadecimal identifier and a string value:
# sg_write_attr /dev/sg1 0x806=BARCODE01
Set a user label text attribute with string value containing spaces in quoted command line argument:
# sg_write_attr /dev/sg1 "UserLabel=User label 1"
Set a user label text attribute with hex sequence value:
# sg_write_attr /dev/sg1 UserLabel:42,41,52,43,4F,44,45,30,32
or
# sg_write_attr /dev/sg1 "0x803:42 41 52 43 4F 44 45 30 32"
Set a locale identifier attribute with values specified by acronyms or numbers:
# sg_write_attr /dev/sg1 LocaleId=ascii
# sg_write_attr /dev/sg1 LocaleId=utf-8
# sg_write_attr /dev/sg1 LocaleId=0x80
# sg_write_attr /dev/sg1 LocaleId:81
# sg_write_attr /dev/sg1 0x805=iso-8859-9
Set multiple attributes specified in command line arguments:
# sg_write_attr /dev/sg1 BarCode=BARCODE01 "UserLabel=My User Label" LocaleId=iso-8859-1
Set variable-length binary attribute with values in numerical or hex sequence formats:
# sg_write_attr /dev/sg1 VCI=1
# sg_write_attr /dev/sg1 VCI=65535
# sg_write_attr /dev/sg1 VCI=0x012345
# sg_write_attr /dev/sg1 VCI=0x0123456789abcdef
# sg_write_attr /dev/sg1 VCI: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:63 38 66 36 62 39 32 32 2d 37 38 38 39 2d 31 31 65 64 2d 38 65 35 31 2d 66 37 36 65 62 32 63 39 38 38 64 31"
Delete an attribute using empty value:
# sg_write_attr /dev/sg1 BarCode=
or
# sg_write_attr /dev/sg1 BarCode:
Delete multiple attributes:
# sg_write_attr /dev/sg1 UserLabel= 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.15
UserLabel=User Label 1
LastWritten=251120221637
Barcode=BARCODE02
OwningHost=backup_server
MediaPoolName=First Media Pool
PartUserLabel=PART01
LUatPart=1
AppFmtVersion=MTF0125
VCI=0x0123456789abcdef
MediumGUID:62 64 61 36 62 30 35 34 2d 37 38 38 39 2d 31 31 65 64 2d 39 65 64 30 2d 62 37 31 30 63 32 62 63 30 34 30 39
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:
00 00 00 25 08 06 01 00 20 42 41 52 43 4f 44 45
2d 30 32 20 20 20 20 20 20 20 20 20 20 20 20 20
20 20 20 20 20 20 20 20 20
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 -A x -t x1z -v attrs_raw.bin
000000 00 00 00 25 08 06 01 00 20 42 41 52 43 4f 44 45 >...%.... BARCODE<
000010 2d 30 32 20 20 20 20 20 20 20 20 20 20 20 20 20 >-02 <
000020 20 20 20 20 20 20 20 20 20 > <
000029
Exit Status
The exit status of sg_write_attr is 0 when it is successful. Otherwise see the sg3_utils(8) man page.
Authors
Written by Douglas Gilbert and Boris Fox.
Reporting Bugs
Report bugs to <dgilbert at interlog dot com>.
Copyright
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.
See Also
sg_read_attrs(sg3_utils)