SG_WRITE_ATTR(8) SG3_UTILS SG_WRITE_ATTR(8) 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 [at- tribute=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 AT- TRIBUTE 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 at- tribute-value pairs one per line, ASCII hexadecimal or binary repre- senting 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 charac- ters 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 out- put. -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 mem- ory. 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 hexa- decimal (prefixed by '0x') representation, or with an acronym if the at- tribute 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-insen- sitive. 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 at- tribute 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 com- mand 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 num- bers: # 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" Lo- caleId=iso-8859-1 Set variable-length binary attribute with values in numerical or hex se- quence 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 (C) 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) sg3_utils-1.48 January 2023 SG_WRITE_ATTR(8)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | EXAMPLES | EXIT STATUS | AUTHORS | REPORTING BUGS | COPYRIGHT | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=sg_write_attr&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>