NAME

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