title: sg_read_long(8)

summary: send a SCSI READ LONG command

text:
# sg_read_long(8)

## NAME
sg_read_long - send a SCSI READ LONG command

## SYNOPSIS
sg_read_long [--16] [--correct] [--help] [--lba=LBA] [--out=OF] [--pblock] [--readonly] [--verbose] [--version] [--xfer_len=BTL] DEVICE

## DESCRIPTION
Send SCSI READ LONG command to DEVICE. The read buffer is output in hex and ASCII to stdout or placed in a file. Note that the data returned includes the logical block data (typically 512 bytes for a disk) plus ECC information (whose format is proprietary) plus optionally other proprietary data. Note that the logical block data may be encoded or encrypted.

In SBC-4 revision 7 the SCSI READ LONG (10 and 16 byte) commands were made obsolete. In the same revision all uses of SCSI WRITE LONG (10 and 16 byte) commands were made obsolete apart from the case in which the WR_UNCOR bit is set.

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

-S, --16

uses a SCSI READ LONG(16) command. The default action is to use a SCSI READ LONG(10) command. The READ LONG(10) command has a 32 bit field for the lba while READ LONG(16) has a 64 bit field.

-c, --correct

sets the 'CORRCT' bit in the SCSI READ LONG command. When set the data is corrected by the ECC before being transferred back to this utility. The default is to leave the 'CORRCT' bit clear in which case the data is not corrected.

-h, --help

output the usage message then exit.

-l, --lba=LBA

where LBA is the logical block address of the sector to read. Assumed to be in decimal unless prefixed with '0x' (or has a trailing 'h'). Defaults to lba 0. If the lba is larger than can fit in 32 bits then the --16 option should be used.

-o, --out=OF

instead of outputting ASCII hex to stdout, send it in binary to the file called OF. If '-' is given for OF then the (binary) output is sent to stdout. Note that all informative and error output is sent to stderr.

-p, --pblock

sets the 'PBLOCK' bit in the SCSI READ LONG command. When set the physical block (plus ECC data) containing the requested logical block address is read. The default is to leave the 'PBLOCK' bit clear in which case the logical block (plus any ECC data) is read.

-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 READ LONG 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.

-x, --xfer_len=BTL

where BTL is the byte transfer length (default to 520). If the given value (or the default) does not match the "long" block size of the device, the appropriate BTL is deduced from the error response and printed (to stderr). The idea is that the user will retry this utility with the correct transfer length.

## NOTES
If a defective block is found and its contents, if any, has been retrieved then "sg_reassign" could be used to map out the defective block. Associated with such an action the number of elements in the "grown" defect list could be monitored (with "sg_reassign --grown") as the disk could be nearing the end of its useful lifetime.

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.

As a data point, Fujitsu uses a 54 byte ECC (per block) which is capable of correcting up to a single burst error or 216 bits "on the fly". [Information obtained from MAV20xxrc product manual.]

## EXIT STATUS
The exit status of sg_read_long 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-2016 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_reassign, sg_write_long, sg_dd


title: sg_readcap(8)

summary: send SCSI READ CAPACITY command

text:
# sg_readcap(8)

## NAME
sg_readcap - send SCSI READ CAPACITY command

## SYNOPSIS
sg_readcap [--10] [--16] [--brief] [--help] [--hex] [--inhex=FN] [--json[=JO]] [--js-file=JFN] [--lba=LBA] [--long] [--pmi] [--raw] [--readonly] [--verbose] [--version] [--zbc] DEVICE

sg_readcap [-16] [-b] [-h] [-H] [-lba=LBA] [-pmi] [-r] [-R] [-v] [-V] [-z] DEVICE

## DESCRIPTION
The normal action of the SCSI READ CAPACITY command is to fetch the number of blocks (and block size) from the DEVICE.

The SCSI READ CAPACITY command (both 10 and 16 byte cdbs) actually yield the block address of the last block and the block size. The number of blocks is thus one plus the block address of the last block (as blocks are counted origin zero (i.e. starting at block zero)). This is the source of many "off by one" errors.

The READ CAPACITY(16) response provides additional information not found in the READ CAPACITY(10) response. This includes protection and logical block provisioning information, plus the number of logical blocks per physical block. So even though the media size may not exceed what READ CAPACITY(10) can show, it may still be useful to examine the response to READ CAPACITY(16). Sadly there are horrible SCSI command set implementations in the wild that crash when the READ CAPACITY(16) command is sent to them.

Device capacity is the product of the number of blocks by the block size. This utility outputs this figure in bytes, MiB (1048576 bytes per MiB), GB (1000000000 bytes per GB) and, if large enough, TB (1000 GB).

If sg_readcap is called without the --long option then the 10 byte cdb version (i.e. READ CAPACITY (10)) is sent to the DEVICE. If the number of blocks in the response is reported as 0xffffffff (i.e. (2**32 - 1) ) and the --hex option has not been given, then READ CAPACITY (16) is called and its response is output.

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. The options are arranged in alphabetical order based on the long option name.

--10

Use the 10 byte cdb variant of the READ CAPACITY command. This is currently the default action of this utility. That default may change to the 16 byte variant, especially if T10 deprecates the 10 byte variant.

--16

Use the 16 byte cdb variant of the READ CAPACITY command. See the '--long' option. -b, --brief outputs two hex numbers (prefixed with '0x' and space separated) to stdout. The first number is the maximum number of blocks on the device (which is one plus the lba of the last accessible block). The second number is the size in bytes of each block. If the operation fails then "0x0 0x0" is written to stdout.

-h, --help

print out the usage message then exit.

-H, --hex

output the response to the READ CAPACITY command (either the 10 or 16 byte cdb variant) in ASCII hexadecimal on stdout. Each line starts with a hexadecimal address or index, starting at 0. If this option is given twice, and ASCII rendering of the 16 bytes on each line is appended to the right hand side of each line.

If this option is given three times then 16 bytes of ASCII hexadecimal are output in each line with no leading address nor ASCII rendering to the right. This output is suitable for importing into a later invocation of this utility with the file containing the hex given to the --inhex=FN option. When given four (or more times) this option adds a comment line (starting with '#') describing the command that caused the output.

-i, --inhex=FN

where FN is a file name whose contents are assumed to be ASCII hexadecimal. If DEVICE is also given then DEVICE is ignored, a warning is issued and the utility continues, decoding the file named FN. 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.

-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, --lba=LBA

used in conjunction with --pmi option. This variant of READ CAPACITY will yield the last block address after LBA prior to a delay. For a disk, given a LBA it yields the highest numbered block on the same cylinder (i.e. before the heads need to move). LBA is assumed to be decimal unless prefixed by "0x" or it has a trailing "h". Defaults to 0. This option was made obsolete in SBC-3 revision 26.

-l, --long

Use the 16 byte cdb variant of the READ CAPACITY command. The default action is to use the 10 byte cdb variant which limits the maximum block address to (2**32 - 2). When a 10 byte cdb READ CAPACITY command is used on a device whose size is too large then a last block address of 0xffffffff is returned (if the device complies with SBC-2 or later).

-O, --old

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

-p, --pmi

partial medium indicator: for finding the next block address prior to some delay (e.g. head movement). In the absence of this option, the total number of blocks and the block size of the device are output. Used in conjunction with the --lba=LBA option. This option was made obsolete in SBC-3 revision 26.

-r, --raw

output response in binary to stdout.

-R, --readonly

open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default for READ CAPACITY(16) is to open it read-write. The default for READ CAPACITY(10) is to open it read-only so this option does not change anything for this case.

-v, --verbose

increase level of verbosity. Can be used multiple times.

-V, --version

outputs version string then exits.

-z, --zbc

additionally prints out the extra ZBC field (RC_BASIS) in the READ CAPACITY response. Using the option implicitly sets the --16 option.

## NOTES
The response to READ CAPACITY(16) contains a LBPRZ bit in the SBC-3 standard (ANSI INCITS 514-2014). There was also a LBPRZ bit with the same meaning in the Logical block provisioning VPD page (0xb2). Then somewhat confusingly T10 expanded the LBPRZ bit to a 3 bit field in SBC-4 draft revision 7, but only in the LB provisioning VPD page. The reason for the expansion was to report a new "provisioning initialization pattern" state (when an unmapped logical block is read). The new state has been assigned LBPRZ=2 in the VPD page and it re-uses LBPRZ=0 in the READ CAPACITY(16) response. LBPRZ=1 retains the same meaning for both variants, namely that a block of zeroes will be returned when an unmapped logical block is read.

## EXIT STATUS
The exit status of sg_readcap 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.

-16

Use the 16 byte cdb variant of the READ CAPACITY command. Equivalent to --long in the main description.

-b

utility outputs two hex numbers (prefixed with '0x' and space separated) to stdout. The first number is the maximum number of blocks on the device (which is one plus the lba of the last accessible block). The second number is the size of each block. If the operation fails then "0x0 0x0" is written to stdout. Equivalent to --brief in the main description.

-h

output the usage message then exit. Giving the -? option also outputs the usage message then exits.

-H

output the response to the READ CAPACITY command (either the 10 or 16 byte cdb variant) in ASCII hexadecimal on stdout.

-lba=LBA

used in conjunction with -pmi option. This variant of READ CAPACITY will yield the last block address after LBA prior to a delay. Equivalent to --lba=LBA in the main description.

-N, --new

Switch to the newer style options.

-pmi

partial medium indicator: for finding the next block address prior to some delay (e.g. head movement). In the absence of this switch, the total number of blocks and the block size of the device are output. Equivalent to --pmi in the main description.

-r

output response in binary (to stdout).

-R

Equivalent to --readonly in the main description.

-v

verbose: print out cdb of issued commands prior to execution. '-vv' and '-vvv' are also accepted yielding greater verbosity.

-V

outputs version string then exits.

-z

Equivalent to --zbc in the main description.

## 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 Douglas Gilbert

## COPYRIGHT
Copyright © 1999-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(sg3_utils)

branch: sisyphus


title: sg_reassign(8)

summary: send SCSI REASSIGN BLOCKS command

text:
# sg_reassign(8)

## NAME
sg_reassign - send SCSI REASSIGN BLOCKS command

## SYNOPSIS
sg_reassign [--address=A,A...] [--dummy] [--eight=0|1] [--grown] [--help] [--hex] [--longlist=0|1] [--primary] [--verbose] [--version] DEVICE

## DESCRIPTION
Send a SCSI REASSIGN BLOCKS command to DEVICE. Alternatively this utility can find the number of element in a "grown" or "primary" defect list with a SCSI READ DEFECT DATA (10) command. These SCSI commands are defined in SBC-2 for direct access devices (e.g. a disk). Reassign blocks is designed to change the physical location of a logical block that is known or suspected to be defective to another area on the media. Disks are typically formatted with blocks held in reserve for this situation.

If neither the --grown nor --primary option is supplied then one or more addresses need to be given. If the address (or all of the addresses) fit into 4 bytes and '--eight=1' is not given then the parameter block passed to DEVICE is made up of 4 byte logical block addresses. If any of the addresses need more than 4 bytes to represent (i.e. >= 2**32) or '--eight=1' is given then the parameter block passed to DEVICE is made up of 8 byte logical block addresses.

## 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, --address=A,A...

where A,A... is a string of comma separated numbers. Each number is interpreted as decimal unless prefixed by '0x' or '0X' (or it has a trailing 'h' or 'H'). If multiple logical block addresses are given they must be separated by a comma or a (single) space. A string that contains any space separators needs to be quoted. At least one address must be given.

-a, --address=-

reads one or more logical block addresses from stdin. These may be comma, space, tab or linefeed (newline) separated. If a line contains "#" then the remaining characters on that line are ignored. Otherwise each non separator sequence of characters should resolve to a decimal number unless prefixed by '0x' or '0X' (or has a trailing 'h'). At least one address must be given. Lines should not be longer than 1023 bytes.

-d, --dummy

prepare for but do not execute the SCSI REASSIGN BLOCKS command. Since the REASSIGN BLOCKS command is essentially irreversible, paranoid users may wish to check the invocation of this utility before reassigning defective blocks on a disk. Useful with '-vv' for those who wish to view the parameter block that will accompany the command.

-e, --eight=0 | 1

when value is 1 then it sets the 'LONGLBA' flag in the command indicating that the addresses in the associated parameter block are 8 byte quantities. When value is 0 then it clears the 'LONGLBA' flag in the command indicating that the addresses in the associated parameter block are 4 byte quantities. If this option is not given then 4 byte quantities are assumed unless one of the address is too large.

-g, --grown

use the SCSI READ DEFECT DATA (10) command to determine the number of elements in the "grown defect list". When this option is given there is no reassignment of blocks (i.e. this utility is passive). When this option is given then the --address= option is not permitted. See the discussion below concerning the relationship between reassigned blocks and the grown defect list. This list is sometimes referred to as the GLIST.

-h, --help

output the usage message then exit.

-H, --hex

print response in hex (for -g, --grown, -p or --primary).

-l, --longlist=0 | 1

sets the REASSIGN BLOCKS cdb field of the same name to the given value. Only 1000 addresses are permitted so there should be no need to specify a value of 1. The short list variant restricts the parameter block length to 2 ** 16 bytes (i.e. about 16000 4 byte addresses or 8000 8 byte addresses). Added for completeness.

-p, --primary

use the SCSI READ DEFECT DATA (10) command to determine the number of elements in the "primary defect list" which is established during the manufacturing process. When this option is given there is no reassignment of blocks (i.e. this utility is passive). When this option is given then the --address= option is not permitted. This list is sometimes referred to as the PLIST.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
Note that if the ARRE field (for reads) and/or the AWRE field (for writes) are set in the "Read Write Error Recovery" mode page then recoverable read and/or write errors cause automatic reassignment of the defective block. The PER bit in the same mode page controls whether a RECOVERED ERROR sense key is reported on not (PER=1 implies do report). Irrespective of the ARRE, AWRE or PER field settings, the error counter log pages reflect any errors (recovered or otherwise). Whenever a block is reassigned, a new entry is added in the "grown" defect list. Apart from doing selftests (see sg_senddiag or smartmontools) regularly, monitoring the grown defect list of a disk is a reasonable metric of its health. If the grown list starts growing quickly that is an ominous sign. The best grown defect lists are empty ones. The number of elements in the grown defect list can be viewed with the --grown option. The contents of the grown defect list can be viewed with the 'sginfo -G' utility.

If an unrecoverable error is detected at a logical block address then REASSIGN BLOCKS is needed to reassign the block. Also if the ARRE and/or AWRE fields are clear and a recoverable error is detected then the logical block in question may be reassigned with this utility (otherwise the error counter log pages will continually be incremented for each recovered access).

The number of blocks held in reserve for the purposes of REASSIGN BLOCKS is vendor specific and may well be limited to the zone within the media where the original (defective) block lay. When this number is exhausted subsequent invocations of this utility may result in a sense key of hardware error and an additional sense of 'No defect spare location available'. The next step would be to reformat the disk (or get a replacement).

The SBC-2 draft standard (revision 16) notes that when multiple addresses are given to the SCSI REASSIGN BLOCKS command and there is some failure at one of the later addresses then all addresses prior to that have already be reassigned. Care should be taken in such a case. Re-executing the command with the same addresses will cause the earlier addresses to be reassigned again. At some stage the disk will run out of reserved locations. So unless a large number of addresses are involved it may be safer to reassign them one address at a time.

## EXIT STATUS
The exit status of sg_reassign 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 © 2005-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
sg_format,sginfo,sg_senddiag(all in sg3_utils), sdparm(sdparm), smartmontools(internet, sourceforge)


title: sg_referrals(8)

summary: send SCSI REPORT REFERRALS command

text:
# sg_referrals(8)

## NAME
sg_referrals - send SCSI REPORT REFERRALS command

## SYNOPSIS
sg_referrals [--help] [--hex] [--lba=LBA] [--maxlen=LEN] [--one-segment] [--raw] [--readonly] [--verbose] [--version] DEVICE

## DESCRIPTION
Send the SCSI REPORT REFERRALS command to the DEVICE and outputs the response. This command was introduced in (draft) SBC-3 revision 24 and devices that support referrals should support this command.

The default action is to decode the response for all user data segment referral descriptors. The amount of output can be reduced by the --lba and --one-segment options.

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

-h, --help

output the usage message then exit.

-H, --hex

output response to this command in ASCII hex.

-l, --lba=LBA

where LBA is the Logical Block Address (LBA) in the first user data segment the DEVICE should report the referrals parameter data for.

-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 then 256 is used. 256 is enough space for the response header and user data segment descriptors.

-s, --one-segment

report the user data segment of the segment specified by the LBA parameter only.

-r, --raw

output response in binary (to stdout).

-R, --readonly

open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write.

-v, --verbose

increase the level of verbosity, (i.e. debug output). Additional output caused by this option is sent to stderr.

-V, --version

print the version string and then exit.

## NOTES
For a discussion of referrals see section 4.25 of sbc3r25.pdf at https://www.t10.org (or the corresponding section of a later draft).

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

## AUTHORS
Written by Douglas Gilbert and Hannes Reinecke.

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

## COPYRIGHT
Copyright © 2009-2014 Douglas Gilbert and Hannes Reinecke

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(8)


title: sg_rem_rest_elem(8)

text:
# sg_rem_rest_elem(8)

## NAME
sg_rem_rest_elem - send SCSI remove or restore element command

## SYNOPSIS
sg_rem_rest_elem [--capacity=RC] [--element=EID] [--help] [--quick] [--remove] [--restore] [--timeout=SE] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SCSI REMOVE ELEMENT AND TRUNCATE [RMEAT] or RESTORE ELEMENTS AND REBUILD [RSEAR] command to the DEVICE. Since both these commands have a potentially huge impact on the DEVICE (similar to the FORMAT UNIT command: destroying data and taking a long time to complete fully), they first give the user the chance to reconsider (3 times within 15 seconds) before taking action.

Unlike the FORMAT UNIT command, these commands seem designed to work in the background. So they will return quickly (although sbc5r01.pdf does not state that) and the disk will be placed in a reduced functionality state where only a specified number of commands will be executed (e.g. INQUIRY and REPORT LUNS) until the operation is complete. Other commands will receive sense data with a sense key of NOT READY and an additional sense code of 'Depopulation in progress' (for RMEAT) or 'Depopulation restoration in progress' (for RSEAR).

The REMOVE ELEMENT AND TRUNCATE has a close relative in ZBC-2 called the REMOVE ELEMENT AND MODIFY ZONES [RMEMZ] command. See the sg_zone utility for an implementation of the latter command.

The difference between RMEAT and RMEMZ is that the former "changes the association between LBAs and physical blocks" and the latter does not change that association. Zones affected by the RMEMZ command are placed into the zone condition: "Offline".

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

-c, --capacity=RC

RC stands for Requested Capacity and is the number of logical blocks the DEVICE should have after the element is removed with the RMEAT command. The default value is 0 which allows the DEVICE to decide what the reduced capacity will be after the element removal. The RSEAR command ignores this value.

-e, --element=EID

where EID is an element identifier which is a 32 bit unsigned integer starting at one. This field is used by the RMEAT command and ignored otherwise. The default value is zero (which is invalid). So the user needs to supply a valid element identifier when --remove is used.

-h, --help

output the usage message then exit.

-q, --quick

the default action (i.e. when this option is not given) is to give the user 15 seconds to reconsider doing a remove or restore element operation on the DEVICE. When this option is given that step (i.e. the 15 second warning period) is bypassed.

-r, --remove

causes the REMOVE ELEMENT AND TRUNCATE command to be sent to the DEVICE. In practice, --element=EID needs to be also given.

-R, --restore

causes the RESTORE ELEMENTS AND REBUILD command to be sent to the DEVICE.

-t, --timeout=SE

where SE is the command timeout in seconds. The default is 60 seconds and if 0 is given, it is mapped to 60. An alternate long form is --tmo=SE.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
Once an element is removed successfully it is termed as "depopulated". Depopulated elements that have the 'Restoration Allowed' (RALWD) bit set (see sg_get_elem_status) are candidates for future restoration.

A (storage) element of a rotating hard disk is one side of a platter typically associated with one head. Such hard disks typically have multiple platters with two heads per platter (i.e. one head each side of the platter).

## EXIT STATUS
The exit status of sg_rem_rest_elem 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 © 2022-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_get_elem_status,sg_zone(sg3_utils)


title: sg_rep_density(8)

text:
# sg_rep_density(8)

## NAME
sg_rep_density - send SCSI REPORT DENSITY SUPPORT command

## SYNOPSIS
sg_rep_density [--help] [--hex] [--inhex=FN] [--maxlen=LEN] [--media] [--raw] [--readonly] [--typem] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SCSI REPORT DENSITY command to DEVICE and outputs the data returned. This command is tape drive specific. This command is found in the SSC-5 draft standard, revision 6 (ssc5r06.pdf). This command was present in the SSC-2 standard (ANSI INCITS 380-2003).

By default this utility requests the density code descriptors supported by the DEVICE (e.g. a tape drive) and decodes the response. If the --typem option is given it fetches the medium type descriptors supported by the DEVICE and decodes the response. When the --media option is given the density code or medium type descriptors supported by the media inside the DEVICE (e.g. a tape cartridge) are fetched.

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

-h, --help

output the usage message then exit.

-H, --hex

output the response in hexadecimal to stdout. When used once the whole response is output in ASCII hexadecimal, prefixed by an address (starting at 0) on each line. When used twice the whole response is output in hexadecimal with no leading address (on each line).

Using this option three times will produce output that can be redirected to a file and later given to another invocation using the --inhex=FN option.

-i, --inhex=FN

where FN is a file name whose contents are assumed to be ASCII hexadecimal. If DEVICE is also given then DEVICE is ignored, a warning is issued and the utility continues, decoding the file named FN. 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.

-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 8192 is used. The maximum allowed value of LEN is 65535.

-M, --media

sets the MEDIA bit in the cdb which causes the density codes (or medium types) supported by the tape cartridge in the drive to be placed in the response. The default is to request the density codes (or medium types) supported by the tape drive itself.

If there is no "medium" (e.g. tape cartridge) present in the drive the SCSI command will fail with a "not ready" sense key.

-r, --raw

output the SCSI response (i.e. the data-out buffer) in binary (to stdout) unless the --inhex=FN option is given.

When used together with the --inhex=FN option then the contents of FN are treated as binary (rather than hexadecimal).

-R, --readonly

open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write.

-t, --typem

sets the MEDIUM TYPE bit in the cdb which causes the medium types supported by the tape drive (or tape cartridge) to be placed in the response. The default is to request the density codes.

-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_rep_density 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 © 2022-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
sg3_utils(sg3_utils)


title: sg_rep_pip(8)

text:
# sg_rep_pip(8)

## NAME
sg_rep_pip - send SCSI REPORT PROVISIONING INITIALIZATION PATTERN command

## SYNOPSIS
sg_rep_pip [--help] [--hex] [--maxlen=LEN] [--raw] [--readonly] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SCSI REPORT PROVISIONING INITIALIZATION PATTERN command to DEVICE and outputs the data returned. This command is found in the SBC-4 draft standard, revision 21 (sbc4r21.pdf).

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

-h, --help

output the usage message then exit.

-H, --hex

output the response in hexadecimal to stdout. When used once the whole response is output in ASCII hexadecimal, prefixed by an address (starting at 0) on each line. When used twice the whole response is output in hexadecimal with no leading address (on each line). The default action is the same as giving the --hex option once.

-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 8192 is used. The maximum allowed value of LEN is 1048576.

-r, --raw

output the SCSI response (i.e. the data-out buffer) in binary (to stdout).

-R, --readonly

open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write.

-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_rep_pip 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 © 2020-2022 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
sg3_utils(sg3_utils)


title: sg_rep_zones(8)

text:
# sg_rep_zones(8)

## NAME
sg_rep_zones - send SCSI REPORT ZONES, REALMS or ZONE DOMAINS command

## SYNOPSIS
sg_rep_zones [--brief] [--domain] [--find=ZT] [--force] [--help] [--hex] [--inhex=FN] [--json[=JO]] [--js-file=JFN] [--locator=LBA] [--maxlen=LEN] [--num=NUM] [--partial] [--raw] [--readonly] [--realm] [--report=OPT] [--start=LBA] [--statistics] [--verbose] [--version] [--wp] DEVICE

## DESCRIPTION
Sends a SCSI REPORT ZONES, REPORT REALMS or REPORT ZONE DOMAINS command to DEVICE and decodes (or simply outputs) the data returned. These commands are found in the ZBC-2 draft standard, revision 12 (zbc2r12.pdf). Only the REPORT ZONES command is defined in the original ZBC standard (INCITS 536-2017) and it is the default for this utility.

The REPORT ZONE DOMAINS command will be sent (and decoded) when the --domain option is given. The REPORT REALMS command will be sent (and decoded) when the --realm option is given.

Rather than send a SCSI command to DEVICE, if the --inhex=FN option is given, then the contents of the file named FN are decoded as ASCII hex (or binary if --raw is also given) and then processed as if it was the response of the command. By default the REPORT ZONES command response is assumed; if the --domain or --realm option is given then the corresponding command response is assumed.

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

-b, --brief

even though a ZBC disk will typically limit the size of the response to the REPORT ZONES command (e.g. due to the "allocation length" field), this may still be potentially a lot of output. This option will only decode and output fields found in the response header plus fields from the last descriptor in the current response.

-d, --domain

send or decode the SCSI REPORT ZONE DOMAINS command.

-F, --find=ZT

where ZT is a zone type number or an abbreviation for a zone type. If ZT is prefixed by either '-' or '!' then the check for equality is inverted to be a check for inequality. IOWs it does a: find the first occurrence that is not the given zone type.

The algorithm used by this option takes into account the --hex, --maxlen=LEN, --num=NUM, --report=OPT and --start=LBA options, if given, and ignores other options. It is only implemented for the Report zones command currently. The algorithm may call the Report zones command repeatedly, with the PARTIAL bit set and the Zone start LBA field being increased as it goes. This continues until either there is a match on the ZT condition, --num=NUM is exhausted or the number of zones is exhausted.

The ZT numbers and abbreviations are listed when the --help option is given twice. Warning: using '!' for inverting the condition may not be so practical as the shell (e.g. bash) may interpret '!' as having special meaning. Placing single quotes around ZT fixes the problem for the bash shell (e.g. --find='!c' meaning find the first zone whose type is not conventional).

-f, --force

when decoding the response to this command, certain sanity checks are done and if they fail a message is sent to stderr and a non-zero exit status is set. If this option is given those sanity checks are bypassed.

-h, --help

output the usage message then exit. When given twice, additional usage information is output.

-H, --hex

output the response in hexadecimal to stdout. When used once the whole response is output in ASCII hexadecimal with a leading address (starting at 0) on each line. When used twice each zone descriptor in the response is output separately in hexadecimal. When used thrice the whole response is output in hexadecimal with no leading address (on each line).

When this option is used twice, it can be useful with either the --brief or --find=ZT option to only output the header and zone descriptor in hex that those two options would otherwise print in ASCII in the absence of the --hex option.

The output format when this option is given thrice is suitable for a later invocation with the --inhex=FN option.

-i, --inhex=FN

where FN is a file name whose contents are assumed to be ASCII hexadecimal. If DEVICE is also given then DEVICE is ignored, a warning is issued and the utility continues, decoding the file named FN. 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.

Note that by default this utility assumes then contents are the response from a REPORT ZONES command. Use the --domain or --realm option for decoding the other two commands.

-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, --locator=LBA

where LBA plays a similar role as it does in --start=LBA. It is the field name used in the REPORT REALMS and REPORT ZONE DOMAINS commands.

-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 16384 is used. The maximum allowed value of LEN is 2097152.

-n, --num=NUM

where NUM is the (maximum) number of zone descriptors to print out. The default value is zero which is taken to mean print out all zone descriptors returned by the REPORT ZONES command.

-p, --partial

set the PARTIAL bit in the cdb. Without the PARTIAL bit set a ZBC disk will attempt to form a response with all zones from LBA to the end of the disk. If there are a large number of zones (e.g. > 10,000) this large response will be truncated so that it doesn't exceed the "allocation length" field in the cdb (see --maxlen=LEN). The advantage of doing this is that the number of (remaining) zones on the disk can be calculated. The disadvantage is the amount of time that may take.

With the PARTIAL bit set in the cdb, only the number of zones implied by the "allocation length" field are fetched. This may be considerably faster than the same command without the PARTIAL bit set.

When iterating through the zones on a ZBC disk, the process will be faster when the PARTIAL bit is set. Typically --start=LBA is set to zero or the [LBA + zone_length] of the last zone reported in the previous iteration.

-r, --raw

output response in binary (to stdout) unless the --inhex=FN option is also given. In that case the input file name (FN) is decoded as binary (and the output is _not_ in binary (but may be hex)).

-R, --readonly

open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write.

-e, --realm

send or decode the SCSI REPORT REALMS command.

-o, --report=OPT

where OPT will become the contents of the REPORTING OPTION field in the cdb. The reporting options differ between REPORT ZONES, REPORT ZONE DOMAINS and REPORT REALMS. If the --help option is given twice ( or the equivalent '-hh') a list of available reporting options (as of writing) for each command is output.

The default value for REPORT ZONES is 0 which means report a list of all zones. Some other values are 1 for list zones with a zone condition of empty; 2 for list zones with a zone condition of implicitly opened; 3 for list zones with a zone condition of explicitly opened; 4 for list zones with a zone condition of closed; 5 for list zones with a zone condition of full; 6 for list zones with a zone condition of read only; 7 for list zones with a zone condition of offline. Other values are 0x10 for list zones with 'RWP recommended' set to true; 0x11 for list zones with non-sequential write resource active set to true, 0x3e for list zones apart from GAP zones, and 0x3f for list zones with a zone condition of 'not write pointer'.

-s, --start=LBA

where LBA is at the start or within the first zone to be reported. The default value is 0. If LBA is not a zone start LBA then the preceding zone start LBA is used for reporting. Assumed to be in decimal unless prefixed with '0x' or has a trailing 'h' which indicate hexadecimal.

The zone start LBA field used in the REPORT ZONES command was changed to the zone domain/realm locator field for the two newer ZBC-2 commands. For this utility --locator=LBA and --start=LBA are interchangeable.

-S, --statistics

reviews all or a limited number of report zones, collects statistics and prints them (on stdout). The number of zones reviewed may be limited by any combination of --num=NUM, --report=OPT and --start=LBA options. The long option name may be abbreviated to --stats.

-v, --verbose

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

-V, --version

print the version string and then exit.

-w, --wp

print the write pointer (in hex) only. In the absence of errors, then a hex LBA will be printed on each line, one line for each zone. Can be usefully combined with the --num=NUM and --start=LBA options.

## EXIT STATUS
The exit status of sg_rep_zones 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 © 2014-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_reset_wp,sg_zone,sg3_utils_json(sg3_utils), zbd(libzbd), blkzone(util-linux)


title: sg_requests(8)

text:
# sg_requests(8)

## NAME
sg_requests - send one or more SCSI REQUEST SENSE commands

## SYNOPSIS
sg_requests [--desc] [--error] [--help] [--hex] [--maxlen=LEN] [--num=NUM] [--number=NUM] [--progress] [--raw] [--status] [--time] [--timeout=SE] [--verbose] [--version] DEVICE

## DESCRIPTION
Send SCSI REQUEST SENSE command to DEVICE and output the parameter data response which is expected to be in sense data format. Both fixed and descriptor sense data formats are supported.

Multiple REQUEST SENSE commands can be sent with the --num=NUM option. This can be used for timing purposes or monitoring the progress indication.

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

-d, --desc

sets the DESC bit in the REQUEST SENSE SCSI cdb. The DEVICE should return sense data in descriptor (rather than fixed) format. This will only occur if the DEVICE recognizes descriptor format (SPC-3 and later). If the device is pre SPC-3 then setting a bit in a reserved field may cause a check condition status with an illegal request sense key, but will most likely be ignored.

-e, --error

when used once it changes the REQUEST SENSE opcode from 0x3 to 0xff which should be rejected by the DEVICE. There is a small chance that the device vendor has implemented a vendor specific command at that opcode (0xff). When used twice the pass-through call to send the SCSI command is bypassed. The idea here is to measure the user space overhead of this package's library to set up and process the response of a SCSI command. This option will be typically used with the --num=NUM and --time options where NUM is a large number (e.g. 1000000).

-h, --help

output the usage message then exit.

-H, --hex

output response in ASCII hexadecimal.

-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. The maximum value of LEN is 255 (but SPC-4 recommends 252).

-n, --num=NUM

perform NUM SCSI REQUEST SENSE commands, stopping when either NUM is reached or an error occurs. The default value for NUM is 1 .

--number=NUM

same action as --num=NUM. Added for compatibility with sg_turs.

-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. Exits when NUM is reached or there are no more progress indications. Ignores --hex, --raw and --time options. See NOTES section below.

-r, --raw

output response in binary (to stdout).

-s, --status

if the REQUEST SENSE command finished without error (as indicated by its SCSI status) then the contents of the parameter data are analysed as sense data and the exit status is set accordingly. The default action (i.e. when this option is not given) is to ignore the contents of the parameter data for the purposes of setting the exit status. Some types of error set a sense key of "NO SENSE" with non-zero information in the additional sense code (e.g. the FAILURE PREDICTION THRESHOLD EXCEEDED group of codes); this results in an exit status value of 10. If the sense key is "NO SENSE" and both asc and ascq are zero then the exit status is set to 0 . See the sg3_utils(8) man page for exit status values.

-t, --time

time the SCSI REQUEST SENSE command(s) and calculate the average number of operations 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 the level of verbosity, (i.e. debug output). Additionally the response (if received) is output in ASCII-HEX. Use this option multiple times for greater verbosity.

-V, --version

print the version string and then exit.

## NOTES
In SCSI 1 and 2 the REQUEST SENSE command was very important for error and warning processing in SCSI. The autosense capability rendered this command almost superfluous.

However recent SCSI drafts (e.g. SPC-4 rev 14 and SBC-3 rev 14) increase the utility of the REQUEST SENSE command. Idle and standby (low) power conditions can be detected with this command.

The REQUEST SENSE command is not marked as mandatory in SPC-3 (i.e. for all SCSI devices) but is marked as mandatory in SBC-2 (i.e. for disks), SSC-3 (i.e. for tapes) and MMC-4 (i.e. for CD/DVD/HD-DVD/BD drives).

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.

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

Early standards suggested that the SCSI TEST UNIT READY command be used for polling the progress indication (see the sg_turs utility). Since SPC-3 the standards suggest that the SCSI REQUEST SENSE command should be used instead.

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_requests 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
sg_turs (sg3_utils)


title: sg_reset(8)

text:
# sg_reset(8)

## NAME
sg_reset - sends SCSI device, target, bus or host reset; or checks reset state

## SYNOPSIS
sg_reset [--bus] [--device] [--help] [--host] [--no-esc] [--target] [--verbose] [--version] DEVICE

## DESCRIPTION
The sg_reset utility with no options (just a DEVICE) reports on the reset state (e.g. if a reset is underway) of the DEVICE. When given a --device, --target, --bus or --host option it requests a device, target, bus or host reset respectively.

A device reset is applied to the Logical Unit (LU) corresponding to DEVICE. It is most likely implemented by a Low level Driver (LLD) in Linux as a LOGICAL UNIT RESET task management function.

The ability to reset a SCSI target was added in Linux kernel 2.6.27 . A LLD may send Low level Drivers (LLDs) the I_T NEXUS RESET task management function. Alternatively it may use a transport mechanism to do the same thing (e.g. a hard reset on the link containing a SAS target).

In the Linux kernel 2.6 and 3 series this utility can be called on sd, sr (cd/dvd), st or sg device nodes; if the user has appropriate permissions.

Users of this utility can check whether a reset recovery is already underway before trying to send a new reset with this utility. Calling this utility with no options, just the DEVICE, will do such a check.

## OPTIONS
-b, --bus

attempt a SCSI bus reset. A bus reset is a SCSI Parallel Interface (SPI) concept not found in modern transports. A recent LLD may implement it as a series of resets on targets that might be considered as siblings to the target on the DEVICE path.

-d, --device

attempt a SCSI device reset. This would typically involve sending a LOGICAL UNIT RESET task management function to DEVICE.

-z, --help

print the usage message then exit.

-H, --host

attempt a host reset. The "host" in this context is often called a Host Bus Adapter (HBA) and contains one or more SCSI initiators.

-N, --no-esc

without this option, if a device reset (--device) fails then it will escalate to a target reset. And if a target reset (--target) fails then it will escalate to a bus reset. And if a bus reset (--bus) fails then it will escalate to a host reset. With this option only the requested reset is attempted. An alternate option name of --no-escalate is also accepted.

--no-escalate

The same as -N, --no-esc.

-t, --target

attempt a SCSI target reset. A SCSI target contains one or more LUs. This would typically involve sending a I_T NEXUS RESET task management function to DEVICE There may be a transport action that is equivalent (e.g. in SAS a hard reset on the link that contains the target).

-v, --verbose

increase the degree of verbosity (debug messages).

-V, --version

prints the version string then exits.

## NOTES
The error recovery code within the Linux kernel (SCSI mid-level) when faced with a SCSI command timing out and no response from the device (LU) does the following. First it tries a device reset and if that is not successful tries a target reset. If that is not successful it tries a bus reset. If that is not successful it tries a host reset. The "device,target,bus,host" order is the reset escalation that the --no-esc option attempts to stop. In large storage configurations the escalation may be (very) undesirable.

This utility calls the SG_SCSI_RESET ioctl and as of lk 3.10.7 the --no-esc option is not supported. Patches to implement this functionality may be accepted in lk 3.18 or 3.19 .

SAM-4 and 5 define a hard reset, a LOGICAL UNIT RESET and a I_T NEXUS RESET. A hard reset is defined to be a power on condition, a microcode change or a transport reset event. LOGICAL UNIT RESET and I_T NEXUS RESET can be requested via task management functions (and support for LOGICAL UNIT RESET is mandatory). In Linux the SCSI subsystem leaves it up to the LLDs as to exactly what type (if any) of reset is performed. The "bus reset" is SCSI Parallel Interface (SPI) concept that may not map well to recent SCSI transports so it may be a dummy operation. A "host reset" attempts to re-initialize the HBA that the request passes through en route to the DEVICE. Note that a "host reset" and a "bus reset" may cause collateral damage.

This utility does not allow individual SCSI commands to be aborted. SAM-4 defines ABORT TASK and ABORT TASK SET task management functions for that.

Prior to SAM-3 there was a TARGET RESET task management function. And in SAM-4 I_T NEXUS RESET appeared which seems closely related: the "I_T" stands for Initiator-Target.

Transports may have their own types of resets not supported by this utility. For example SAS has a link reset in which both ends of a physical link (e.g. between a SAS expander and a SAS tape drive) renegotiate their connection.

Prior to version 0.57 of this utility the command line had short options only (e.g. -d but not --device). Also -h invoked a host reset while in the current version -h is equivalent to --help and both -H and --host invoke a host reset. For backward compatibility define the environment variable SG3_UTILS_OLD_OPTS or SG_RESET_OLD_OPTS . In this case -h will invoke a host reset and the output will be verbose as it was previously (equivalent to using the --verbose option now). For example:

SG_RESET_OLD_OPTS=1 sg_reset -h /dev/sg1

sg_reset: starting host reset

sg_reset: completed host reset

## ENVIRONMENT VARIABLES
Since sg3_utils version 1.23 the environment variables SG3_UTILS_OLD_OPTS or SG_RESET_OLD_OPTS can be given. When either is present this utility will expect the older command line options as outlined in the NOTES section.

## AUTHORS
Written by Douglas Gilbert.

## COPYRIGHT
Copyright © 1999-2022 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.


title: sg_reset_wp(8)

summary: send SCSI RESET WRITE POINTER command

text:
# sg_reset_wp(8)

## NAME
sg_reset_wp - send SCSI RESET WRITE POINTER command

## SYNOPSIS
sg_reset_wp [--all] [--count=ZC] [--help] [--verbose] [--version] [--zone=ID] DEVICE

## DESCRIPTION
Sends a SCSI RESET WRITE POINTER command to the DEVICE. This command is described in ZBC standard (INCITS 536-2016) and the draft ZBC-2 documents at T10 (e.g. zbc2r12.pdf).

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

-a, --all

sets the ALL field in the cdb. This causes a reset write pointer operation of all open zones and full zones. When this option is given then the --zone=ID option is ignored. Either this option or the --zone=ID option is required.

-C, --count=ZC

ZC is placed in the Zone Count field in the cdb of the RESET WRITE POINTER command supported by this utility. ZC should be a value from 0 to 65535 (0xffff) inclusive.

The action that the DEVICE takes with this option depends on whether the --all option is set. See the RESET WRITE POINTER command description (e.g. section 5.9, table 46 in zbc2r12.pdf).

-h, --help

output the usage message then exit.

-v, --verbose

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

-V, --version

print the version string and then exit.

-z, --zone=ID

where ID is placed in the cdb's ZONE ID field. A zone id is a zone start logical block address (LBA). This causes a reset write pointer operation on the zone identified by the ZONE ID field. The default value is 0. Either this option or the --all option is required. ID is assumed to be in decimal unless prefixed with '0x' or has a trailing 'h' which indicate hexadecimal.

## NOTES
The Zones Emptied log parameter in the Zoned Block Device Statistics log page counts the number of times the RESET WRITE POINTER command has been (successfully) invoked.

## EXIT STATUS
The exit status of sg_reset_wp 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 © 2014-2022 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_rep_zones,sg_zone(sg3_utils)


title: sg_rmsn(8)

text:
# sg_rmsn(8)

## NAME
sg_rmsn - send SCSI READ MEDIA SERIAL NUMBER command

## SYNOPSIS
sg_rmsn [--help] [--raw] [--readonly] [--verbose] [--version] DEVICE

## DESCRIPTION
Send a SCSI READ MEDIA SERIAL NUMBER command to DEVICE and outputs the response.

This command is described in SPC-3 found at www.t10.org . It was originally added to SPC-3 in revision 11 (2003/2/12). It is not an mandatory command and the author has not seen any SCSI devices that support it.

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

-h, --help

output the usage message then exit.

-r, --raw

sends the serial number (if found) to stdout. This output may contain non-printable characters (e.g. the serial number is padded with NULLs at the end so its length is a multiple of 4). The default action is to print the serial number out in ASCII-HEX with ASCII characters to the right. All error messages are sent to stderr.

-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 READ MEDIA SERIAL NUMBER 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.

## NOTES
Device identification information is also found in a standard INQUIRY response and its VPD pages (see sg_vpd). The relevant VPD pages are the "device identification page" (VPD page 0x83) and the "unit serial number" page (VPD page 0x80).

The MMC-4 command set for CD/DVD/HD-DVD/BD drives has a "media serial number" feature (0x109) [and a "logical unit serial number" feature]. These can be viewed with sg_get_config.

## EXIT STATUS
The exit status of sg_rmsn 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 © 2005-2012 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(sg3_utils), sg_get_config(sg3_utils)


title: sg_rtpg(8)

text:
# sg_rtpg(8)

## NAME
sg_rtpg - send SCSI REPORT TARGET PORT GROUPS command

## SYNOPSIS
sg_rtpg [--decode] [--help] [--hex] [--raw] [--readonly] [--verbose] [--version] DEVICE

## DESCRIPTION
Send a SCSI REPORT TARGET PORT GROUPS command to DEVICE and outputs the response.

Target port group access is described in SPC-3 and SPC-4 found at www.t10.org . The most recent draft of SPC-4 is revision 37 in which target port groups are described in section 5.15 .

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

-d, --decode

decodes the status code and asymmetric access state from each target port group descriptor returned. The default action is not to decode these values.

-e, --extended

use extended header format for parameter data. This sets the PARAMETER DATA FORMAT field in the cdb to 1.

-h, --help

output the usage message then exit.

-H, --hex

output response in hex (rather than partially or fully decode it).

-r, --raw

output response in binary to stdout.

-R, --readonly

open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
The Report Target Port Groups command should be supported whenever the TPGS bits in a standard INQUIRY response are greater than zero. [View with sg_inq utility.]

## EXIT STATUS
The exit status of sg_rtpg 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-2014 Christophe Varoqui and 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)


title: sg_safte(8)

summary: access SCSI Accessed Fault\-Tolerant Enclosure (SAF\-TE) device

text:
# sg_safte(8)

## NAME
sg_safte - access SCSI Accessed Fault-Tolerant Enclosure (SAF-TE) device

## SYNOPSIS
sg_safte [--config] [--devstatus] [--encstatus] [--flags] [--help] [--hex] [--insertions] [--raw] [--usage] [--verbose] [--version] DEVICE

## DESCRIPTION
Fetches enclosure status (via a SCSI READ BUFFER command). The DEVICE should be a SAF-TE device which may be a storage array controller (INQUIRY peripheral device type 0xc) or a generic processor device (INQUIRY peripheral device type 0x3).

If no options are given (only the DEVICE argument) then the overall enclosure status as reported by the option --config is reported.

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

-c, --config

will issues a Read Enclosure Configuration (READ BUFFER ID 0) cdb to the device, which returns a list of the enclosure hardware resources.

-d, --devstatus

will issue a Read Device Slot Status (READ BUFFER ID 4) cdb to the device, which returns information about the current state of each drive or slot.

-s, --encstatus

will issue a Read Enclosure Status (READ BUFFER ID 1) cdb to the device, which returns the operational state of the components.

-f, --flags

will issue a Read Global Flags (READ BUFFER ID 5) cdb to the device, which read the most recent state of the global flags of the RAID processor device.

-h, --help

output the usage message then exit.

-H, --hex

output the response to a READ BUFFER command in ASCII hex to stdout. If used once, output the response to the first READ BUFFER command (i.e. with buffer_id=0). This should be the enclosure configuration. If used twice (or more often), the response to subsequent READ BUFFER commands is output.

-i, --insertions

will issue a Read Device Insertions (READ BUFFER ID 3) cdb to the device, which returns information about the number of times devices have been inserted whilst the RAID system was powered on.

-r, --raw

output the response to a READ BUFFER command in binary to stdout. If used once, output the response to the first READ BUFFER command (i.e. with buffer_id=0). This should be the enclosure configuration. If used twice (or more often), the response to subsequent READ BUFFER commands is output.

-u, --usage

will issue a Read Usage Statistics (READ BUFFER ID 2) cdb to the device, which returns the information on total usage time and number of power-on cycles of the RAID device.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
This implementation is based on the intermediate review document dated 19970414 and named "SR041497.pdf". So it is quite old. Intel and nStor are the authors. Intel have a zip archive containing this and related documents in the "SAF-TE: SCSI Accessed Fault Tolerant Enclosures Interface Specification" section of this page:

https://www.intel.com/content/www/us/en/servers/ipmi/ipmi-technical-resources.html

Similar functionality is provided by SPC-4 SCSI Enclosure Services (SES) devices (Peripheral device type 0xd), which can be queried with the sg_ses utility.

## EXAMPLES
To view the configuration:

sg_safte /dev/sg1

To view the device slot status:

sg_safte --devstatus /dev/sg1

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

## AUTHORS
Written by Hannes Reinecke and Douglas Gilbert.

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

## COPYRIGHT
Copyright © 2004-2016 Hannes Reinecke and 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, sg_ses (in sg3_utils package); safte-monitor (internet)


title: sg_sanitize(8)

text:
# sg_sanitize(8)

## NAME
sg_sanitize - remove all user data from disk with SCSI SANITIZE command

## SYNOPSIS
sg_sanitize [--ause] [--block] [--count=OC] [--crypto] [--dry-run] [--desc] [--early] [--fail] [--help] [--invert] [--ipl=LEN] [--overwrite] [--pattern=PF] [--quick] [--test=TE] [--timeout=SECS] [--verbose] [--version] [--wait] [--zero] [--znr] DEVICE

## DESCRIPTION
This utility invokes the SCSI SANITIZE command. This command was first introduced in the SBC-3 revision 27 draft. The purpose of the sanitize operation is to alter the information in the cache and on the medium of a logical unit (e.g. a disk) so that the recovery of user data is not possible. If that user data cannot be erased, or is in the process of being erased, then the sanitize operation prevents access to that user data.

Once a SCSI SANITIZE command has successfully started, then user data from that disk is no longer available. Even if the disk is power cycled, the sanitize operation will continue after power is re-instated until it is complete.

This utility requires either the --block, --crypto, --fail or --overwrite option. With the --block, --crypto or --overwrite option the user is given 15 seconds to reconsider whether they wish to erase all the data on a disk, unless the --quick option is given in which case the sanitize operation starts immediately. The disk's INQUIRY response strings are printed out just in case the wrong DEVICE has been given.

If the --early option is given then this utility will exit soon after starting the SANITIZE command with the IMMED bit set. The user can monitor the progress of the sanitize operation with the "sg_requests --num=9999 --progress" which sends a REQUEST SENSE command every 30 seconds. Otherwise if the --wait option is given then this utility will wait until the SANITIZE command completes (or fails) and that can be many hours.

If the --wait option is not given then the SANITIZE command is started with the IMMED bit set. If neither the --early nor the --wait options are given then this utility sends a REQUEST SENSE command after every 60 seconds until there are no more progress indications in which case this utility exits silently. If additionally the --verbose option is given the exit will be marked by a short message that the sanitize seems to have succeeded.

## 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, --ause

sets the AUSE bit in the cdb. AUSE is an acronym for "allow unrestricted sanitize exit". The default action is to leave the AUSE bit cleared.

-B, --block

perform a "block erase" sanitize operation.

-c, --count=OC

where OC is the "overwrite count" associated with the "overwrite" sanitize operation. OC can be a value between 1 and 31 and 1 is the default.

-C, --crypto

perform a "cryptographic erase" sanitize operation. Note that this erase is often very quick as it simply overwrites an internal cryptographic key with a new value. Those keys are not accessible to users and encrypt all data written then decrypt all data read from the media. The primary reason for doing that is to make this operation fast. This operation can not be reversed.

-d, --desc

sets the DESC field in the REQUEST SENSE command used for polling. By default this field is set to zero. A REQUEST SENSE polling loop is used after the SANITIZE command is issued (assuming that neither the --early nor the --wait option have been given) to check on the progress of this command as it can take some time.

-D, --dry-run

this option will parse the command line, do all the preparation but bypass the actual SANITIZE command.

-e, --early

the default action of this utility is to poll the disk every 60 seconds to fetch the progress indication until the sanitize is finished. When this option is given this utility will exit "early" as soon as the SANITIZE command with the IMMED bit set to 1 has been acknowledged. This option and --wait cannot both be given.

-F, --fail

perform an "exit failure mode" sanitize operation. Typically requires the preceding SANITIZE command to have set the AUSE bit.

-h, --help

print out the usage information then exit.

-i, --ipl=LEN

set the initialization pattern length to LEN bytes. By default it is set to the length of the pattern file (PF) or 4 if the --zero option is given. Only active when the --overwrite option is also given. It is the number of bytes from the PF file that will be used as the initialization pattern (if the --zero option is not given). The minimum size is 1 byte and the maximum is the logical block size of the DEVICE (and not to exceed 65535). If LEN exceeds the PF file size then the initialization pattern is padded with zeros.

-I, --invert

set the INVERT bit in the overwrite service action parameter list. This only affects the "overwrite" sanitize operation. The default is a clear INVERT bit. When the INVERT bit is set then the initialization pattern is inverted between consecutive overwrite passes.

-O, --overwrite

perform an "overwrite" sanitize operation. When this option is given then the --pattern=PF or the --zero option is required.

-p, --pattern=PF

where PF is the filename of a file containing the initialization pattern required by an "overwrite" sanitize operation. The length of this file will be used as the length of the initialization pattern unless the --ipl=LEN option is given. The length of the initialization pattern must be from 1 to the logical block size of the DEVICE.

-Q, --quick

the default action (i.e. when the option is not given) is to give the user 15 seconds to reconsider doing a sanitize operation on the DEVICE. When this option is given that step (i.e. the 15 second warning period) is skipped.

-T, --test=TE

set the TEST field in the overwrite service action parameter list. This only affects the "overwrite" sanitize operation. The default is to place 0 in that field.

-t, --timeout=SECS

where SECS is the number of seconds used for the timeout on the SANITIZE command.

-v, --verbose

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

-V, --version

print the version string and then exit.

-w, --wait

the default action (i.e. without this option and the --early option) is to start the SANITIZE command with the IMMED bit set then poll for the progress indication with the REQUEST SENSE command until the sanitize operation is complete (or fails). When this option is given (and the --early option is not given) then the SANITIZE command is started with the IMMED bit clear. For a large disk this might take hours. [A cryptographic erase operation could potentially be very quick.]

-z, --zero

with an "overwrite" sanitize operation this option causes the initialization pattern to be zero (4 zeros are used as the initialization pattern). Cannot be used with the --pattern=PF option. If this option is given twice (e.g. '-zz') then 0xff is used as the initialization byte.

-Z, --znr

sets ZNR bit (zoned no reset) in cdb. Introduced in the SBC-4 revision 7 draft.

## NOTES
The SCSI SANITIZE command is closely related to the ATA SANITIZE command, both are relatively new with the ATA command being the first one defined. The SCSI to ATA Translation (SAT) definition for the SCSI SANITIZE command appeared in the SAT-3 revision 4 draft.

When a SAT layer is used to a (S)ATA disk then for OVERWRITE the initialization pattern must be 4 bytes long. So this means either the --zero option may be given, or a pattern file (with the --pattern=PF option) that is 4 bytes long or set to that length with the --ipl=LEN option.

The SCSI SANITIZE command is related to the SCSI FORMAT UNIT command. It is likely that a block erase sanitize operation would take a similar amount of time as a format on the same disk (e.g. 9 hours for a 2 Terabyte disk). The primary goal of a format is the configuration of the disk at the end of a format (e.g. different logical block size or protection information added). Removal of user data is only a side effect of a format. With the SCSI SANITIZE command, removal of user data is the primary goal. If a sanitize operation is interrupted (e.g. the disk is power cycled) then after power up any remaining user data will not be available and the sanitize operation will continue. When a format is interrupted (e.g. the disk is power cycled) the drafts say very little about the state of the disk. In practice some of the original user data may remain and the format may need to be restarted.

Finding out whether a disk (SCSI or ATA) supports SANITIZE can be a challenge. If the user really needs to find out and no other information is available then try 'sg_sanitize --fail -vvv <device>' and observe the sense data returned may be the safest approach. Using the --fail variant of this utility should have no effect unless it follows an already failed sanitize operation. If the SCSI REPORT SUPPORTED OPERATION CODES command (see sg_opcodes) is supported then using it would be a better approach for finding if sanitize is supported.

If using the dd command to check the before and after data of a particular block (i.e. check the erase actually worked) it is a good idea to use the 'iflag=direct' operand. Otherwise the first read might be cached and returned when the same LBA is read a little later. Obviously this utility should only be used to sanitize data on a disk whose mounted file systems (if any) have been unmounted prior to the erase!

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

As a precaution if this utility is called with no options then apart from printing a usage message, nothing happens:

sg_sanitize /dev/sdm

To do a "block erase" sanitize the --block option is required. The user will be given a 15 second period to reconsider, the SCSI SANITIZE command will be started with the IMMED bit set, then this utility will poll for a progress indication with a REQUEST SENSE command until the sanitize operation is finished:

sg_sanitize --block /dev/sdm

To start a "block erase" sanitize and return from this utility once it is started (but not yet completed) use the --early option:

sg_sanitize --block --early /dev/sdm

If the 15 second reconsideration time is not required add the --quick option:

sg_sanitize --block --quick --early /dev/sdm

To do an "overwrite" sanitize a pattern file may be given:

sg_sanitize --overwrite --pattern=rand.img /dev/sdm

If the length of that "rand.img" is 512 bytes (a typically logical block size) then to use only the first 17 bytes (repeatedly) in the "overwrite" sanitize operation:

sg_sanitize --overwrite --pattern=rand.img --ipl=17 /dev/sdm

To overwrite with zeros use:

sg_sanitize --overwrite --zero /dev/sdm

## EXIT STATUS
The exit status of sg_sanitize is 0 when it is successful. Otherwise see the sg3_utils(8) man page. Unless the --wait option is given, the exit status may not reflect the success of otherwise of the format.

The Unix convention is that "no news is good news" but that can be a bit unnerving after an operation like sanitize, especially if it finishes quickly (i.e. before the first progress poll is sent). Giving the --verbose option once should supply enough additional output to settle those nerves.

## AUTHORS
Written by Douglas Gilbert.

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

## COPYRIGHT
Copyright © 2011-2020 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_requests(8), sg_format(8)


title: sg_sat_datetime(8)

text:
# sg_sat_datetime(8)

## NAME
sg_sat_datetime - report or set date and time on a ATA device

## SYNOPSIS
sg_sat_datetime [--dma] [--elapsed] [--format] [--help] [--hex] [--milliseconds=MS] [--readonly] [--seconds=SECS] [--srep] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SET DATE & TIME EXT or READ LOG [DMA] EXT command to the ATA DEVICE to set the date and time or read it from the Device Statistics log address(04h), General Statistics page (01h). These commands are found in the ATA Command Set (ACS-5) standard. ATA commands are sent using ATA PASS-THROUGH SCSI commands.

If either the --milliseconds=MS or --seconds=SECS option is given (and both can't be given) then the SET DATE & TIME command is sent. Otherwise, the READ LOG EXT command, or if the --dma option is used, the READ LOG DMA EXT command is sent to the device.

The date and time is sent and received from the DEVICE generally 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. If the date and time is not set after power-on reset, the value is the same as the device power-on hours in milliseconds.

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

-d, --dma

use READ LOG DMA EXT to read the date and time value from the device. Ignored if setting the date and time.

-e, --elapsed

assume the date and time from READ LOG [DMA] EXT 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.

This option is especially useful if the date and time has not been set. Per ACS-5, when not set, the date and time is initialized to the power-on hours of the device in milliseconds.

-f, --format

output the date and time formatted using the default locale.

-h, --help

output the usage message then exit.

-H, --hex

output the date and time in ASCII hexadecimal.

-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 ATA SET DATE & TIME EXT command.

-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 ATA SET DATE & TIME command. SECS is multiplied by 1000 before being used in the ATA SET DATE & TIME command.

-S, --srep

report the number of seconds since 1970-01-01 00:00:00 UTC. This is done by dividing the value returned by the ATA READ LOG [DMA] EXT command by 1000.

-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_sat_datetime is 0 when it is successful. Otherwise, see the sg3_utils(8) man page.

## NOTES
The DEVICE should immediately start accumulating time after the date and time is set. ie. If you set and then retrieve the date and time, the returned values will likely have increased.

The ACS-5 standard makes no provision for a power-safe date and time storage. Unless the device has vendor-specific power-safe capability, after a power-on reset, per ACS-5, the date and time should be the power-on hours of the device returned in milliseconds (or seconds if --srep option is used).

## 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_sat_datetime -S /dev/sg2

1681156506

\# date --date=@1681156506

Mon Apr 10 02:55:06 PM CDT 2023

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

Mon, 10 Apr 2023 14:55:06 -0500

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

\# date -R --date=@`sg_sat_datetime -S /dev/sg2`

Mon, 10 Apr 2023 14:55:06 -0500

Alternatively, the --format option can be used to format the date and time using the default locale.

\# sg_sat_datetime --format /dev/sg2

Mon Apr 10 15:02:54 2023

To set the date and time on the DEVICE to now (approximately) the following could be used:

\# date +%s

1681157099

\# sg_sat_datetime --seconds=1681157099 /dev/sg0

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

\# sg_sat_datetime --seconds=`date +%s` /dev/sg0

## AUTHORS
Written by Jeremy Bauer and Daniel Woeste with extensive use of sg_timestamp and sg_sat_read_gplog by Douglas Gilbert.

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

## COPYRIGHT
Copyright © 2023 Jeremy Bauer and Daniel Woeste of Western Digital Corporation

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

## SEE ALSO
sdparm(sdparm), sg_logs(sg3_utils), sg_timestamp(sg3_utils), sg_sat_read_gplog(sg3_utils)


title: sg_sat_identify(8)

text:
# sg_sat_identify(8)

## NAME
sg_sat_identify - send ATA IDENTIFY DEVICE command via SCSI to ATA Translation (SAT) layer

## SYNOPSIS
sg_sat_identify [--ck_cond] [--extend] [--help] [--hex] [--ident] [--len=CLEN] [--packet] [--raw] [--readonly] [--verbose] [--version] DEVICE

## DESCRIPTION
This utility sends either an ATA IDENTIFY DEVICE command or an ATA IDENTIFY PACKET DEVICE command to DEVICE and outputs the response. The devices that respond to these commands are ATA disks and ATAPI devices respectively. Rather than send these commands directly to the device they are sent via a SCSI transport which is assumed to contain a SCSI to ATA Translation (SAT) Layer (SATL). The SATL may be in an operating system driver, in host bus adapter firmware or in some external enclosure.

The SAT standard (SAT ANSI INCITS 431-2007, prior draft: sat-r09.pdf at www.t10.org) defines two SCSI "ATA PASS-THROUGH" commands: one using a 16 byte "cdb" and the other with a 12 byte cdb. This utility defaults to using the 16 byte cdb variant. SAT-4 revision 5 added a SCSI "ATA PASS-THROUGH(32)" command. SAT-2 and SAT-3 are now also standards: SAT-2 ANSI INCITS 465-2010 and SAT-3 ANSI INCITS 517-2015 . The SAT-4 project is near standardization and the most recent draft is sat4r06.pdf .

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

-c, --ck_cond

sets the CK_COND bit in the ATA PASS-THROUGH SCSI cdb. The default setting is clear (i.e. 0). When set the SATL should yield a sense buffer containing a ATA Result descriptor irrespective of whether the command succeeded or failed. When clear the SATL should only yield a sense buffer containing a ATA Result descriptor if the command failed.

-e, --extend

sets the EXTEND bit in the ATA PASS-THROUGH SCSI cdb. The default setting is clear (i.e. 0). When set a 48 bit LBA command is sent to the device. This option has no effect when --len=12.

-h, --help

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

-H, --hex

outputs the ATA IDENTIFY (PACKET) DEVICE response in hex. The default action (i.e. without any '-H' options) is to output the response in hex, grouped in 16 bit words (i.e. the ATA standard's preference). When given once, the response is output in ASCII hex bytes (i.e. the SCSI standard's preference). When given twice (i.e. '-HH') the output is in hex, grouped in 16 bit words, the same as the default but without a header. When given thrice (i.e. '-HHH') the output is in hex, grouped in 16 bit words, in a format that is acceptable for 'hdparm --Istdin' to process. '-HHHH' simply outputs hex data bytes, space separated, 16 per line.

-i, --ident

outputs the World Wide Name (WWN) of the device. This should be a NAA-5 64 bit number. It is output in hex prefixed with "0x". If not available then "0x0000000000000000" is output. The equivalent for a SCSI disk (i.e. its logical unit name) can be found with "sg_vpd -ii".

-l, --len=CLEN

CLEN this is the length of the SCSI cdb used for the ATA PASS-THROUGH command. CLEN can either be 12, 16 or 32. The default is 16. The larger cdb sizes are needed for 48 bit LBA addressing of ATA devices. The ATA Auxiliary and ICC registers are only conveyed with the 32 byte cdb variant.

-p, --packet

send an ATA IDENTIFY PACKET DEVICE command (via the SATL). The default action is to send an ATA IDENTIFY DEVICE command. Note that the ATAPI specification by T13 (i.e. the PACKET interface) is now obsolete.

-r, --raw

output the ATA IDENTIFY (PACKET) DEVICE response 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.

-R, --readonly

open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write.

-v, --verbose

increases the level or verbosity.

-V, --version

print out version string

## NOTES
Since the response to the IDENTIFY (PACKET) DEVICE command is very important for the correct use of an ATA(PI) device (and is typically the first command sent), a SATL should provide an ATA Information VPD page which contains the similar information.

The SCSI ATA PASS-THROUGH (12) command's opcode is 0xa1 and it clashes with the MMC set's BLANK command used by cd/dvd writers. So a SATL in front of an ATAPI device that uses MMC (i.e. has peripheral device type 5) probably should treat opcode 0xa1 as a BLANK command and send it through to the cd/dvd drive. The ATA PASS-THROUGH (16) command's opcode (0x85) does not clash with anything so it is a better choice.

Prior to Linux kernel 2.6.29 USB mass storage limited sense data to 18 bytes which made the --ck_cond option yield strange (truncated) results.

## EXAMPLES
These examples use Linux device names and a Linux utility called hdparm. For suitable device names in other supported Operating Systems see the sg3_utils(8) man page.

In this example /dev/sdb is a SATA 2.5" disk connected via a USB (type C connector) dongle that implements the UAS (USB attached SCSI) protocol (also known as UASP). UAS is a vast improvement over the USB mass storage class.

\# sg_sat_identify /dev/sdb

Response for IDENTIFY DEVICE ATA command:

00 0c5a 3fff c837 0010 0000 0000 003f 0000 .Z ?. .7 .. .. .. .? ..

....

The hexadecimal ASCII (with plain ASCII to the right) output is abridged to a single line (i.e. the first 16 bytes (or 8 words)). Now to decode some of that ATA Identify response. First sg_inq can decode a few strings:

\# sg_sat_identify -HHHH /dev/sdb | sg_inq --ata -I -

ATA device: model, serial number and firmware revision:

ST9500420AS 5VJCE6R7 0002SDM1

For a lot more details, the hdparm utility is a good choice:

\# sg_sat_identify -HHH /dev/sdb | hdparm --Istdin

ATA device, with non-removable media

Model Number: ST9500420AS

Serial Number: 5VJCE6R7

Firmware Revision: 0002SDM1

Transport: Serial

Standards:

....

There are about 80 more lines of details decoded by hdparm in this case. Notice the difference in the number of "H" options: three give an unadorned hex output arranged in (little endian) words (i.e. 16 bits each) while four "H" options give an unadorned hex output in bytes (i.e. 8 bits each).

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

## AUTHOR
Written by Douglas Gilbert

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

## COPYRIGHT
Copyright © 2006-2020 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(sg3_utils), sg_inq(sg3_utils), sdparm(sdparm), hdparm(hdparm)


title: sg_sat_phy_event(8)

summary: use ATA READ LOG EXT via a SAT pass\-through to fetch

text:
# sg_sat_phy_event(8)

## NAME
sg_sat_phy_event - use ATA READ LOG EXT via a SAT pass-through to fetch SATA phy event counters

## SYNOPSIS
sg_sat_phy_event [--ck_cond] [--extend] [--help] [--hex] [--ignore] [--len={16|12}] [--raw] [--reset] [--verbose] [--version] DEVICE

## DESCRIPTION
This utility sends an ATA READ LOG EXT with the log page ("address") set to 11h to DEVICE and outputs the response. Log page 11h is defined in the SATA 2.5 standard and contains phy event counters. Rather than send this command directly to the DEVICE, are sent via a SCSI transport which is assumed to contain a SCSI to ATA Translation (SAT) Layer (SATL). The SATL may be in an operating system driver, in host bus adapter firmware or in some external enclosure.

The SAT standard (SAT ANSI INCITS 431-2007, prior draft: sat-r09.pdf at www.t10.org) defines two SCSI "ATA PASS-THROUGH" commands: one using a 16 byte "cdb" and the other with a 12 byte cdb. This utility defaults to using the 16 byte cdb variant. SAT-2 is also a standard: SAT-2 ANSI INCITS 465-2010 and the draft prior to that is sat2r09.pdf . The SAT-3 project has started and the most recent draft is sat3r01.pdf .

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

-c, --ck_cond

sets the CK_COND bit in the ATA PASS-THROUGH SCSI cdb. The default setting is clear (i.e. 0). When set the SATL should yield a sense buffer containing a ATA Result descriptor irrespective of whether the command succeeded or failed. When clear the SATL should only yield a sense buffer containing a ATA Result descriptor if the command failed.

-e, --extend

sets the EXTEND bit in the ATA PASS-THROUGH SCSI cdb. The default setting is clear (i.e. 0). When set a 48 bit LBA command is sent to the device. This option has no effect when --len=12.

-h, --help

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

-H, --hex

outputs the ATA READ LOG EXT response in hex. The default action (i.e. without any '-H' options) is to output the response in hex, grouped in 16 bit words (i.e. the ATA standard's preference). When given once, the response is output in ASCII hex bytes (i.e. the SCSI standard's preference). When given twice (i.e. '-HH') the output is in hex, grouped in 16 bit words, the same as the default but without a header.

-i, --ignore

usually the phy counter identifier names are decoded. When this option is given, the numeric value of the identifier is output, the vendor flag, the data length (in bytes) and the corresponding value.

-l, --len={16|12}

this is the length of the SCSI cdb used for the ATA PASS-THROUGH commands. The argument can either be 16 or 12. The default is 16. The larger cdb size is needed for 48 bit LBA addressing of ATA devices. On the other hand some SCSI transports cannot convey SCSI commands longer than 12 bytes.

-r, --raw

output the ATA READ LOG EXT response 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.

-R, --reset

reset the counters after the current values are returned, decoded and displayed.

-v, --verbose

increases the level or verbosity.

-V, --version

print out version string

## NOTES
The SCSI ATA PASS-THROUGH (12) command's opcode is 0xa1 and it clashes with the MMC set's BLANK command used by cd/dvd writers. So a SATL in front of an ATAPI device that uses MMC (i.e. has peripheral device type 5) probably should treat opcode 0xa1 as a BLANK command and send it through to the cd/dvd drive. The ATA PASS-THROUGH (16) command's opcode (0x85) does not clash with anything so it is a better choice.

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. disks and ATAPI DVDs) can also be specified. For example "sg_inq /dev/sda" will work in the 2.6 series kernels. From lk 2.6.6 other SCSI "char" device names may be used as well (e.g. "/dev/st0m"). Prior to lk 2.6.29 USB mass storage limited sense data to 18 bytes which made the --ck_cond option yield strange (truncated) results.

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

## AUTHOR
Written by Douglas Gilbert

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

## COPYRIGHT
Copyright © 2006-2020 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_sat_identify,sg_sat_read_gplog(sg3_utils), smp_rep_phy_err_log(smp_utils),sdparm(sdparm),hdparm(hdparm)