title: sg_start(8)

text:
# sg_start(8)

## NAME
sg_start - send SCSI START STOP UNIT command: start, stop, load or eject medium

## SYNOPSIS
sg_start [0] [1] [--eject] [--help] [--fl=FL] [--immed] [--load] [--loej] [--mod=PC_MOD] [--noflush] [--pc=PC] [--readonly] [--start] [--stop] [--verbose] [--version] DEVICE

sg_start [--eject] [--fl=FL] [-i] [--imm=0|1] [--load] [--loej] [--mod=PC_MOD] [--noflush] [--pc=PC] [-r] [--start] [--stop] [-v] [-V] [0|1] DEVICE

## DESCRIPTION
sg_start sends a SCSI START STOP UNIT command to the DEVICE with the selected options. The most used options are --stop to spin down a disk and --start to spin up a disk. Using --start on a disk that is already spinning is harmless. There is also finer grain control with "power condition": active, idle or standby. This is set with the --pc=PC option. In some contexts the "stop" state can be considered an additional power condition.

Devices that contain removable media such as cd/dvds can use the --loej option to load the medium when used in conjunction with --start (i.e. load medium then spin up). Alternatively --loej may be used to eject the medium when used in conjunction with --stop (i.e. spin down then eject medium). More simply, the loading or ejecting of a removable medium can be requested with the --load or --eject' option.

If no option or argument is given then a --start is assumed; as the utility's name suggests.

This utility supports two command line syntaxes, the preferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options.

Linux note: best not to use a standard block device name (e.g. /dev/sdc) with the --stop option. Use a sg or bsg device node instead (see lsscsi(8) ). The block layer will sometimes notice the disk spinning down and decide: "that's not right" and spin it up again!

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

0

same action as --stop.

1

same action as --start.

-e, --eject

stop the medium and eject it from the drive. Only appropriate for a device with removable medium. Might be ignored (prevented), see below. Note, this is an operation that can be done on a tape drive or CD/DVD/BD player, not on a hard disk or SSD!

-h, --help

print out the usage message then exit.

-f, --fl=FL

sets the format layer number for the disc to "jump" to (defined in MMC-5). Values of FL can be 0 to 3. When this option is chosen, the FL, LoEj and Start bits are set in the cdb as required by MMC-5; thus the user does not need to set the --start and/or --load options.

-i, --immed

sets the IMM bit on the START STOP UNIT command so this utility will return immediately and not wait for the media to complete the requested action. The default is to wait until the media to complete the requested action before returning.

-l, --load

load the medium in the drive and start it. Only appropriate for a removable medium.

-L, --loej

sets the LOEJ bit on the START STOP UNIT command. This loads the media when the unit is started or eject it when the unit is stopped (i.e. works in conjunction with START bit in cdb). This option is ignored if 'pc > 0'. Default is off (i.e. don't attempt to load or eject media). If a start/start indication is not given (i.e. neither --start nor --stop) and this option is given then a load and start action is assumed.

-m, --mod=PC_MOD

where PC_MOD is the 'power condition modifier' value. 0 to 15 (inclusive) are valid and 0 is the default. This 'power condition modifier' field in the cdb was added after sbc3r13.

-n, --noflush

do not perform a flush to media (e.g. like SYNCHRONIZE CACHE does) before a variant of this utility that limits access to the media. Using the --stop option is an example of something that limits access to the media. This 'noflush' field in the cdb was added after sbc3r13.

-O, --old

Switch to older style options. Please use as first option.

-p, --pc=PC

where PC is the 'power conditions' value. 0 to 15 (inclusive) are valid. Default value is 0. When '--pc=0' then --eject, --load, --loej, --start and --stop are active. Some common values are 1 for the "active" power condition (SBC); 2 for the idle power condition; 3 for the standby power condition; 5 for sleep power condition (MMC); 7 for LU_CONTROL (SBC), 0xa (decimal 10) for FORCE_IDLE_0 (SBC) and 0xb (decimal 11) for FORCE_STANDBY_0 (SBC). See recent SBC-3, MMC-5 and SAS drafts at www.t10.org for more information.

-r, --readonly

open the DEVICE in read-only mode. Maybe required in Linux to stop a nuisance spin-up if the DEVICE is an ATA disk. The nuisance spin-up may occur at the end of this command negating the effect of the --stop option.

-s, --start

start (spin-up) the DEVICE. This sets the START bit in the cdb. Using this option on an already started device is harmless. In the absence of other options, this option defaults (i.e. set the START cdb bit).

-S, --stop

stop (spin-down) the DEVICE. This clears the START bit in the cdb. This operation is typically done on a hard disk or SSD. In the case of a SSD it will be placed in low power mode and may need a start operation later before normal IO can resume.

-v, --verbose

increase the level of verbosity. Can be used multiple times.

-V, --version

print out version string then exit.

## NOTES
To avoid confusion, only one of 0, 1 --eject, --load, --start and --stop should be given.

There is an associated "power condition" mode page (0x1a) in which timer values can be set for transitioning to either idle or standby state after a period of inactivity. The sdparm utility can be used to view the power condition mode page and if required change it. If a DEVICE is in either idle or standby power condition state then a REQUEST SENSE command (see the sg_requests utility) should yield a sense key of "no sense" and an additional sense code of "Low power condition on" on recent SCSI devices.

Ejection of removable media (e.g. 'sg_start --eject /dev/hdd' where the DEVICE is an ATAPI cd/dvd drive) may be prevented by a prior SCSI PREVENT ALLOW MEDIUM REMOVAL command (see sg_prevent). In this case this utility should fail with an error generated by the device: illegal request / medium removal prevented. This can be overridden using sg_prevent or, for example, 'sdparm --command=unlock /dev/hdd'.

The SCSI TEST UNIT READY command can be used to find out whether a DEVICE is ready to transfer data. If rotating media is stopped or still coming up to speed, then the TEST UNIT READY command will yield a "not ready" sense key and an more informative additional sense code. See the sg_turs utility.

In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD drives) can also be specified. For example "sg_start 0 /dev/sda" will work in the 2.6 series kernels.

In the Linux 2.6 series, especially with ATA disks, using this utility to stop (spin down) a disk may not be sufficient and other mechanisms will start the disk again some time later. The user might additionally mark the disk as "offline" with 'echo offline > /sys/block/sda/device/state' where sda is the block name of the disk. To restart the disk "offline" can be replaced with "running". Note that once the 'state' is set to offline, no SCSI commands can be sent to the device until it is set back to running. Also stopping a disk via a pass-through interface (e.g. /dev/sg1 or /dev/bsg/1:0:0:0) may reduce unwanted side effects (such as restarting it again when this utility completes).

## EXIT STATUS
The exit status of sg_start is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## OLDER COMMAND LINE OPTIONS
The options in this section were the only ones available prior to sg3_utils version 1.23 . Since then this utility defaults to the newer command line options which can be overridden by using --old (or -O) as the first option. See the ENVIRONMENT VARIABLES section for another way to force the use of these older command line options.

Note that the action of --loej is slightly different in the older interface: when neither --start nor --stop (nor proxies for them) are given, --loej performs an eject operation. In the same situation the newer interface will perform a load operation.

Earlier versions of sg_start had a '-s' option to perform a SYNCHRONIZE CACHE command before the START STOP UNIT command was issued. According to recent SBC-2 drafts this is done implicitly if required. Hence the '-s' option has been dropped.

All options, other than '-v' and '-V', can be given with a single "-". For example: "sg_start -stop /dev/sda" and "sg_start --stop /dev/sda" are equivalent. The single "-" form is for backward compatibility.

0

stop (spin-down) DEVICE.

1

start (spin-up) DEVICE.

--eject

stop the medium and eject it from the drive.

--fl=FL

sets the format layer number for the disc to "jump" to (defined in MMC-5).

-i

sets the IMM bit on the START STOP UNIT command so this utility will return immediately and not wait for the media to spin down. Same effect as '--imm=1'. The default action (without this option or a '--imm=1' option) is to wait until the media spins down before returning.

--imm=0|1

when the immediate bit is 1 then this utility returns immediately after the DEVICE has received the command. When this option is 0 (the default) then the utility returns once the command has completed its action (i.e. it waits until the device is started or stopped).

--load

load the medium in the drive and start it.

--loej

sets the LOEJ bit in the START STOP UNIT cdb. When a "start" operation is indicated, then a load and start is performed. When a "stop" operation is indicated, then a stop and eject is performed. When neither a "start" or "stop" operation is indicated does a stop and eject. [Note that the last action differs from the new interface in which the option of this name defaults to load and start.]

-N, --new

Switch to the newer style options.

--mod=PC_MOD

where PC_MOD is the 'power condition modifier' value. 0 to 15 (inclusive) are valid and 0 is the default. This field was added after sbc3r13.

--noflush

do not perform a flush to media (e.g. like SYNCHRONIZE CACHE does) before a variant of this utility that limits access to the media. Using the --stop option is an example of something that limits access to the media. This field was added after sbc3r13.

--pc=PC

where PC is the 'power condition' value (in hex). 0 to f (inclusive) are valid. Default value is 0.

-r

see the --readonly option above. May be useful for ATA disks.

--start

start (spin-up) DEVICE.

--stop

stop (spin-down) DEVICE. Same meaning as "0" argument.

-v

verbose: outputs SCSI command in hex to console before with executing it. '-vv' and '-vvv' are also accepted yielding greater verbosity.

-V

print out version string then exit.

## ENVIRONMENT VARIABLES
Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS can be given. When it is present this utility will expect the older command line options. So the presence of this environment variable is equivalent to using --old (or -O) as the first command line option.

## AUTHOR
Written by K. Garloff and D. Gilbert

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2002-2021 Kurt Garloff, Douglas Gilbert

This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_prevent(sg3_utils), sg_requests(sg3_utils), sg_turs(sg3_utils) sdparm(sdparm), lsscsi(lsscsi)


title: sg_stpg(8)

text:
# sg_stpg(8)

## NAME
sg_stpg - send SCSI SET TARGET PORT GROUPS command

## SYNOPSIS
sg_stpg [--active] [--help] [--hex] [--offline] [--optimized] [--raw] [--standby] [--state=S,S...] [--tp=P,P...] [--unavailable] [--verbose] [--version] DEVICE

## DESCRIPTION
Send a SCSI SET TARGET PORT GROUPS command to DEVICE. This utility has different modes depending on whether the --tp= option is given.

If --tp= is given then the SET TARGET PORT GROUPS command parameter block is built with a descriptor for each element in the list given to --tp=. The corresponding asymmetric access state value is either taken from the --state= list or, if that is not given, from one of the explicit state options (e.g. --unavailable), used repeatedly if required.

If --tp= is not given then a sequence of SCSI commands are sent to the DEVICE leading up to the SET TARGET PORT GROUPS command. First an INQUIRY is sent to fetch the device identification VPD page to find the (primary) target port group associated with DEVICE. Then a REPORT TARGET PORT GROUPS command is issued to find the current state and whether a transition to the requested state is supported. If so the SET TARGET PORT GROUPS command is sent.

Target port group access is described in SPC-4 found at www.t10.org in sections 5.8 and 5.16 (in rev 36e dated 2012/8/24). The SET TARGET PORT GROUPS command is also described in section 6.45 of that document.

## OPTIONS
Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name.

-a, --active

set active/non-optimized state.

-h, --help

output the usage message then exit.

-H, --hex

output response to the REPORT TARGET PORT GROUPS command in hex then exit.

-O, -l, --offline

set offline state. This is the appropriate state to set a target port to prior to removing the device. Note that a relative target port identifier should be given with this state (rather than a target port group identifier that all other states take).

-o, --optimized

set active/optimized state. If no other state options or --tp= option are given then active/optimized is the default state.

-r, --raw

output response to the REPORT TARGET PORT GROUPS command in binary to stdout then exit.

-s, --standby

set standby state. Port group shall accept those commands listed for "unavailable" state plus LOG SELECT/SENSE, MODE SELECT/SENSE, RECEIVE DIAGNOSTIC RESULTS, SEND DIAGNOSTIC, PERSISTENT RESERVE IN/OUT commands.

-S, --state=S,S...

specifies a comma separated list (one element of more) of states. Either a number or an abbreviation can be given. A number is assumed to be a decimal number unless it is prefixed by "0x" or has a trailing "h" in which case a hexadecimal value is assumed. Only the values 0, 1, 2, 3 or 14 are accepted. The accepted abbreviations are "an", "ao", "o", "s" or "u"; which represent active/non-optimized(1), active/optimized(0), offline(14), standby(2) or unavailable(3) respectively.

-t, --tp=P,P...

specifies a comma separated list (one element of more). Each elements is either a target port group identifier (when the corresponding state is other than "offline") or a relative target port identifier (when the corresponding state is "offline"). Each element is assumed to be a decimal number unless it is prefixed by "0x" or has a trailing "h" in which case a hexadecimal value is assumed.

-u, --unavailable

set unavailable state. Port group shall only accept INQUIRY, REPORT LUNS, REPORT/SET TARGET PORT GROUPS, REQUEST SENSE and READ/WRITE BUFFER commands.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
The SET TARGET PORT GROUPS command should be supported whenever the TPGS value in a standard INQUIRY response is 2 or 3. [View with sg_inq utility.]

Notice that the offline state is termed as a "secondary target port asymmetric access state" and takes a relative target port identifier (i.e. acts on a single target port). All the other states are termed as "primary target port asymmetric access states" and each takes a target port group identifier (i.e. acts on one or more target ports).

When --tp= is given then the same number of elements should be given to the --state= option. If more than one list element is given to --tp= and an equal number of elements is _not_ given to the --state= option, then if only one state is specified then it is repeated.

## EXIT STATUS
The exit status of sg_stpg is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2007-2014 Hannes Reinecke, Christophe Varoqui and D Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_inq, sg_rtpg (sg3_utils)

branch: sisyphus


title: sg_stream_ctl(8)

text:
# sg_stream_ctl(8)

## NAME
sg_stream_ctl - send SCSI STREAM CONTROL or GET STREAM STATUS command

## SYNOPSIS
sg_stream_ctl [--brief] [--close] [--ctl=CTL] [--get] [--help] [--id=SID] [--maxlen=LEN] [--open] [--readonly] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SCSI STREAM CONTROL or GET STREAM STATUS command to the DEVICE. These commands, together with WRITE STREAM(16 and 32) and several fields in the Block Limits Extension VPD page [0xb7] support the streams concept. The stream commands were added in SBC-4 draft 8 (September 2015).

Both STREAM CONTROL and GET STREAM STATUS commands expect data from the DEVICE (referred to as 'data-in'). In the case of STREAM CONTROL only the 'open' (STR_CTL<--0x1) actually needs the data-in as it contains the "Assigned stream id" if the open was successful. The assigned stream id should be used by subsequent WRITE STREAM commands and ultimately by the STREAM CONTROL close (STR_CTL<--0x2). Valid stream ids are between 1 and 65535 inclusive.

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

-b, --brief

this option reduces the output of the GET STREAM STATUS command to just one number (in decimal) per line sent to stdout. Those numbers are the currently open stream ids. If an error occurs then -1 is sent to stdout and error related messages are sent to stderr. The default is to print more words (and fields) from the GET STREAM STATUS response.

-c, --close

selects the STREAM CONTROL command and sets STR_CTL<--0x2 (i.e. 'close'). The --id=SID option should also be given because it defaults to 0 which is not a valid stream id.

-C, --ctl=CTL

CTL is the value placed in the STR_CTL field of the STREAM CONTROL command (cdb). It is a two bit field so has 4 variants: 0 and 3 are reserved; 1 opens are new stream and 2 closes the given stream id. '--ctl=1' is equivalent to '--open' while '--ctl=2' is equivalent to '--close'.

-g, --get

selects the GET STREAM STATUS command. If the --id=SID option is also given the the response starts lists open stream ids from and including SID. If the --id=SID option is not given (or SID is 0) then all open stream id will be returned in the response (data-in) as long as the allocation length (defaults to 248 bytes which can be overridden by the --maxlen=LEN option) is long enough. This is the default action of this utility (i.e. GET STREAM STATUS command) if no "selecting" options are given.

-h, --help

output the usage message then exit.

-i, --id=SID

SID is a stream id, a value between 1 and 65535. It is used by STREAM CONTROL (close) to identify the stream to close. It is used by the GET STREAM STATUS command as the starting stream id (from and including); so stream ids that are less than SID will not appear in the response.

-m, --maxlen=LEN

LEN is the maximum length the response can be. It becomes the ALLOCATION LENGTH field in both commands. The default (in the absence of this option) is 8 bytes for STREAM CONTROL and 248 bytes for GET STREAM STATUS.

-o, --open

selects the STREAM CONTROL command and sets STR_CTL<--0x1 (i.e. 'open'). If the --id=SID option is given then it is ignored. The user should observe the response as the "Assigned stream id" is printed on stdout if the open is successful, if not '-1' is sent to stdout and error messages are sent to stderr. If the --brief option is also given then the only thing sent to stdout is a number of the assigned stream id (1 to 65535 inclusive) or '-1' if there is an error.

-r, --readonly

this option sets a 'read-only' flag when the underlying operating system opens the given DEVICE. This may not work since operating systems can not easily determine whether a pass-through command is a logical read or write operation on the media (or its metadata) so they take a risk averse stance and require read-write type permissions on the DEVICE open irrespective of what is performed by the pass-through.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
There are no special read commands for streams. This implies that "normal" READs (6, 10, 12, 16 or 32) can be used. Note that when a stream is closed, all resources associated with that stream id are removed, apart from the data in the written LBAs. To make sure the reading back data is not delayed too much by error recovery (in the presence of media errors) the user may set the RECOVERY TIME LIMIT field (RTL, units for non-zero values: milliseconds) in the 'Read-write error recovery' mode page. This can be done with the sdparm utility.

The SCSI WRITE STREAM (16 and 32) commands can be found in the sg_write_x utility in this package.

## EXIT STATUS
The exit status of sg_stream_ctl is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2018 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_vpd,sg_write_x(sg3_utils); sdparm(sdparm)


title: sg_sync(8)

summary: send SCSI SYNCHRONIZE CACHE command

text:
# sg_sync(8)

## NAME
sg_sync - send SCSI SYNCHRONIZE CACHE command

## SYNOPSIS
sg_sync [--16] [--count=COUNT] [--group=GN] [--help] [--immed] [--lba=LBA] [--sync-nv] [--timeout=SECS] [--verbose] [--version] DEVICE

## DESCRIPTION
Send SYNCHRONIZE CACHE(10) or SYNCHRONIZE CACHE(16) command to DEVICE. These commands are defined for SCSI block devices (see SBC-3). If successful these commands make sure that any blocks whose latest versions are held in cache are written to (also termed as "synchronized with") the medium.

If the LBA and COUNT arguments are both zero (their defaults) then all blocks in the cache are synchronized. If LBA is greater than zero while COUNT is zero then blocks in the cache whose addresses are from and including LBA to the highest lba on the device are synchronized. If both LBA and COUNT are non zero then blocks in the cache whose addresses lie in the range LBA to LBA+COUNT-1 inclusive are synchronized with the medium.

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

-S, --16

performs a SYNCHRONIZE CACHE(16) command. Default is to perform a SYNCHRONIZE CACHE(10) command.

-c, --count=COUNT

where COUNT is the number of blocks to synchronize from and including LBA. Default value is 0. When 0 then all blocks in the cache from and including LBA argument to the highest block address are synchronized.

-g, --group=GN

where GN is the group number which can be between 0 and 63 inclusive. The default value is 0 . Group numbers are used to segregate data collected within the device. This is a new feature in SBC-2 and can probably be ignored for the time being.

-h, --help

output the usage message then exit.

-i, --immed

sets the IMMED bit in the SYNCHRONIZE CACHE command. This instructs the device, if the format of the command is acceptable, to return a GOOD status immediately rather than wait for the blocks in the cache to be synchronized with (i.e. written to) the medium.

-l, --lba=LBA

where LBA is the lowest logical block address in the cache to synchronize to the medium. Default value is 0 .

-s, --sync-nv

synchronize the (volatile) cache with the non-volatile cache. Without this option (or if there is no non-volatile cache in the device) the synchronization is with the medium. The SYNC_NV bit was made obsolete in SBC-3 revision 35d.

-t, --timeout=SECS

where SECS is the number of seconds the OS allows the SYNCHRONIZE CACHE(16) to complete before it tries to cancel the command. Cancelling commands (typically with the task management function "abort task") is best avoided. Note this option is only active together with the --16 option. The default timeout is 60 seconds for both SYNCHRONIZE CACHE(10) and SYNCHRONIZE CACHE(16). Note that timeout issues can be avoided with the --immed option.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
With the SYNCHRONIZE CACHE(16) command LBA can be up to 64 bits in size and COUNT up to 32 bits in size. With the SYNCHRONIZ CACHE(10) command LBA can be up to 32 bits in size and COUNT up to 16 bits in size.

Various numeric arguments (e.g. LBA) may include multiplicative suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section in the sg3_utils(8) man page.

## EXIT STATUS
The exit status of sg_sync is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2004-2018 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_start(sg3_utils)


title: sg_test_rwbuf(8)

text:
# sg_test_rwbuf(8)

## NAME
sg_test_rwbuf - test a SCSI host adapter by issuing dummy writes and reads

## SYNOPSIS
sg_test_rwbuf [--addrd=AR] [--addwr=AW] [--help] [--quick] --size=SZ [--times=NUM] [--verbose] [--version] DEVICE

or an older deprecated format sg_test_rwbuf DEVICE SZ [AW] [AR]

## DESCRIPTION
sg_test_rwbuf writes and reads back SZ bytes to the internal buffer of DEVICE (e.g. /dev/sda or /dev/sg0). A pseudo random pattern is written to the data buffer on the device then read back. If the same pattern is found 'Success' is reported. If they do not match (checksums unequal) then this is reported and up to 24 bytes from the first point of mismatch are reported; the first line shows what was written and the second line shows what was received. For testing purposes, you can ask it to write AW or read AR additional bytes.

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

-r, --addrd=AR

Read an additional AR bytes (more than indicated by SZ) from the data buffer. Checksum is performed over the first SZ bytes.

-w, --addwr=AW

Write an additional AW bytes (more than indicated by SZ) of zeros into the data buffer. Checksum is generated over the first SZ bytes.

-h, --help

Print out a usage message the exit.

-q, --quick

Perform a READ BUFFER descriptor command to find out the available data buffer length and offset, print them out then exit (without testing with write/read sequences).

-s, --size=SZ

where SZ is the size of buffer in bytes to be written then read and checked. This number needs to be less than or equal to the size of the device's data buffer which can be seen from the --quick option. Either this option or the --quick option should be given.

-t, --times=NUM

where NUM is the number of times to repeat the write/read to buffer test. Default value is 1 .

-v, --verbose

increase verbosity of output.

-V, --version

print version number (and data of last change) then exit.

## NOTES
The microcode in a SCSI device is _not_ modified by doing a WRITE BUFFER command with its mode set to "data" (0x2) as done by this utility. Therefore this utility is safe in that respect. [Mode values 0x4, 0x5, 0x6 and 0x7 are the dangerous ones :-)]

WARNING: If you access the device at the same time (e.g. because it's a hard disk with a mounted file system on it) the device's buffer may be used by the device itself for other data at the same time, and overwriting it may or may not cause data corruption! HOWEVER the SPC-3 draft standard does state in its WRITE BUFFER command: "This command shall not alter any medium of the logical unit when data mode ... is specified". This implies that it _is_ safe to use this utility with devices that have mounted file systems on them. Following this theme further, a disk with active mounted file systems may cause the data read back to be different (due to caching activity) to what was written and hence a checksum error.

## EXIT STATUS
The exit status of sg_test_rwbuf is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by D. Gilbert and K. Garloff

## COPYRIGHT
Copyright © 2000-2018 Douglas Gilbert, Kurt Garloff

This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


title: sg_timestamp(8)

summary: report or set timestamp on SCSI device

text:
# sg_timestamp(8)

## NAME
sg_timestamp - report or set timestamp on SCSI device

## SYNOPSIS
sg_timestamp [--elapsed] [--help] [--hex] [--milliseconds=MS] [--no-timestamp] [--origin] [--raw] [--readonly] [--seconds=SECS] [--srep] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SCSI REPORT TIMESTAMP or SET TIMESTAMP command to the DEVICE. These commands are found in the SPC-5 draft standard revision 7 (spc5r07.pdf).

If either the --milliseconds=MS or --seconds=SECS option is given (and both can't be given) then the SET TIMESTAMP command is sent; otherwise the REPORT TIMESTAMP command is sent.

The timestamp is sent and received from the DEVICE as the number of milliseconds since the epoch of 1970-01-01 00:00:00 UTC and is held in a 48 bit unsigned integer. That same epoch is used by Unix machines, but they usually hold the number of seconds since that epoch. The Unix date command and especially its "+%s" format is useful in converting to and from timestamps and more humanly readable forms. See the EXAMPLES section below.

A companion utility called sg_sat_datetime with similar options is available to access or set the date and time in an ATA device (typically a SATA disk). sg_sat_datetime issues ATA commands via the SCSI to ATA Translation (SAT) layer.

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

-e, --elapsed

assume the timestamp in the REPORT TIMESTAMP is an elapsed time from an event such as a power cycle or hard reset and format the output as '<n> days hh:mm:ss.xxx' where hh is hours (00 to 23 inclusive); mm is minutes (00 to 59 inclusive); ss is seconds (00 to 59 inclusive) and xxx is milliseconds (000 to 999 inclusive). If the number of days is 0 then '0 days' is not output unless this option is given two or more times.

-h, --help

output the usage message then exit.

-H, --hex

output the response to REPORT TIMESTAMP in ASCII hexadecimal on stderr. The response is not decoded.

-m, --milliseconds=MS

where MS is the number of milliseconds since 1970-01-01 00:00:00 UTC to set in the DEVICE with the SCSI SET TIMESTAMP command.

-N, --no-timestamp

when REPORT TIMESTAMP is called this option suppress the output of the timestamp value (in either seconds or milliseconds). This may be useful in uncluttering the output when trying to decode the timestamp origin (see the --origin option).

-o, --origin

the REPORT TIMESTAMP returned parameter data contains a "timestamp origin" field. When this option is given, that field is decoded and printed out before the timestamp value is output. The default action (i.e. when the option is not given) is not to print out this decoded field.

T10 defines this field as "the most recent event that initialized the returned device clock". The value 0 indicates a power up of hard reset initialized the clock; 2 indicates a SET TIMESTAMP initialized the clock while 3 indicates some other method initialized the clock.

When used once a descriptive string is output (in a line before the timestamp value). When used twice the value of the TIMESTAMP ORIGIN field is output (in decimal, a value between 0 and 7 inclusive). When used thrice a line of the form 'TIMESTAMP_ORIGIN=<value>' is output.

-r, --raw

output the SCSI REPORT TIMESTAMP response (i.e. the data-out buffer) in binary (to stdout). Note that the --origin and --srep options are ignored when this option is given. Also all error and verbose messages are output to stderr.

-R, --readonly

open the DEVICE read-only. The default action is to open the DEVICE read-write.

-s, --seconds=SECS

where SECS is the number of seconds since 1970-01-01 00:00:00 UTC to set in the DEVICE with the SCSI SET TIMESTAMP command. SECS is multiplied by 1000 before being used in the SET TIMESTAMP command.

-S, --srep

report the number of seconds since 1970-01-01 00:00:00 UTC. This is done by dividing by 1000 the value returned by the SCSI REPORT TIMESTAMP command.

-v, --verbose

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

-V, --version

print the version string and then exit.

## EXIT STATUS
The exit status of sg_timestamp is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## NOTES
The TCMOS and the SCSIP bits in the Control extension mode page (see sdparm) modify the actions of the timestamp held by a DEVICE.

Currently only the "Utilization usage rate based on date and time" parameters within the Utilization log page (sbc4r09.pdf) use timestamps. See the sg_logs utility. Vendor specific commands and pages may also be using timestamps.

## EXAMPLES
On Unix machines (e.g. Linux, FreeBSD and Solaris) the date command is useful when working with timestamps.

To fetch the timestamp from a DEVICE and display it in a humanly readable form the following could be used:

\# sg_timestamp -S /dev/sdb

1448993950

\# date --date=@1448993950

Tue Dec 1 13:19:10 EST 2015

\# date -R --date="@1448993950"

Tue, 01 Dec 2015 13:19:10 -0500

The latter two date commands show different forms of the same date (i.e. 1448993950 seconds since 1970-01-01 00:00:00 UTC). The sg_timestamp and date commands can be combined using backquotes:

\# date -R --date=@`sg_timestamp -S /dev/sdc`

Wed, 16 Dec 2015 20:12:59 -0500

To set the timestamp on the DEVICE to now (approximately) the following could be used:

\# date +%s

1448993955

\# sg_timestamp --seconds=1448993955 /dev/sdb

Those two command lines could be combined into one by using backquotes:

\# sg_timestamp --seconds=`date +%s` /dev/sdb

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2015-2018 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sdparm(sdparm), sg_logs(sg3_utils), sg_sat_datetime(sg3_utils)


title: sg_turs(8)

text:
# sg_turs(8)

## NAME
sg_turs - send one or more SCSI TEST UNIT READY commands

## SYNOPSIS
sg_turs [--ascq=ASC[,ASQ]] [--delay=MS] [--help] [--low] [--num=NUM] [--number=NUM] [--progress] [--time] [--timeout=SE] [--verbose] [--version] DEVICE

sg_turs [-d=MS] [-n=NUM] [-p] [-t] [-v] [-V] DEVICE

## DESCRIPTION
This utility sends one or more SCSI TEST UNIT READY commands to the DEVICE. This may be useful for timing the per command overhead. Note that TEST UNIT READY has no associated data, just a 6 byte command (with each byte a zero) and a returned SCSI status value.

This utility supports two command line syntaxes, the preferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options.

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

-a, --ascq=ASC[,ASQ]

checks the sense data associated with a sense key of NOT READY. If there is a match on ASC and, if given, with ASQ then this utility sets its exit status to 36. That is an alternate good code because an exit status of 0 would imply the unit is ready.

The reason this option was added is USB card readers (e.g. SD card readers) that often yield an additional sense code of 0x3a,0x0 for "no medium present" when there is no SD card in the reader. There are variations of additional sense code 0x3a so it is best not to give the ASQ value so any ascq code will match.

-d, --delay=MS

this option causes a delay of MS milliseconds to occur before each TEST UNIT READY command is issued.

-h, --help

print out the usage message then exit.

-l, --low

when [--progress] is not being used, this utility tries to complete the SCSI TEST UNIT READY command(s) as quickly as possible. Usually it calls a library function to do each TUR (sg_ll_test_unit_ready). With this option it uses the lower level sg_pt interface (see sg_pt.h) to save a little time on each TUR.

-n, --num=NUM

performs TEST UNIT READY NUM times. If not given defaults to 1. These suffix multipliers are permitted: c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576; MB *1,000,000; g G GiB *1,073,741,824; and GB *1,000,000,000 . Also a suffix of the form "x<n>" multiplies the leading number by <n>. Alternatively a hex number may be given, prefixed by either '0x' or has a trailing 'h'.

--number=NUM

same as --num=NUM. Added for compatibility with sg_requests and other utilities in this package. The sg_request utility has taken over the role of polling the progress indication which was originally assigned to the TEST UNIT READY command. This is a change by T10.

-O, --old

Switch to older style options. Please use as first option.

-p, --progress

show progress indication (a percentage) if available. If --num=NUM is given, NUM is greater than 1 and an initial progress indication was detected then this utility waits 30 seconds before subsequent checks. If the --delay=MS option is given then it will wait for that number of milliseconds instead of 30 seconds. Exits when NUM is reached or there are no more progress indications. Ignores --time option. See NOTES section below.

-t, --time

after completing the requested number of TEST UNIT READY commands, outputs the total duration and the average number of commands executed per second.

-T, --timeout=SE

where SE is the command timeout of each TEST UNIT READY command. The unit for SE is seconds and if 0 is given, it is mapped to 60 seconds which is the default. An alternate long option form is --tmo=SE.

-v, --verbose

increase level or verbosity.

-V, --version

print version string then exit.

## NOTES
The progress indication is optionally part of the sense data. When a prior command that takes a long time to complete (and typically precludes other media access commands) is still underway, the progress indication can be used to determine how long before the device returns to its normal state. Around SPC-3 T10 changed the preferred command for polling the progress indication from TEST UNIT READY to REQUEST SENSE (see the sg_requests utility).

The SCSI FORMAT command for disks used with the IMMED bit set is an example of an operation that takes a significant amount of time and precludes other media access during that time. The IMMED bit set instructs the FORMAT command to return control to the application client once the format has commenced (see SBC-3). Several long duration SCSI commands associated with tape drives also use the progress indication (see SSC-3).

The DEVICE is opened with a read-only flag (e.g. in Unix with the O_RDONLY flag).

Early standards suggested that the SCSI TEST UNIT READY command be used for polling the progress indication. More recent standards seem to suggest the SCSI REQUEST SENSE command should be used instead.

## EXIT STATUS
The exit status of sg_turs is 0 when it is successful (e.g. in the case of a mechanical disk, it is spun up and ready to accept IO commands). For this utility the other exit status values of interest are 2, 12, 13 and 36. 12 is for the case when the sense key is "not ready" [0x2] and the additional sense code ends with "Target port in standby state" [0x4, 0xb]. 13 is for the case when the sense key is "not ready" [0x2] and the additional sense code is "Target port in unavailable state" [0x4, 0xc]. The exit status of 36 is associated with --ascq=ASC[,ASQ] option. All other cases when the sense key is "not ready" [0x2] will set the exit status to 2. For other exit status values see the sg3_utils(8) man page.

## OLDER COMMAND LINE OPTIONS
The options in this section were the only ones available prior to sg3_utils version 1.23 . Since then this utility defaults to the newer command line options which can be overridden by using --old (or -O) as the first option. See the ENVIRONMENT VARIABLES section for another way to force the use of these older command line options.

-d, --delay=MS

this option causes a delay of MS milliseconds to occur before each TEST UNIT READY command is issued.

-n=NUM

performs TEST UNIT READY NUM times. If not given defaults to 1. Equivalent to --num=NUM in the main description.

-N, --new

Switch to the newer style options.

-p

show progress indication (a percentage) if available. Equivalent to --progress in the main description.

-t

after completing the requested number of TEST UNIT READY commands, outputs the total duration and the average number of commands executed per second. Equivalent to --time in the main description.

-v

increase level of verbosity.

-V

print out version string then exit.

## ENVIRONMENT VARIABLES
Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS can be given. When it is present this utility will expect the older command line options. So the presence of this environment variable is equivalent to using --old (or -O) as the first command line option.

## AUTHORS
Written by D. Gilbert

## COPYRIGHT
Copyright © 2000-2023 Douglas Gilbert

This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_inq, sg_requests (sg3_utils)


title: sg_unmap(8)

text:
# sg_unmap(8)

## NAME
sg_unmap - send SCSI UNMAP command (known as 'trim' in ATA specs)

## SYNOPSIS
sg_unmap [--all=ST,RN[,LA]] [--anchor] [--dry-run] [--force] [--grpnum=GN] [--help] [--in=FILE] [--lba=LBA,LBA...] [--num=NUM,NUM...] [--timeout=TO] [--verbose] [--version] DEVICE

## DESCRIPTION
Send a SCSI UNMAP command to DEVICE to unmap one or more logical blocks. This command was introduced in SBC-3 revision 18 under the broad heading of "logical block provisioning". Logical blocks may also be unmapped by the SCSI WRITE SAME command; see the sg_write_same utility. The unmap capability is closely related to the ATA DATA SET MANAGEMENT command with the "Trim" bit set.

Logical blocks to be unmapped can be specified in one of three ways to this utility. One way is by supplying the start LBAs to the '--lba=' option and the corresponding number(s) to unmap to the '--num=' option. Another way is by putting start LBA and number to unmap pairs in a file whose name is given to the '--in=' option. Alternatively a large segment or all of a disk (SSD) can be unmapped with the --all=ST_RN[,LA] option. All values are assumed to be decimal unless prefixed by "0x" (or "0X") or have a trailing "h" (or "H") in which case they are interpreted as hexadecimal. Suffix multipliers are permitted on decimal values (e.g. '--num=1m').

When the '--lba=' option is given then the '--num=' option must also be given. If one has a comma separated list as its argument then the other must have the same number of elements in its list. The arguments can use a single space as a separator but need to be in quotes or escaped to not be misinterpreted by the shell.

With the '--in=FILE' option an even number of values must be found and are interpreted as pairs: the first value in each pair is a starting LBA and the second value is the number to unmap from that LBA. Everything from and including a "#" on a line is ignored as are blank lines. Values may be comma, space and tab separated or appear on separate lines. Each line should not exceed 1023 bytes in length.

Since a lot of data can be lost with this utility, a 15 second "cooling off" period is given before any UNMAP commands are sent. During this period the user is reminded what will happen, and to which device, so they can use control-C (or some other technique) to terminate this utility before any unmapping takes place. This period can be bypassed with the --force option.

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

-A, --all=ST,RN[,LA]

where ST is the starting LBA, RN is the repeat number which is the maximum number of blocks in each SCSI UNMAP command, and LA, if given, is the last LBA to unmap. If LA is not given, then the last LBA on the DEVICE is used. That is obtained by the SCSI READ CAPACITY command.

-a, --anchor

sets the 'Anchor' bit in the command (introduced in sbc3r22).

-d, --dry-run

perform all the preparation, including opening DEVICE plus sending a 'standard' SCSI INQUIRY command (and optionally a READ CAPACITY), but exit before performing any SCSI UNMAP commands.

-f, --force

bypass the 15 second warning period that occurs before any UNMAP commands are sent.

-g, --grpnum=GN

sets the 'Group number' field to GN. Defaults to a value of zero. GN should be a value between 0 and 63.

-h, --help

output the usage message then exit.

-I, --in=FILE

where FILE is a file name containing pairs of values. The first member of each pair is a starting LBA and the second member of the pair is the number of logical blocks to unmap from and including that starting LBA. Values are interpreted as decimal unless indicated otherwise. This option cannot be present with the '--lba=' option.

-l, --lba=LBA,LBA...

where LBA,LBA... is a string of comma (or space) separated values that are interpreted as starting logical block addresses. Each number is interpreted as decimal unless prefixed by '0x' or '0X' (or it has a trailing 'h' or 'H'). An argument that contains any space separators needs to be quoted (or otherwise escaped). When this option is given then the '--num=' option must also be given and they must contain the same number of elements in their arguments.

-n, --num=NUM,NUM...

where NUM,NUM... is a string of comma (or space) separated values that are interpreted as a number of logical blocks to unmap. Each number is interpreted as decimal unless prefixed by '0x' or '0X' (or it has a trailing 'h' or 'H'). Note that 0 blocks is acceptable. An argument that contains any space separators needs to be quoted (or otherwise escaped). When this option is given then the '--lba=' option must also be given and they must contain the same number of elements in their arguments.

-t, --timeout=TO

where TO is a timeout value (in seconds) for the UNMAP command. The default value is 60 seconds.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
Some limits: an LBA can be up to 64 bits, a NUM up to 32 bits (imposed by structure of UNMAP SCSI command parameter data). The NUM is further constrained by the MAXIMUM UNMAP LBA COUNT field in the BLOCK LIMITS VPD page (0xb0). The maximum number of LBA,NUM pairs is limited to 128 by this utility and may be further constrained by the MAXIMUM UNMAP BLOCK DESCRIPTOR COUNT field in the BLOCK LIMITS VPD page.

Since it is unclear how long the UNMAP command will take to execute a '--timeout=" option has been provided. The default timeout period is 60 seconds. If all the logical blocks on a logical unit (e.g. a disk drive) are to be unmapped then the FORMAT UNIT SCSI command (see the sg_format utility) may be considered as an alternative.

Support for logical block provisioning is indicated by the LBPME bit in the response to the SCSI READ CAPACITY (16) command (see the sg_readcap utility).

In SBC-3 revision 25 the LBPU and ANC_SUP bits where added to the Logical Block Provisioning VPD page. When LBPU is set it indicates that the device supports the UNMAP command. When the ANC_SUP bit is set it indicates the device supports anchored LBAs.

The SCSI UNMAP command does the "right thing" with respect to command queueing. However its ATA counterpart: the DATA SET MANAGEMENT command with the "Trim" bit set does not interact well with SATA queueing known as NCQ. To address this problem T13 have introduced a new command called SFQ DATA SET MANAGEMENT which also has a Trim bit.

## EXAMPLES
In the examples directory of the sg3_utils package there is a sg_unmap_example.txt file that shows the format that the '--in=' option accepts.

To unmap all blocks from and including LBA 0x2000 to the end of the device (e.g. disk or SSD) with each SCSI UNMAP command given 1024 blocks to unmap:

sg_unmap --all=0x2000,1k /dev/sg2

Add '--force' to bypass the 15 seconds of warnings. So '--force' is appropriate for batch files.

## EXIT STATUS
The exit status of sg_unmap is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2009-2018 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_format,sg_get_lba_status,sg_readcap,sg_vpd,sg_write_same(sg3_utils)


title: sg_verify(8)

text:
# sg_verify(8)

## NAME
sg_verify - invoke SCSI VERIFY command(s) on a block device

## SYNOPSIS
sg_verify [--0] [--16] [--bpc=BPC] [--count=COUNT] [--dpo] [--ff] [--ebytchk=BCH] [--group=GN] [--help] [--in=IF] [--lba=LBA] [--ndo=NDO] [--quiet] [--readonly] [--verbose] [--version] [--vrprotect=VRP] DEVICE

## DESCRIPTION
Sends one or more SCSI VERIFY (10 or 16) commands to DEVICE. These SCSI commands are defined in the SBC-2 and SBC-3 standards at https://www.t10.org and SBC-4 drafts.

When --ndo=NDO is not given then the verify starts at the logical block address given by the --lba=LBA option and continues for --count=COUNT blocks. No more than --bpc=BPC blocks are verified by each VERIFY command so if necessary multiple VERIFY commands are sent. Medium verification operations are performed by the DEVICE (e.g. assuming each block has additional EEC data, check this against the logical block contents). No news is good news (i.e. if there are no verify errors detected then no messages are sent to stderr and the Unix exit status is 0).

When --ndo=NDO is given then the --bpc=BPC option is ignored. A single VERIFY command is issued and a comparison starts at the logical block address given by the --lba=LBA option and continues for --count=COUNT blocks. The VERIFY command has an associated data-out buffer that is NDO bytes long. The contents of the data-out buffer are obtained from the FN file (if --in=FN is given) or from stdin. A comparison takes place between data-out buffer and the logical blocks on the DEVICE. If the comparison is good then no messages are sent to stderr and the Unix exit status is 0. If the comparison fails then a sense buffer with a sense key of MISCOMPARE is returned; in this case the Unix exit status will be 14. Messages will be sent to stderr associated with MISCOMPARE sense buffer unless the --quiet option is given.

In SBC-3 revision 34 the BYTCHK field in all SCSI VERIFY commands was expanded from one to two bits. That required some changes in the options of this utility, see the section below on OPTION CHANGES.

## OPTIONS
Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name.

-0, --0

a buffer NDO bytes long full of zeros is sent as the data-out part of a VERIFY command. So stdin is not read and if --in=IF is given, an error is generated. Useful when BCH is 3 to check if some or all of DEVICE (e.g. a disk) is zero filled blocks.

-S, --16

uses a VERIFY(16) command (default VERIFY(10)). Even without this option, using an --lba=LBA which is too large, will cause the utility to issue a VERIFY(16) command.

-b, --bpc=BPC

this option is ignored if --ndo=NDO is given. Otherwise BPC specifies the maximum number of blocks that will be verified by a single SCSI VERIFY command. The default value is 128 blocks which equates to 64 KB for a disk with 512 byte blocks. If BPC is less than COUNT then multiple SCSI VERIFY commands are sent to the DEVICE. For the default VERIFY(10) BPC cannot exceed 0xffff (65,535) while for VERIFY(16) BPC cannot exceed 0x7fffffff (2,147,483,647). For recent block devices (disks) this value may be constrained by the maximum transfer length field in the block limits VPD page.

-c, --count=COUNT

where COUNT specifies the number of blocks to verify. The default value is 1 . If COUNT is greater than BPC (or its default value of 128) and NDO is not given, 0 or less than multiple SCSI VERIFY commands are sent to the device. Otherwise COUNT becomes the contents of the verification length field of the SCSI VERIFY command issued. The sg_readcap utility can be used to find the maximum number of blocks that a block device (e.g. a disk) has.

-d, --dpo

disable page out changes the cache retention priority of blocks read on the device's cache to the lowest priority. This means that blocks read by other commands are more likely to remain in the device's cache.

-E, --ebytchk=BCH

sets the BYTCHK field to BCH overriding the value (1) set by the --ndo=NDO option. Values of 1, 2 or 3 are accepted for BCH however sbc3r34 reserves the value 2. If this option is given then --ndo=NDO must also be given. If BCH is 3 then NDO should be the size of one logical block (plus the size of some or all of the protection information if VRP is greater than 0).

-f, --ff

a buffer NDO bytes long full of 0xff bytes is sent as the data-out part of a VERIFY command. So stdin is not read and if --in=IF is given, an error is generated. Useful when BCH is 3 to check if some or all of DEVICE (e.g. a disk) is 0xff byte filled blocks.

-g, --group=GN

where GN becomes the contents of the group number field in the SCSI VERIFY(16) command. It can be from 0 to 63 inclusive. The default value for GN is 0. Note that this option is ignored for the SCSI VERIFY(10) command.

-h, --help

output the usage message then exit.

-i, --in=IF

where IF is the name of a file from which NDO bytes will be read and placed in the data-out buffer. This is only done when the --ndo=NDO option is given. If this option is not given then stdin is read. If IF is "-" then stdin is also used.

-l, --lba=LBA

where LBA specifies the logical block address of the first block to start the verify operation. LBA is assumed to be decimal unless prefixed by '0x' or a trailing 'h' (see below). The default value is 0 (i.e. the start of the device).

-n, --ndo=NDO

NDO is the number of bytes to obtain from the FN file (if --in=FN is given) or from stdin. Those bytes are placed in the data-out buffer associated with the SCSI VERIFY command and NDO is placed in the verification length field in the cdb. The default value for NDO is 0 and the maximum value is dependent on the OS. If the --ebytchk=BCH option is not given then the BYTCHK field in the cdb is set to 1.

-q, --quiet

suppress the sense buffer messages associated with a MISCOMPARE sense key that would otherwise be sent to stderr. Still set the exit status to 14 which is the sense key value indicating a MISCOMPARE .

-r, --readonly

opens the DEVICE read-only rather than read-write which is the default. The Linux sg driver needs read-write access for the SCSI VERIFY command but other access methods may require read-only access.

-v, --verbose

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

-V, --version

print the version string and then exit.

-P, --vrprotect=VRP

where VRP is the value in the vrprotect field in the VERIFY command cdb. It must be a value between 0 and 7 inclusive. The default value is zero.

## BYTCHK
BYTCHK is the name of a field (two bits wide) in the VERIFY(10) and VERIFY(16) commands. When set to 1 or 3 (sbc3r34 reserves the value 2) it indicates that associated with the SCSI VERIFY command, a data-out buffer will be sent for the device (disk) to check. Using the --ndo=NDO option sets the BYTCHK field to 1 and NDO is the number of bytes placed in the data-out buffer. Those bytes are obtained from stdin or IF (from the --in=FN option). The --ebytchk=BCH option may be used to override the BYTCHK field value of 1 with BCH.

The calculation of NDO is left up to the user. Its value depends on the logical block size (which can be found with the sg_readcap utility), the COUNT and the VRP values. If the VRP is greater than 0 then each logical block will contain an extra 8 bytes (at least) of protection information.

When the BYTCHK field is 0 then the verification process done by the device (disk) is vendor specific. It typically involves checking each block on the disk against its error correction codes (ECC) which is additional data also held on the disk.

Many Operating Systems put limits on the maximum size of the data-out (and data-in) buffer. For Linux at one time the limit was less than 1 MB but has been increased somewhat.

## OPTION CHANGES
Earlier versions of this utility had a --bytchk=NDO option which set the BYTCHK bit and set the cdb verification length field to NDO. The shorter form of that option was -B NDO. For backward compatibility that option is still present but not documented. In its place is the --ndo=NDO whose shorter form of -n NDO. --ndo=NDO sets the BYTCHK field to 1 unless that is overridden by the --ebytchk=BCH.

## NOTES
Various numeric arguments (e.g. LBA) may include multiplicative suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section in the sg3_utils(8) man page.

The amount of error correction and the number of retries attempted before a block is considered defective are controlled in part by the Verify Error Recovery mode page. A note in the SBC-3 draft (rev 29 section 6.4.9 on the Verify Error Recovery mode page) advises that to minimize the number of checks (and hence have the most "sensitive" verify check) do the following in that mode page: set the EER bit to 0, the PER bit to 1, the DTE bit to 1, the DCR bit to 1, the verify retry count to 0 and the verify recovery time limit to 0. Mode pages can be modified with the sdparm utility.

The SCSI VERIFY(6) command defined in the SSC-2 standard and later (i.e. for tape drive systems) is not supported by this utility.

## EXIT STATUS
The exit status of sg_verify is 0 when it is successful. When BCH is other than 0 then a comparison takes place and if it fails then the exit status is 14 which happens to be the sense key value of MISCOMPARE. Otherwise see the EXIT STATUS section in the sg3_utils(8) man page.

Earlier versions of this utility set an exit status of 98 when there was a MISCOMPARE.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2004-2019 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sdparm(sdparm), sg_modes(sg3_utils), sg_readcap(sg3_utils), sg_inq(sg3_utils)


title: sg_vpd(8)

text:
# sg_vpd(8)

## NAME
sg_vpd - fetch SCSI VPD page and/or decode its response

## SYNOPSIS
sg_vpd [--all] [--enumerate] [--examine] [--force] [--help] [--hex] [--ident] [--inhex=FN] [--json[=JO]] [--js-file=JFN] [--long] [--maxlen=LEN] [--page=PG] [--quiet] [--raw] [--sinq_inraw=RFN] [--vendor=VP] [--verbose] [--version] [DEVICE]

## DESCRIPTION
This utility, when DEVICE is given, fetches a Vital Product Data (VPD) page and decodes it or outputs it in ASCII hexadecimal or binary. VPD pages are fetched with a SCSI INQUIRY command.

Alternatively the --inhex=FN option can be given. In this case FN is assumed to be a file name ('-' for stdin) containing ASCII hexadecimal representing a VPD page response. If the --raw option is also given then binary input is assumed (rather than ASCII hexadecimal).

Probably the most important page is the Device Identification VPD page (page number: 0x83). Since SPC-3, support for this page has been flagged as mandatory. This page can be fetched by using the --ident option.

The reference document used for interpreting VPD pages (and the INQUIRY standard response) is T10/BSR INCITS 566 Revision 6 which is draft SPC-6 dated 22 October 2021. It can be found at https://www.t10.org .

When no options are given, other than a DEVICE, then the "Supported VPD pages" (0x0) VPD page is fetched and decoded.

## OPTIONS
Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name.

-a, --all

decode all VPD pages. When used with DEVICE the pages to be decoded are found in the "Supported VPD pages" VPD page. Pages that cannot be decoded are displayed in hex; add the --long option to have ASCII displayed to the right of each line of hex.

If this option is used with the --inhex=FN option then the file FN is assumed to contain 1 or more VPD pages (in ASCII hex or binary). Decoding continues until the file is exhausted (or an error occurs). Sanity checks are applied on each VPD page's length and the ascending order of VPD page numbers (required by SPC-4) so bad data may be detected.

If the --page=PG option is also given then no VPD page whose page number is greater than PG (or its numeric equivalent) is decoded.

-e, --enumerate

list the names of the known VPD pages, first the standard pages (i.e. those defined by T10), then the vendor specific pages. Each group is sorted in abbreviation order. The DEVICE and most other options are ignored and this utility exits after listing the VPD page names. May be used together with --page=PG where PG is numeric. If so, it searches for the summary lines of all VPD pages whose number matches PG. May be used with --vendor=VP to restrict output to known vendor specific pages for vendor/product VP.

-E, --examine

scan part of all of the VPD space (page numbers 0x0 to 0xff) and output any pages found. If this option is given once, the scan starts at page 0x80; if it is given twice, the scan starts at 0x0; and if given three times the scan starts at 0xc0. This option takes no notice of the contents of VPD page 0x0 which should contain a list of all supported VPD pages. Some vendors either forget to list some standard pages or perhaps purposely don't list vendor specific pages which are in the range 0xc0 to 0xff.

If the --page=PG option is not given then the scan finishes at page 0xff. if the --page=PG option is given then the scan finishes at page PG. A check is made before the scan to make sure the start page is less than or equal to the finish page; if not the start and finish page numbers are swapped.

The sdparm utility which lists mode and VPD pages also has a --examine option will similar functionility. Note that T10 has changed most of the pages that list supported pages (e.g. VPD, mode and log pages; supported commands) to add the weasel words "may or may not list all ...".

-f, --force

As a sanity check, the normal action when fetching VPD pages other than page 0x0 (the "Supported VPD pages" VPD page), is to first fetch page 0x0 and only if the requested page is one of the supported pages, to go ahead and fetch the requested page.

When this option is given, skip checking of VPD page 0x0 before accessing the requested VPD page. The prior check of VPD page 0x0 is known to crash certain USB devices, so use with care.

-h, --help

outputs the usage message summarizing command line options then exits. Ignores DEVICE if given.

-H, --hex

outputs the requested VPD page in ASCII hexadecimal. Can be used multiple times, see section on the ATA information vpd page.

To generate output suitable for placing in a file that can be used by a later invocation with the --inhex=FN option, use the '-HHHH' option (e.g. 'sg_vpd -p di -HHHH /dev/sg3 > dev_id.hex'). The reason '-HHHH' is used is to flag that unadorned hexadecimal (without other text or address offsets) is sent to stdout.

-i, --ident

decode the device identification (0x83) VPD page. When used once this option has the same effect as '--page=di'. When use twice then the short form of the device identification VPD page's logical unit designator is decoded. In the latter case this option has the same effect as '--quiet --page=di_lu'.

-I, --inhex=FN

FN is expected to be a file name (or '-' for stdin) which contains ASCII hexadecimal or binary representing a VPD page (or a standard INQUIRY) response. This utility will then decode that response. It is preferable to also supply the --page=PG option, if not this utility will attempt to guess which VPD page (or standard INQUIRY) the response is associated with. The hexadecimal should be arranged as 1 or 2 digits representing a byte each of which is whitespace or comma separated. Anything from and including a hash mark to the end of line is ignored. If the --raw option is also given then FN is treated as binary.

-j[=JO], --json[=JO]

output is in JSON format instead of plain text form. Note that arguments to the short and long form are themselves optional and if present start with "=" and no whitespace is permitted around that "=".

See sg3_utils_json manpage or use '?' for JO to get a summary.

-J, --js-file=JFN

output is in JSON format and it is sent to a file named JFN. If that file exists then it is truncated. By default, the JSON output is sent to stdout.

When this option is given, the --json[=JO] option is implied and need not be given. The --json[=JO] option may still be needed to set the JO parameter to non-default values.

-l, --long

when decoding some VPD pages, give a little more output. For example the ATA Information VPD page only shows the signature (in hex) and the IDENTIFY (PACKET) DEVICE (in hex) when this option is given.

-m, --maxlen=LEN

where LEN is the (maximum) response length in bytes. It is placed in the cdb's "allocation length" field. If not given (or LEN is zero) then 252 is used (apart from the ATA Information VPD page which defaults to 572) and, if the response indicates this value is insufficient, another INQUIRY command is sent with a larger value in the cdb's "allocation length" field. If this option is given and LEN is greater than 0 then only one INQUIRY command is sent. Since many simple devices implement the INQUIRY command badly (and do not support VPD pages) then the safest value to use for LEN is 36. See the sg_inq(8) man page for the more information.

-p, --page=PG

where PG is the VPD page to be decoded or output. The PG argument can either be an abbreviation, a number or a pair or numbers/abbreviations separated by a comma. The VPD page abbreviations can be seen by using the --enumerate option. If a number is given it is assumed to be decimal unless it has a hexadecimal indicator which is either a leading '0x' or a trailing 'h'. If one number is given then it is assumed to be a VPD page number. If two numbers (or abbreviations) are given then the second one is the same as VP (see the --vendor=VP option). If this option is not given (nor '-i', '-l' nor '-V') then the "Supported VPD pages" (0x0) VPD page is fetched and decoded. If PG is '-1' or 'sinq' then the standard INQUIRY response is output. This option may also be used with the --enumerate (see its description).

If PG is not found in the 'Supported VPD pages' VPD page (0x0) then EDOM is returned. To bypass this check use the --force option.

-q, --quiet

suppress the amount of decoding and error output.

-r, --raw

if not used with --inhex=FN then output requested VPD page in binary. The output should be piped to a file or another utility when this option is used. The binary is sent to stdout, and errors are sent to stderr.

if used with --inhex=FN then the contents of FN is treated as binary.

-Q, --sinq_inraw=RFN

where RFN is a filename containing binary standard INQUIRY response data that matches either DEVICE or FN. Linux places this standard INQUIRY response in its sysfs pseudo filesystem. A typical location is at /sys/class/scsi_device/<hctl>/device/inquiry where <hctl> is a four part numeric tuple separated by colons. This tuple distinguishes the device from any others on the system. Linux also places some VPD page responses in binary in the same directory with names like "vpd_pg83" where the last two digits form the hexadecimal VPD page number whose binary contents are therein.

Some VPD pages (e.g. the Extended Inquiry VPD page) depend on knowing the settings in the standard INQUIRY response to interpret the fields in that VPD page. This option together with the --all, --examine or --page=PG allows this utility to process both the standard INQUIRY response and VPD pages in the same invocation.

The --raw option has no effect on this option. The DEVICE argument may be given with this option.

-M, --vendor=VP

where VP is a vendor (e.g. "sea" for Seagate) or vendor/product acronym (e.g. "hp3par" for the 3PAR array from HP). Many vendors have re-used the numbers at the beginning of the vendor specific VPD page range (e.g. page 0xc0) and this option is a way of selecting only those which are of interest. Using a VP of "xxx" will list the available acronyms.

If this option is used with --page=PG and PG is an acronym then this option is ignored. If PG is a number (e.g. 0xc0) then VP is used to choose the which vendor specific page (e.g. sharing page number 0xc0) to decode.

-v, --verbose

increases the level or verbosity.

-V, --version

print out version string then exit.

## ATA INFORMATION VPD PAGE
This VPD page (0x89 or 'ai') is defined by the SCSI to ATA Translation standard. It contains information about the SAT layer, the "signature" of the ATA device and the response to the ATA IDENTIFY (PACKET) DEVICE command. The latter part has 512 bytes of identity, capability and settings data which the hdparm utility is capable of decoding (so this utility doesn't decode it).

To unclutter the output for this page, the signature and the IDENTIFY (PACKET) DEVICE response are not output unless the --long option (or --hex or --raw) are given. When the --long option is given the IDENTIFY (PACKET) DEVICE response is output as 256 (16 bit) words as is the fashion for ATA devices. To see that response as a string of bytes use the '-HH' option. To format the output suitable for hdparm to decode use either the '-HHH' or '-rr' option. For example if 'dev/sdb' is a SATA disk behind a SAT layer then this command: 'sg_vpd -p ai -HHH /dev/sdb | hdparm --Istdin' should decode the ATA IDENTIFY (PACKET) DEVICE response.

## NOTES
Since some VPD pages (e.g. the Extended INQUIRY page) depend on settings in the standard INQUIRY response, then the standard INQUIRY response is output as a pseudo VPD page when PG is set to '-1' or 'sinq'. Also the decoding of some fields (e.g. the Extended INQUIRY page's SPT field) is expanded when the '--long' option is given using the standard INQUIRY response information (e.g. the PDT and the PROTECT fields).

The DEVICE is opened with a read-only flag (e.g. in Unix with the O_RDONLY flag).

## EXIT STATUS
The exit status of sg_vpd is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## EXAMPLES
The examples in this page use Linux device names. For suitable device names in other supported Operating Systems see the sg3_utils(8) man page.

To see the VPD pages that a device supports, use with no options. The command line invocation is shown first followed by a typical response:

\# sg_vpd /dev/sdb

Supported VPD pages VPD page:

Supported VPD pages [sv]

Unit serial number [sn]

Device identification [di]

Extended inquiry data [ei]

Block limits (SBC) [bl]

To see the VPD page numbers associated with each supported page then add the '--long' option to the above command line. To view a VPD page either its number or abbreviation can be given to the '--page=' option. The page name abbreviations are shown within square brackets above. In the next example the Extended inquiry data VPD page is listed:

\# sg_vpd --page=ei /dev/sdb

extended INQUIRY data VPD page:

ACTIVATE_MICROCODE=0 SPT=0 GRD_CHK=0 APP_CHK=0 REF_CHK=0

UASK_SUP=0 GROUP_SUP=0 PRIOR_SUP=0 HEADSUP=1 ORDSUP=1 SIMPSUP=1

WU_SUP=0 CRD_SUP=0 NV_SUP=0 V_SUP=0

P_I_I_SUP=0 LUICLR=0 R_SUP=0 CBCS=0

Multi I_T nexus microcode download=0

Extended self-test completion minutes=0

POA_SUP=0 HRA_SUP=0 VSA_SUP=0

To check if any protection types are supported by a disk use the '--long' option on the Extended inquiry data VPD page:

\# sg_vpd --page=ei --long /dev/sdb

extended INQUIRY data VPD page:

ACTIVATE_MICROCODE=0

SPT=1 [protection types 1 and 2 supported]

GRD_CHK=1

....

Search for the name (and acronym) of all pages that share VPD page number 0xb0 .

\# sg_vpd --page=0xb0 --enumerate

Matching standard VPD pages:

bl 0xb0 Block limits (SBC)

oi 0xb0 OSD information

sad 0xb0 Sequential access device capabilities (SSC)

Some examples follow using the "--all" option. Send an ASCII hexadecimal representation of all VPD pages to a file:

\# sg_vpd --all -HHHH /dev/sg3 > all_vpds.hex

At some later time that file could be decoded with:

\# sg_vpd --all --inhex=all_vpds.hex

To do the equivalent as the previous example but use a file containing binary:

\# sg_vpd --all --raw /dev/sg3 > all_vpds.bin

\# sg_vpd --all --raw --inhex=all_vpds.bin

Notice that "--raw" must be given with the second (--inhex) invocation to alert the utility that all_vpds.bin contains binary as it assumes ASCII hexadecimal by default. Next we only decode T10 specified VPD pages excluding vendor specific VPD pages that start at page number 0xc0:

\# sg_vpd --all --page=0xbf --raw --inhex=all_vpds.bin

In Linux, binary images of some important VPD page responses (e.g. 0, 80h and 83h) are cached in files within the sysfs pseudo file system. Since VPD pages hardly ever change their contents, decoding those files will give the same output as probing the device with the added benefit that decoding those files doesn't need root permissions. The long and short forms are shown:

sg_vpd --raw --inhex=/sys/class/scsi_generic/sg3/device/vpd_pg83

sg_vpd -rI /sys/class/scsi_generic/sg3/device/vpd_pg83

If /dev/sg3 is a disk at 2:0:0:0 , then this invocation should give more verbose output but essentially the same as the previous two examples.

sg_vpd -v -r -I /sys/class/scsi_disk/2:0:0:0/device/vpd_pg83

Further examples can be found on the https://sg.danny.cz/sg/sg3_utils.html web page.

## AUTHOR
Written by Douglas Gilbert

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2006-2023 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_inq(sg3_utils), sg3_utils(sg3_utils), sdparm(sdparm), hdparm(hdparm)


title: sg_wr_mode(8)

summary: write (modify) SCSI mode page

text:
# sg_wr_mode(8)

## NAME
sg_wr_mode - write (modify) SCSI mode page

## SYNOPSIS
sg_wr_mode [--cfile=CF] [--contents=H,H...] [--dbd] [--force] [--help] [--len=10|6] [--mask=M,M...] [--page=PG_H[,SPG_H]] [--raw] [--rtd] [--save] [--six] [--verbose] [--version] DEVICE

## DESCRIPTION
Writes a modified mode page to DEVICE. Uses the SCSI MODE SENSE (6 or 10 byte variant) command to fetch the existing mode data which includes a mode page (or subpage). It then combines that with the contents, potentially masked, and writes the modified mode page with the SCSI MODE SELECT (6 or 10 byte variant) command. This utility does not modify the block descriptor(s); if any block descriptors are fetched by the MODE SENSE command then the same block descriptors are written back with the following MODE SELECT command.

If the --rtd option is given then most other options apart from --save, --len=10|6 and --six are ignored. In this case only a MODE SELECT command is sent to the DEVICE with the RTD bit (Revert To Defaults) set. This bit was added to this command in SPC-5 revision 11, so older devices may not support it. The Extended Inquiry VPD page has the RTD_SUP bit to indicate whether the DEVICE supports the RTD bit in the MODE SELECT(6 and 10) commands. When the --rtd option is given the rest of this section can be ignored.

If a contents option is not given then the various components (i.e. header, block descriptor(s) and mode page) of the "current" values of the existing mode page are printed out. In this case the mode page is not altered on the device.

If the contents are specified, and a mask is not specified, then the contents must match the existing mode page in various aspects unless the --force option is given. These include length, mode page code and subpage code if applicable. If all is well then the contents string is written to DEVICE as the new mode page.

If both contents and mask strings are specified then only bit positions in the contents corresponding to set bits in the mask are taken while the existing mode page supplies bit positions corresponding to clear bits. When a mask is given then the mask and/or the contents may be shorter than the existing mode page. If the mask is shorter than the contents then the remaining bytes are taken from the contents. If the contents are shorter than the existing mode page then the remaining bytes are taken from the existing mod page.

The force option allows the contents string to be written as the new mode page without any prior checks on the existing mode page. This should only be required for vendor specific mode pages. The existing mode data is ignored apart from the block descriptors which can be suppressed with the --dbd option if need be.

Changing individual fields in a mode page is probably more easily done with the sdparm utility. Fields can be identified by acronym or by a numerical descriptor.

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

-C, --cfile=CF

where CF is a file name containing the mode page. See the "HEX, BINARY AND JSON FORMATS" section in the sg3_utils manpage for more information. If the --raw option is also given then the contents of FN are treated as binary.

-c, --contents=H,H...

where H,H... is a string of comma separated hex numbers each of which should resolve to a byte value (i.e. 0 to ff inclusive). A (single) space separated string of hex numbers is also allowed but the list needs to be in quotes. This is the new contents of the mode page to be written to DEVICE, potentially filtered by the mask string.

-c, --contents=-

reads contents string from stdin. See the --cfile=CF option above.

-d, --dbd

disable block descriptors (DBD flag in cdb). Some device types include block descriptors in the mode data returned by a MODE SENSE command. If so the same block descriptors are written by the MODE SELECT command. This option instructs the MODE SENSE command not to return any block descriptors. This would be a sensible default for this utility apart from the fact that not all SCSI devices support the DBD bit in the cdb.

-f, --force

force the contents string to be taken as the new mode page, or at least doesn't do checks on the existing mode page. Note that DEVICE may still reject the new contents for the mode page. Cannot be given with the --mask=M,M... option.

-h, --help

output the usage message then exit.

-l, --len=10 | 6

length of the SCSI commands (cdb) sent to DEVICE. The default is 10 so 10 byte MODE SENSE and MODE SELECT commands are issued. Some old devices don't support the 10 byte variants hence this option.

-m, --mask=M,M...

where M,M... is a string of comma separated hex numbers each of which should resolve to a byte value (i.e. 0 to ff inclusive). A (single) space separated string of hex numbers is also allowed but the list needs to be in quotes. The mask chooses (bit by bit) whether the new mode page comes from the contents (mask bit set) or from the existing mode page (mask bit clear). If the mask string is shorter than the contents string then the remaining bytes are taken from the contents string. If the contents string is shorter than the existing mode page then the remaining bytes are taken from the existing mode page (i.e. they are left unaltered).

-p, --page=PG_H

where PG_H is the page code value to fetch and modify. The page code is in hex and should be between 0 and 3e inclusive. Notice that page code 3f to fetch all mode pages is disallowed.

-p, --page=PG_H,SPG_H

where PG_H is the page code value and SPG_H is the subpage code value to fetch and modify. Both values are in hex. The subpage code should be between 0 and fe inclusive. Notice that subpage code ff to fetch all mode subpages (for a given mode page or all mode pages in the case of 3f,ff) is disallowed.

-r, --raw

when this option is given then the file given by the --cfile=CF option is treated as binary (the default is to treat it as ASCII hexadecimal).

-R, --rtd

when this option is given most other actions are bypassed and a MODE SELECT(6 or 10) command is sent to the DEVICE with the RTD bit set. This will cause all current values (and saved values if the --save option is also given) of all mode pages to be reverted to their default values.

-s, --save

changes the "saved" mode page when MODE SELECT is successful. By default (i.e. when --save is not used) only the "current" mode page values are changed when MODE SELECT is successful. In this case the new mode page will stay in effect until the device is reset (e.g. power cycled). When it restarts the "saved" values for the mode page will be re-instated. So to make changes permanent use the --save option.

When used with the --rtd option then both the current and saved values in each mode page are reverted to their default values. In the absence of --save option only the current values in each mode page are reverted to their default values.

-6, --six

this option will cause the 6 byte variants of MODE SENSE and MODE SELECT commands to be used. The default is to use the 10 byte options. This option is equivalent to using the --len=6 option.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
This utility does not check whether the contents string is trying to modify parts of the mode page which are changeable. The device should do that and if some part is not changeable then it should report: "Invalid field in parameter list".

Some mode pages are not saveable. If so an attempt to use the --save option should cause an error to be reported from the device: "Illegal field in cdb".

The device is required to do various checks before it accepts a new mode page. If these checks fail then the mode page is not altered and either a "parameter list length error" or an "invalid field in parameter list" error is returned by the device in the sense data.

The recommended way to modify a mode page is to read it with a MODE SENSE, modify some part of it then write it back to the device with a MODE SELECT command. For example, reading an existing mode page can be accomplished with 'sg_modes -p=1a -r /dev/sdb > mp_1a.txt' (the power condition mode page). The mp_1a.txt file can be edited and then used as the contents string to this utility (e.g. 'sg_wr_mode -p 1a -s -c - /dev/sdb < mp_1a.txt').

Two fields differ between what is read from the device with MODE SENSE and what is written to the device with MODE SELECT: the mode data length is reserved (i.e. zero(es)) in a MODE SELECT command while the PS bit ((sub)page byte 0 bit 7) in each mode (sub)page is reserved (zero) in a MODE SELECT command. The PS bit given in the contents string is zeroed unless the --force option is selected.

## EXAMPLES
This utility can be used together with the sg_modes utility. To re-instate the default mode page values (i.e. the mode page values chosen by the manufacturer of the device) as both the current and saved mode page values the following sequence could be used:

$ sg_modes --control=2 --page=1a -r /dev/sda > t

$ sg_wr_mode --page=1a --contents=- --save /dev/sda < t

Next is an example of using a mask to modify the "idle condition counter" of the "power condition" mode page (0x1a) from 0x28 to 0x37. Note that the change is not saved so the "idle condition counter" will revert to 0x28 after the next power cycle. The output from sg_modes is abridged.

$ sg_modes --page=1a /dev/hdc

>> Power condition (mmc), page_control: current

00 1a 0a 00 03 00 00 00 28 00 00 01 2c

$ sg_wr_mode -p 1a -c 0,0,0,0,0,0,0,37 -m 0,0,0,0,0,0,0,ff /dev/hdc

$ sg_modes -p 1a /dev/hdc

>> Power condition (mmc), page_control: current

00 1a 0a 00 03 00 00 00 37 00 00 01 2c

## EXIT STATUS
The exit status of sg_wr_mode is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2004-2023 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sdparm(sdparm), sg_modes(sg3_utils), sginfo(sg3_utils)


title: sg_write_attr(8)

summary: send SCSI WRITE ATTRIBUTE command

text:
# 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 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)