FreeBSD Manual Pages
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 [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 ap- plicable 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 identi- fier, length, format and a name as defined by T10, with supple- mentary 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 in- put 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 log- ical 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 in- put 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 at- tribute value, delimited by an equal sign '=' or a colon ':'. At- tribute identifier can be specified as a number in decimal, octal (pre- fixed 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 numeri- cal format, or acronym, while a colon sign denotes a hex sequence com- prised 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. Avail- able acronyms can be listed by the --enumerate options. Acronyms are case-insensitive. For the fixed-length binary attributes, value length must match at- tribute 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 de- vice 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 >...%.... BAR- CODE< 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 war- ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR- POSE. 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+14.3.quarterly>