title: sg_modes(8)

text:
# sg_modes(8)

## NAME
sg_modes - reads mode pages with SCSI MODE SENSE command

## SYNOPSIS
sg_modes [--all] [--ALL] [--control=PC] [--dbd] [--dbout] [--examine] [--flexible] [--help] [--hex] [--list] [--llbaa] [--maxlen=LEN] [--multiple] [--page=PG[,SPG]] [--raw] [-R] [--readwrite] [--six] [--verbose] [--version] [DEVICE]

sg_modes [-6] [-a] [-A] [-c=PC] [-d] [-D] [-e] [-f] [-h] [-H] [-l] [-L] [-m=LEN] [-M] [-p=PG[,SPG]] [-r] [-subp=SPG] [-v] [-V] [-w] [-?] [DEVICE]

## DESCRIPTION
This utility sends a MODE SENSE SCSI command to the DEVICE and outputs the response. There is a 6 byte and 10 byte (cdb) variant of the MODE SENSE command, this utility defaults to the 10 byte variant. The SPC-4 standard (and the SPC-5 standard) stated that implementers should migrate away from the SCSI MODE SELECT(6) and MODE SENSE(6) commands in favour of the 10 byte variants (e.g. MODE SENSE(10)). In draft SPC-6 revision 7 the SCSI MODE SELECT(6) and MODE SENSE(6) commands have been removed.

This utility decodes mode page headers and block descriptors but outputs the contents of each mode page in hex. It also has no facility to change the mode page contents or block descriptor data. Mode page contents are decoded and can be changed with the sdparm utility.

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.

If no page is given (and --list is not selected) then --all is assumed. The --all option requests all mode pages (but not subpages) in a single response.

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

-a, --all

output all the mode pages reported by the DEVICE. This is what the page code 63 (0x3f) is defined to do. When used once, mode subpages are not fetched. When used twice (e.g. '-aa'), all mode pages and subpages are requested which is equivalent to '--page=63,255'.

-A, --ALL

same meaning as using the --all option twice. That is, all mode pages and subpages are fetched. The default is to fetch all the mode pages but not mode subpages.

-c, --control=PC

PC is the page control value. Up to four different versions of each page are held by the device:

0 : current values (i.e. those active at present)

1 : changeable values

2 : default values (i.e. the manufacturer's settings)

3 : saved values

The changeable values are bit masks showing which fields could be changed with a MODE SELECT. The saved values will be re-instated the next time the device is power cycled or reset. If this option is not given then current values [0] are assumed.

-d, --dbd

disable block descriptors. By default, block descriptors (usually one (for disks) or none) are returned in a MODE SENSE response. This option sets the "disable block descriptors" (DBD) bit in the cdb which instructs the device not to return any block descriptors in its response. Older devices may not support this setting and may return an "illegal request" sense key; alternatively they may ignore it. Oddly the Reduced Block Command set (RBC) requires this bit set.

-D, --dbout

disable outputting block descriptors. Irrespective of whether block descriptors are present in the response or not, they are not output.

-e, --examine

if the --page=PG[,SPG] option is not given, examine each mode page in the range 0 through to 62 (inclusive). If the --page=PG[,SPG] option is give, then all subpages whose page code is PN are examined (subpages 0 through 254 (inclusive)). If some response is given then print out the mode (sub)page name or number (in hex) if the name is not known.

The sdparm utility which lists mode and VPD pages also has a --examine option will similar functionility.

-f, --flexible

Some devices, bridges and/or drivers attempt crude translations between MODE SENSE 6 and 10 byte commands without correcting the response. This will cause the response to be mis-interpreted (usually with an error saying the response is malformed). With this option, the length of the response is checked, and if it looks wrong, the response is then decoded as if the other mode sense (cdb length) was sent.

-h, --help

print out the usage message then exit.

-H, --hex

Since this utility shows the structure of a MODE SENSE command response (i.e. its parameter header, zero or more block descriptors followed by zero or more mode pages) but outputs most of the contents of the response in hexadecimal. When this option is used once, the only difference is that the mode page name, if known, is followed by it page number (and subpage number) bracketed in hex.

When this option is given twice, then each line of hex output has an ASCII rendering of that hex place at the end of each line. When this option is given three times, then the hexadimal address, shown at the start of each hexadecimal line is dropped, there is no ASCII rendering of hex, and all test lines are removed. This leaves simple hex that is parsable that represents the MODE SENSE command response. The component parts of that response are put on separate line.

When the option is given four or more times (recommended for a parsable form), the ASCII informational lines are back, but they all start with "#" which a parser needs to ignore. The output is sent to stdout while any error messages or warning are sent to stderr. So simple Unix command line redirection of stdout to a file (done with '>' in most Unix shells) should be sufficient to capture the output. As noted above, the sdparm utility can be used to decode that hex file later with its '--inhex=FN' option.

-l, --list

lists all common page and subpage codes and their names that are found in the command set that matches the peripheral type of the given DEVICE. If no DEVICE and no --page=PG is given then the common page and subpage codes and their names are listed for SBC (e.g. a disk). If no DEVICE is given and a --page=PG is given then the common page and subpage codes and their names are listed for the command set whose peripheral device type matches the value given to PG. For example 'sg_mode --list --page=1' lists the command mode pages and subpages for tape devices. Additionally if a sub_page_code is given then it is interpreted as a transport identifier and command transport specific mode page codes and their names are listed following the main mode page list. Other options are ignored.

-L, --llbaa

set the Long LBA Accepted (LLBAA) bit in the MODE SENSE (10) cdb. This bit is not defined in the MODE SENSE (6) cdb so setting the '-L' and '--six' options is reported as an error. When set the DEVICE may respond with 16 byte block descriptors as indicated by the 'LongLBA' field in the response. In most cases setting this option is not needed.

-m, --maxlen=LEN

The LEN argument is the maximum response length in bytes. It is the 'allocation length' field in the cdb. When not given (or LEN is zero) then the allocation length field is set to 4096 for MODE SENSE (10) or 252 for MODE SENSE (6). The LEN argument must be non-negative and no greater than 65535 for MODE SENSE (10) and not greater than 255 for MODE SENSE (6).

-M, --multiple

for each mode page (and mode subpage), fetch all available page controls. There may be up to four page controls as outlined in the --control=PC option. The mode parameter header, and block descriptors are output that same way as without this option. After the mode page name (and numbers) are output, there is a line with either current, changeable, default or saved page control on it followed by that page control in hex.

If the --control=PC option is given, it is overridden by this option.

-O, --old

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

-p, --page=PG

page code to fetch. The PG is assumed to be a decimal value unless prefixed by '0x' or has a trailing 'h'. It should be a value between 0 and 63 (inclusive). When not given and a default is required then a value of 63 (0x3f), which fetches all mode pages, is used.

Alternatively an acronym for the mode page can be given. The available acronyms can be listed out with the --page=xxx option. They are almost the same as the acronyms used for mode pages in the sdparm utility.

-p, --page=PG,SPG

page code and subpage code values to fetch. Both arguments are assumed to be decimal unless flagged as hexadecimal. The page code should be between 0 and 63 inclusive. The subpage code should be between 0 and 255 inclusive. The default value for the subpage code is 0.

-r, --raw

output the response in binary to stdout. Error messages and warnings, if any, are sent to stderr. When this option is used twice (e.g. '-rr') then has the same action as '-R'

-R

output the selected mode page to stdout a byte per line. Each line contains two hexadecimal digits (e.g. "3e"). Useful as input (after editing) to the sg_wr_mode(8) utility.

-w, --readwrite

open DEVICE in "read-write" mode. Default is to open it in read-only mode.

-6, -s, --six

by default this utility sends a 10 byte MODE SENSE command to the DEVICE. However some SCSI devices only support 6 byte MODE SENSE commands (e.g. SCSI-2 tape drives). This parameter forces the use of 6 byte MODE SENSE commands.

-v, --verbose

increase level of verbosity. Can be used multiple times.

-V, --version

print out version string then exit.

## NOTES
If the normal sg_modes utility fails with "illegal command operation code" then try the '--six' (or '-6') option.

This utility performs a SCSI INQUIRY command to determine the peripheral type of the device (e.g. 0 -> Direct Access Device (disk)) prior to sending a MODE SENSE command. This helps in decoding the block descriptor and mode pages.

This utility opens DEVICE in read-only mode (e.g. in Unix, with the O_RDONLY flag) by default. It will open DEVICE in read-write mode if the --readwrite option is given.

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

There is no JSON output from this utility because its primary output is mode pages in hexadecimal. So apart from the mode page name and its structure, nothing is decoded. The sdparm utility does decode mode page contents and it does support JSON output.

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

-6

by default this utility sends a 10 byte MODE SENSE command to the DEVICE. This parameter forces the use of 6 byte MODE SENSE commands. See --six in the main description.

-a

see --all in the main description.

-A

output all the mode pages and subpages supported by the DEVICE. Same as '--all --all' in the new syntax.

-c=PC

PC is the page control value. See --control=PC in the main description.

-d

see --dbd in the main description.

-D

see --dbout in the main description.

-e

see --examine in the main description.

-f

see --flexible in the main description.

-h

The default action is to decode known mode page numbers (and subpage numbers) into text. With this option mode page numbers (and subpage numbers) are output in hexadecimal.

-H

same action as the '-h' option.

-l

see --list in the main description.

-L

see --llbaa in the main description.

-N, --new

Switch to the newer style options.

-m=LEN

see --maxlen=LEN in the main description.

-M

see --multiple in the main description.

-p=PG

PG is page code to fetch. Should be a hexadecimal number between 0 and 3f inclusive (0 to 63 decimal). The default value when required is 3f (fetch all mode pages). Note that an acronym for the page and/or subpage values is not accepted in this older format (because any acronym starting with the letters 'a' to 'f' is ambiguous; it could either be a hex number or an acronym).

-p=PG,SPG

page code and subpage code values to fetch. The page code should be a hexadecimal number between 0 and 3f inclusive. The subpage code should be a hexadecimal number between 0 and ff inclusive. The default value for the subpage code is 0.

-r

output the selected mode page to stdout a byte per line. Each line contains two hexadecimal digits (e.g. "3e"). Useful as input (after editing) to the sg_wr_mode(8) utility.

-subp=SPG

sub page code to fetch. Should be a hexadecimal number between 0 and 0xff inclusive. The default value is 0.

-v

increase verbosity of output.

-V

print out version string then exit.

-w

see --readwrite in the main description.

-?

output usage message then exit. Ignore all other parameters.

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

## EXAMPLES
All mode pages, but not mode subpages, can be dumped in hex to a file like this:

\# sg_modes -a -HHHH /dev/sdb > modes_sdeb.hex

If there are any errors then they are sent to stderr so they will appear on the console and not within the modes_sdeb.hex file. Nonetheless the contents of modes_sdeb.hex may not be useful if an error has occurred.

The '-HHHH' option produces hex output with comment lines starting with a '#' character. Each comment describes the following block. If all is well, the modes_sdeb.hex file will be suitable for the sdparm utility to decode:

\# sdparm -a --inhex=modes_sdeb.hex

See the sdparm(8) manpage for further information.

To dump both mode pages and subpages, use this invocation:

\# sg_modes -aa -HHHH /dev/sdb > modes_sdeb.hex

No change is needed in the associated sdparm call. There is some example output in the inhex directory in the sg3_utils package, in a file called: modes_sdeb.hex . The file was produced by using this utility on the scsi_debug driver in Linux.

Each mode page (and subpage) has up to four 'page controls': current, changeable, default and saved. The last three may or may not be supported by the device. All available page controls for all mode pages and subpages can be placed in a hex file with this invocation:

\# sg_modes -aa -M -HHHH /dev/sdb > modes_mm_sdeb.hex

Again, no change is needed in the associated sdparm call. There is some example output in the inhex directory in the sg3_utils package, in a file called: modes_mm_sdeb.hex .

## AUTHOR
Written by Douglas Gilbert

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

## COPYRIGHT
Copyright © 2000-2023 Douglas Gilbert

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

## SEE ALSO
sdparm(8), sg_wr_mode(8), sginfo(8), sgmode(scsirastools), scsiinfo(net), scu(net), seatools(seagate)

All these utilities offer some facility to change mode page (or block descriptor) parameters.


title: sg_opcodes(8)

text:
# sg_opcodes(8)

## NAME
sg_opcodes - report supported SCSI commands or task management functions

## SYNOPSIS
sg_opcodes [--alpha] [--compact] [--enumerate] [--help] [--hex] [--inhex=FN] [--json[=JO]] [--js-file=JFN] [--mask] [--mlu] [--no-inquiry] [--opcode=OP[,SA]] [--pdt=DT] [--raw] [--rctd] [--repd] [--sa=SA] [--tmf] [--unsorted] [--verbose] [--version] DEVICE

sg_opcodes [-a] [-c] [-e] [-H] [-i=FN] [-j] [-m] [-M] [-n] [-o=OP] [-p=DT] [-q] [-R] [-s=SA] [-t] [-u] [-v] [-V] [-?] DEVICE

## DESCRIPTION
This utility sends a SCSI REPORT SUPPORTED OPERATION CODES or a REPORT SUPPORTED TASK MANAGEMENT FUNCTIONS command to the DEVICE and then outputs the response. The default action is to report supported operation codes. In this mode it will either list all supported commands or give detailed information on a specific command identified by the --opcode=OP option (perhaps with additional information from the --sa=SA option).

The name of a SCSI command depends on its peripheral device type (e.g. a disk). The REPORT SUPPORTED OPERATION CODES and REPORT SUPPORTED TASK MANAGEMENT FUNCTIONS commands are not supported in the MMC command set for CD and DVD devices. This utility does an INQUIRY to obtain the peripheral device type and prints out the vendor, product and revision strings.

A similar facility to query supported operation codes previously was available via the CmdDt bit in the SCSI INQUIRY command (see sg_inq(8)). However that facility was made obsolete and replaced by the REPORT SUPPORTED OPERATION CODES command in SPC-3 (revision 4) during February 2002.

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

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

-a, --alpha

when all supported commands are being listed there is no requirement for the device server (i.e. the DEVICE) to sort the list of commands. When this option is given the list of supported commands is sorted by name (alphabetically). When this option and the --unsorted option are both _not_ given then the list of supported commands is sorted numerically (first by operation code and then by service action).

-c, --compact

some command names, especially those associated with some service actions, are getting longer. This may cause line wrap in the one line per command mode on some terminals. When this option is given the opcode and service action fields are combined into a single field with the service action, prefixed by a comma shown directly after the opcode. If there is no service action associated with the command, then the comma and the service action are not shown after the opcode. The CDB size field is not shown when this option is given.

-e, --enumerate

this option prints the name of the SCSI command based on the given opcode, peripheral device type and optionally the service action. If given, DEVICE is ignored. The opcode, peripheral device type and service action default to zero if not given. Thus if this option is the only option given then "Test Unit ready" is output since its opcode is 0, it has no service action and it is common to all peripheral device types since it is defined in the SCSI Primary Commands (SPC) standard(s).

-h, --help

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

-H, --hex

outputs the response in ASCII hexadecimal to stdout. When used once or twice, each line starts with a relative (hex) address starting at 0 on the first hex line output. The difference is when used twice the hexadecimal bytes are rendered in ASCII at the right of each line; non-printable characters are replaced by "." .

When used three or more times, there is no leading relative address on each line. This output is suitable for being redirected to a file which can later by given to 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.

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

-m, --mask

additionally prints out the cdb mask in hex. So a 12 byte cdb will have a 12 byte hexadecimal mask. If the hexadecimal is expanded (mentally) to binary then a "1" means the corresponding position in the cdb may be set. And "0" means the corresponding position in the cdb must not be set. For "0" mask positions that a user tries to set in a cdb, the device may either ignore it or report an error, typically with a sense key of "illegal request".

-M, --mlu

additionally prints out an indication (0 or 1) whether the command effects all logical units in the containing target. MLU (Multiple Logical Units) is a bit in the REPORT SUPPORTED OPERATION CODES response introduced by proposal 18-045r1 (and possibly in spc5r20). Without the option, the default output format which lists all opcodes, does not include a MLU indication.

-n, --no-inquiry

Prior to calling a SCSI REPORT SUPPORTED OPERATION CODES or a REPORT SUPPORTED TASK MANAGEMENT FUNCTIONS command, a SCSI INQUIRY command is performed. The reason is to determine the peripheral device type (pdt) of the DEVICE as this is helpful in translating operation codes to the command names. By default this utility prints a summary of INQUIRY command response on stdout. If this option (or the --raw option) is given then that summary is not printed on stdout.

-O, --old

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

-o, --opcode=OP[,SA]

the DEVICE will be queried for the given operation code (i.e. the OP value) which is the first byte of a SCSI command. Optionally, if a SA value is given, it will be used as that SCSI command's service action. Note that OP and OP,0 are not the same thing, as SCSI does allow the service action to be 0 (but not in this command). OP and SA are decimal unless prefixed by "0x" or they have a trailing "h". OP should be in the range 0 to 255 (0xff) inclusive. SA should be in the range 0 to 65535 (0xffff) inclusive. When this option is not given then all available SCSI commands supported by the DEVICE are listed.

-p, --pdt=DT

where DT is the peripheral device type. This is used together with the --enumerate to differentiate when a command opcode (and perhaps service action) is shared by multiple device types.

Numerical values between -1 and 31 (inclusive) may be used where -1 implies what is in SPC. Names like 'tape', 'disk' and 'processor' may also be given.

This option may also be used with the --no-inquiry option to suppress this utility doing an INQUIRY command since the main reason for doing that is to find the peripheral device type of the DEVICE.

-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, --rctd

set report command timeout descriptor (RCTD) bit in the cdb. The response may or may not contain command timeout descriptors. If available they are output. If supported there are two values: a nominal command timeout and a recommended command timeout. Both have units of seconds. A value of zero means that no timeout is indicated and this is shown in the corresponding decoded output as "-".

-q, --repd

set read extended parameter data (REPD) bit in the report task management functions cdb. 16 bytes rather than the default 4 bytes expected in the response. This was added in SPC-4 (revision 26).

-s, --sa=SA

the DEVICE will be queried for a command with the given service action (i.e. the SA value). Used in conjunction with the --opcode=OP option. If this option is not given, --opcode=OP is given and the command in question does have a service action then a value of 0 will be assumed. SA is decimal and expected to be in the range 0 to 65535 (0xffff) inclusive.

-t, --tmf

list supported task management functions. This is done with the SCSI REPORT SUPPORTED TASK MANAGEMENT FUNCTIONS command. When this option is chosen the --alpha, --opcode=OP, --rctd, --sa=SA and --unsorted options are ignored.

-u, --unsorted

when all supported commands are being listed there is no requirement for the device server (i.e. the DEVICE) to sort the list of commands. When this option is given the list of supported commands is in the order given by the DEVICE. When this option is not given the supported commands are sorted numerically (first by operation code and then by service action).

-v, --verbose

increase level of verbosity. Can be used multiple times.

-V, --version

print out version string then exit.

## NOTES
As of SPC-5 revision 8 the recognized task management functions are: abort set, abort task set, clear ACA, clear task set, logical unit reset, query task, query asynchronous event, query task set, and I_T nexus reset. In SPC-4 revision 26 target reset and wakeup task management functions were made obsolete.

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

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

-a

sort command alphabetically. Equivalent to --alpha in main description.

-c

see the --compact option above.

-e

see the --enumerate option above.

-H

see the --hex option above.

-m

see the --mask option above.

-n

don't print a summary of the SCSI INQUIRY response on stdout.

-N, --new

Switch to the newer style options.

-o=OP

the DEVICE will be queried for the given operation code (i.e. OP) which is the first byte of a SCSI command. OP is hexadecimal and expected to be in the range 0 to ff inclusive. When this option is not given then all available SCSI commands supported by the DEVICE are listed.

-p=DT

see the --pdt=DT option above.

-q

set the read extended parameter data (REPD) bit in report TMF cdb. Equivalent to --repd in main description.

-R

set the report command timeout descriptor (RCTD) bit in cdb. Equivalent to --rctd in main description.

-s=SA

the DEVICE will be queried for a command with the given service action (i.e. SA). Used in conjunction with the -o=OP option. If this option is not given, -o=OP is given and the command in question does have a service action then a value of 0 will be assumed. SA is hexadecimal and expected to be in the range 0 to ffff inclusive.

-t

list supported task management functions. Equivalent to --tmf in the main description.

-u

output all supported commands in the order given by DEVICE. Equivalent to --unsorted in main description.

-v

increase level of verbosity. Can be used multiple times.

-V

print out version string then exit.

-?

output usage message. Ignore all other parameters.

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

To see the information about a specific command give its operation code to the '--op=' option. A command line invocation is shown first followed by a typical response:

\# sg_opcodes --op=93h /dev/sdb

Opcode=0x93

Command_name: Write same(16)

Command supported [conforming to SCSI standard]

Usage data: 93 e2 00 00 00 00 ff ff ff ff 00 00 ff ff 00 00

The next example shows the supported task management functions:

\# sg_opcodes --tmf -n /dev/sdb

Task Management Functions supported by device:

Abort task

Abort task set

Clear ACA

Clear task set

Logical unit reset

Query task

Enumerate can be used to look up a SCSI command name in the absence of a device that supports that command. The opcode and service action (if required) should be supplied:

\# sg_opcodes --enumerate --op=0x9b,0xa

SCSI command:

Read buffer(16), read data from echo buffer

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

## AUTHOR
Written by Douglas Gilbert

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

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


title: sg_persist(8)

text:
# sg_persist(8)

## NAME
sg_persist - use SCSI PERSISTENT RESERVE command to access registrations and reservations

## SYNOPSIS
sg_persist [OPTIONS] DEVICE

sg_persist [OPTIONS] --device=DEVICE

sg_persist --help | --version

## DESCRIPTION
This utility allows Persistent reservations and registrations to be queried and changed. Persistent reservations and registrations are queried by sub-commands (called "service actions" in SPC-4) of the SCSI PERSISTENT RESERVE IN (PRIN) command. Persistent reservations and registrations are changed by sub-commands of the SCSI PERSISTENT RESERVE OUT (PROUT) command.

There is a two stage process to obtain a persistent reservation. First an application (an I_T nexus in the standard's jargon) must register a reservation key. If that is accepted (and it should be unless some other I_T nexus has registered that key) then the application can try and reserve the device. The reserve operation must specify the reservation key and a "type" (see the --prout-type=TYPE option).

It is relatively safe to query the state of Persistent reservations and registrations. With no options this utility defaults to the READ KEYS sub-command of the PRIN command. Other PRIN sub-commands are READ RESERVATION, REPORT CAPABILITIES and READ FULL STATUS.

Before trying to change Persistent reservations and registrations users should be aware of what they are doing. The relevant sections of the SCSI Primary Commands document (i.e. SPC-5 ANSI INCITS 502-2020) are sections 8.14 (titled "Reservations"), 9.16 (for the PRIN command) and 9.17 (for the PROUT command). To safeguard against accidental use, the --out option must be given when a PROUT sub-command (e.g. --register) is used.

The older SCSI RESERVE and RELEASE commands (both 6 and 10 byte variants) are not supported by this utility. In SPC-3, RESERVE and RELEASE are deprecated, replaced by Persistent Reservations. RESERVE and RELEASE have been removed from SPC-4 and Annex B is provided showing how to convert to persistent reservation commands. See a utility called 'scsires' for support of the SCSI RESERVE and RELEASE commands.

DEVICE needs to be specified for all variants of this utility apart from --help and --version. The DEVICE can be given either as an argument (typically but not necessarily following the options) or via the --device=DEVICE option.

SPC-4 does not use the term "sub-command". It uses the term "service action" for this and for part of a field's name in the parameter block associated with the PROUT command (i.e. "service action reservation key"). To lessen the potential confusion the term "sub-command" has been introduced.

## OPTIONS
Arguments to long options are mandatory for short options as well. The following options are sorted in alphabetical order, based on their long option name.

-l, --alloc-length=LEN

specify the allocation length of the PRIN command. LEN is a hex value. By default this value is set to the size of the data-in buffer (8192). This parameter is of use for verification that response to PRIN commands with various allocation lengths is per section 4.3.5.6 of SPC-4 revision 18. Valid LEN values are 0-8192.

-C, --clear

Clear is a sub-command of the PROUT command. It releases the persistent reservation (if any) and clears all registrations from the device. It is required to supply a reservation key that is registered for this I_T_L nexus (identified by --param-rk=RK).

This option issues the PERSISTENT RESERVE OUT SCSI command with its service action field set to CLEAR [0x3].

-d, --device=DEVICE

DEVICE to send SCSI commands to. The DEVICE can either be provided via this option or via a freestanding argument. For example, these two: 'sg_persist --device=/dev/sg2' and 'sg_persist /dev/sg2' are equivalent.

-h, --help

output a usage message showing main options. Use twice (e.g. '-hh') for the other option and more help.

-H, --hex

the response to a valid PRIN sub-command will be output in hexadecimal. By default (i.e. without this option) if the PRIN sub-command is recognised then the response will be decoded as per SPC-4. May be used more than once for more hex and less text.

-i, --in

specify that a SCSI PERSISTENT RESERVE IN command is required. This is the default.

-m, --maxlen=LEN

LEN is used as the ALLOCATION LENGTH field of the PRIN command. LEN is by default a decimal value. To give a hex value use a '0x' or '0X' prefix, or use a 'h' (or 'H') suffix. Can also take multipliers, see --maxlen=LEN option in the sg3_utils manual page.

This option is the same as --alloc-length=LEN option apart from the representation of LEN. The option defaults to decimal while --alloc-length=LEN only takes hex.

-n, --no-inquiry

the default action is to do a standard SCSI INQUIRY command and output make, product and revision strings plus the peripheral device type prior to executing a PRIN or PROUT command. With this option the INQUIRY command is skipped.

-o, --out

specify that a SCSI PERSISTENT RESERVE OUT command is required.

-Y, --param-alltgpt

set the 'all target ports' (ALL_TG_PT) flag in the parameter block of the PROUT command. Only relevant for 'register' and 'register and ignore existing key' sub-commands.

-Z, --param-aptpl

set the 'activate persist through power loss' (APTPL) flag in the parameter block of the PROUT command. Relevant for 'register', 'register and ignore existing key' and 'register and move' sub-commands.

-K, --param-rk=RK

specify the reservation key found in the parameter block of the PROUT command. RK is assumed to be hex (up to 8 bytes long). Default value is 0. This option is needed by most PROUT sub-commands.

-S, --param-sark=SARK

specify the service action reservation key found in the parameter block of the PROUT command. SARK is assumed to be hex (up to 8 bytes long). Default value is 0. This option is needed by some PROUT sub-commands.

-P, --preempt

Preempt is a sub-command of the PROUT command. Preempts the existing persistent reservation (identified by --param-sark=SARK) with the registration key that is registered for this I_T_L nexus (identified by --param-rk=RK). If a new reservation is established as a result of the preemption then the supplied --prout-type=TYPE is used as the type for this new reservation.

This option issues the PERSISTENT RESERVE OUT SCSI command with its service action field set to PREEMPT [0x4].

-A, --preempt-abort

Preempt and Abort is a sub-command of the PROUT command. Preempts the existing persistent reservation (identified by --param-sark=SARK) with the registration key that is registered for this I_T_L nexus (identified by --param-rk=RK). If a new reservation is established as a result of the preemption then the supplied --prout-type=TYPE is used as the type for this new reservation. ACA and other pending tasks are aborted.

This option issues the PERSISTENT RESERVE OUT SCSI command with its service action field set to PREEMPT AND ABORT [0x5].

-T, --prout-type=TYPE

specify the PROUT command's 'type' argument. Required by the 'register-move', 'reserve', 'release' and 'preempt (and abort)' sub-commands. Valid TYPE values: 1-> write exclusive, 3-> exclusive access, 5-> write exclusive - registrants only, 6-> exclusive access - registrants only, 7-> write exclusive - all registrants, 8-> exclusive access - all registrants. Default value is 0 (which is an invalid type). Each "persistent reservation type" is explained in more detail in a subsection of that name in the read reservation section of the PRIN command (section 6.15.3.3 of SPC-4 revision 37).

-s, --read-full-status

Read Full Status is a sub-command of the PRIN command. For each registration with the given SCSI device, it lists the reservation key and associated information. TransportIDs, if supplied in the response, are decoded.

This option issues the PERSISTENT RESERVE IN SCSI command with its service action field set to READ FULL STATUS [0x3].

-k, --read-keys

Read Keys is a sub-command of the PRIN command. Lists all the reservation keys registered (i.e. registrations) with the given SCSI device. This is the default sub-command for the SCSI PRIN command.

This option issues the PERSISTENT RESERVE IN SCSI command with its service action field set to READ KEYS [0x0].

-y, --readonly

Open DEVICE read-only. May be useful with PRIN commands if there are unwanted side effects with the default read-write open. When given twice is interpreted as forcing a read-write open thus overriding the SG_PERSIST_IN_RDONLY environment variable if present. See the ENVIRONMENT VARIABLES section for more.

-r, --read-reservation

Read Reservation is a sub-command of the PRIN command. List information about the current holder of the reservation on the DEVICE. If there is no current reservation this will be noted. Information about the current holder of the reservation includes its reservation key, scope and type.

This option issues the PERSISTENT RESERVE IN SCSI command with its service action field set to READ RESERVATION [0x1].

-s, --read-status

same as --read-full-status.

-G, --register

Register is a sub-command of the PROUT command. It has 3 different actions depending on associated parameters. a) add a new registration with '--param-rk=0' and '--param-sark=<new_rk>'; b) Change an existing registration with '--param-rk=<old_rk>' and '--param-sark=<new_rk>'; or c) Delete an existing registration with '--param-rk=<old_rk>' and '--param-sark=0'.

This option issues the PERSISTENT RESERVE OUT SCSI command with its service action field set to REGISTER [0x0].

-I, --register-ignore

Register and Ignore Existing Key is a sub-command of the PROUT command. Similar to --register except that when changing a reservation key the old key is not specified. The '--param-sark=<new_rk>' option should also be given.

This option issues the PERSISTENT RESERVE OUT SCSI command with its service action field set to REGISTER AND IGNORE EXISTING KEY [0x6].

-M, --register-move

register (another initiator) and move (the reservation held by the current initiator to that other initiator) is a sub-command of the PROUT command. It requires the transportID of the other initiator. [The standard uses the term I_T nexus but the point to stress is that there are two initiators (the one sending this command and another one) but only one logical unit.] The --prout-type=TYPE and --param-rk=RK options need to match that of the existing reservation while --param-sark=SARK option specifies the reservation key of the new (i.e. destination) registration.

This option issues the PERSISTENT RESERVE OUT SCSI command with its service action field set to REGISTER AND MOVE [0x7].

-Q, --relative-target-port=RTPI

relative target port identifier that reservation is to be moved to by PROUT 'register and move' sub-command. RTPI is assumed to be hex in the range 0 to ffff inclusive. Defaults to 0 .

-L, --release

Release is a sub-command of the PROUT command. It releases the current persistent reservation. The --prout-type=TYPE and --param-rk=RK options, matching the reservation, must also be specified.

This option issues the PERSISTENT RESERVE OUT SCSI command with its service action field set to RELEASE [0x2].

-z, --replace-lost

Replace Lost Reservation is a sub-command of the PROUT command. It "begins a recovery process for the lost persistent reservation that is managed by application clients". It also stops the device server terminating commands due to a lost persistent reservation. Options should be '--param-rk=0' (or not given), '--param-sark=<new_rk>' and --prout-type=TYPE.

This option issues the PERSISTENT RESERVE OUT SCSI command with its service action field set to REPLACE LOST RESERVATION [0x8].

-c, --report-capabilities

Report Capabilities is a sub-command of the PRIN command. It lists information about the aspects of persistent reservations that the DEVICE supports.

This option issues the PERSISTENT RESERVE IN SCSI command with its service action field set to REPORT CAPABILITIES [0x2].

-R, --reserve

Reserve is a sub-command of the PROUT command. It creates a new persistent reservation (if permitted). The --prout-type=TYPE and --param-rk=RK options must also be specified.

This option issues the PERSISTENT RESERVE OUT SCSI command with its service action field set to RESERVE [0x1].

-X, --transport-id=TIDS

The TIDS argument can take one of several forms. It can be a comma (or a single space) separated list of ASCII hex bytes representing a single TransportID as defined in SPC-5. They are usually 24 bytes long apart from in iSCSI. The TIDS argument may be a transport specific form ( e.g. "sas,5000c50005b32001" is clearer than an equivalent to the hex byte form: "6,0,0,0,5,0,c5,0,5,b3,20,1"). The TIDS argument may be "-" in which case one or more TransportIDs can be read from stdin. The TIDS argument may be of the form "file=<name>" in which case one or more TransportIDs can be read from a file called <name>. See the "TRANSPORT IDs" section below for more information.

-U, --unreg

optional when the PROUT register and move sub-command is invoked. If given it will unregister the current initiator (I_T nexus) after the other initiator has been registered and the reservation moved to it. When not given the initiator (I_T nexus) that sent the PROUT command remains registered.

This option issues the PERSISTENT RESERVE OUT SCSI command with its service action field set to REGISTER AND MOVE [0x7]. The UNREG bit is set in the associated parameter list.

-v, --verbose

print out cdb of issued commands prior to execution. If used twice prints out the parameter block associated with the PROUT command prior to its execution as well. If used thrice decodes given transportID(s) as well. To see the response to a PRIN command in low level form use the --hex option.

-V, --version

print out version string. Ignore all other parameters.

-?

output usage message. Ignore all other parameters.

## TRANSPORT IDs
TransportIDs are used in persistent reservations to identify initiators. The format of a TransportID differs depending on the type of transport being used. Their format is described in SPC-4 (in draft revision 37 see section 7.6.4).

A TransportID is required for the PROUT 'register and move' sub-command and the PROUT 'register' sub-command can have zero, one or more TransportIDs.

When the --transport-id=TIDS option is given then the TIDS argument may be a comma (or single space) separated list of ASCII hex bytes that represent a single TransportID as defined in SPC-4. Alternatively the TIDS argument may be a transport specific string starting with either "fcp,", "spi,", "sbp,", "srp,", "iqn", "sas," or "sop,". The "iqn" form is an iSCSI qualified name. Apart from "iqn" the other transport specific leadin string may be given in upper case (e.g. "FCP,").

The "fcp," form should be followed by 16 ASCII hex digits that represent an initiator's N_PORT_NAME (e.g. "fcp,10000000C9F3A571"). The "spi," form should be followed by "<scsi_address>,<relative_target_port_identifier>" (both decimal numbers). The "sbp," form should be followed by 16 ASCII hex digits that represent an initiator's EUI-64 name. The "srp," form should be followed by 32 ASCII hex digits that represent an initiator port identifier. The "sas," form should be followed by 16 ASCII hex digits that represent an initiator's port SAS address (e.g. "sas,5000c50005b32001"). The "sop," form takes a hex number that represents a routing id.

There are two iSCSI qualified name forms. The shorter form contains the iSCSI name of the initiator port (e.g. "iqn.5886.com.acme.diskarrays-sn-a8675309"). The longer form adds the initiator session id (ISID in hex) separated by ",i,0x". For example "iqn.5886.com.acme.diskarrays-sn-a8675309,i,0x1234567890ab". On the command line to stop punctuation in an iSCSI name being (mis)-interpreted by the shell, putting the option argument containing the iSCSI name in double quotes is advised. iSCSI names are encoded in UTF-8 so if non (7 bit) ASCII characters appear in the iSCSI name on the command line, there will be difficulties if they are not encoded in UTF-8. The locale can be changed temporarily by prefixing the command line invocation of sg_persist with "LANG=en_US.utf-8" for example.

Alternatively the TIDS argument may specify a file (or pipe) from which one or more TransportIDs may be read. If the TIDS argument is "-" then stdin (standard input) is read. If the TIDS argument is of the form "file=<name>" then a file called <name> is read. A valid SPC-4 TransportID is built from the transport specific string outlined in the previous paragraphs. The parsing of the data read is relatively simple. Empty lines are ignored. Everything from and including a "#" on a line is ignored. Leading spaces and tabs are ignored. There can be one transportID per line. The transportID can either be a comma, space or tab separated list of ASCII hex bytes that represent a TransportID as defined in SPC-4. Padding with zero bytes to a minimum length of 24 bytes is performed if necessary. The transportID may also be transport specific string type discussed above.

In SPC-3 the SPEC_I_PT bit set to one and TransportIDs were allowed for the PROUT register and ignore existing key sub-command. In SPC-4 that is disallowed yielding a CHECK CONDITION status with and ILLEGAL REQUEST sense key and an additional sense code set to INVALID FIELD IN PARAMETER LIST.

## NOTES
In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series any SCSI device name (e.g. /dev/sdc, /dev/st1m or /dev/sg3) can be specified. For example "sg_persist --read-keys /dev/sdb" will work in the 2.6 series kernels.

The only scope for PROUT commands supported in the current draft of SPC-4 is "LU_SCOPE". Hence there seems to be no point in offering an option to set scope to another value.

Most errors with the PROUT sub-commands (e.g. missing or mismatched --prout-type=TYPE) will result in a RESERVATION CONFLICT status. This can be a bit confusing when you know there is only one (active) initiator: the "conflict" is with the SPC standard, not another initiator.

Some recent disks accept some PRIN and PROUT sub-commands when the media is stopped. One exception was setting the APTPL flag (with the --param-aptpl option) during a key register operation, it complained if the disk one stopped. The error indicated it wanted the disk spun up and when that happened, the registration was successful.

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

Due to the various option defaults the simplest example executes the 'read keys' sub-command of the PRIN command:

sg_persist /dev/sdb

This is the same as the following (long-winded) command:

sg_persist --in --read-keys --device=/dev/sdb

To read the current reservation either the '--read-reservation' form or the shorter '-r' can be used:

sg_persist -r /dev/sdb

To register the new reservation key 0x123abc the following could be used:

sg_persist --out --register --param-sark=123abc /dev/sdb

Given the above registration succeeds, to reserve the DEVICE (with type 'write exclusive') the following could be used:

sg_persist --out --reserve --param-rk=123abc

--prout-type=1 /dev/sdb

To release the reservation the following can be given (note that the --param-rk and --prout-type arguments must match those of the reservation):

sg_persist --out --release --param-rk=123abc

--prout-type=1 /dev/sdb

Finally to unregister a reservation key (and not effect other registrations which is what '--clear' would do) the command is a little surprising:

sg_persist --out --register --param-rk=123abc /dev/sdb

Now have a close look at the difference between the register and unregister examples above.

An example file that is suitably formatted to pass transportIDs via a '--transport-id=file=transport_ids.txt' option can be found in the examples sub-directory of the sg3_utils package. There is also a simple test script called sg_persist_tst.sh in the same directory.

The above sequence of commands was tested successfully on a Seagate Savvio 10K.3 disk and a 1200 SSD both of which have SAS interfaces.

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

## ENVIRONMENT VARIABLES
Currently there is one recognised environment variable: SG_PERSIST_IN_RDONLY. If present and only if a PRIN command has been selected then the given DEVICE is opened read-only (e.g. in Unix that is with the O_RDONLY flag). See the --readonly option.

## AUTHOR
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 the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg3_utils(sg3_utils), scsires(internet)


title: sg_prevent(8)

text:
# sg_prevent(8)

## NAME
sg_prevent - send SCSI PREVENT ALLOW MEDIUM REMOVAL command

## SYNOPSIS
sg_prevent [--allow] [--help] [--prevent=PC] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SCSI PREVENT ALLOW MEDIUM REMOVAL command to DEVICE. The default action of this utility is to prevent the removing or ejecting of the medium from a drive. This is done by ignoring the SCSI START STOP UNIT command (see sg_start) and ignoring the eject button on the drive when the user presses it. Drives that hold removable disks, tape cartridges or cd/dvd media typically implement this command. The definition of the "prevent" codes for this command differ between disks and tapes (covered by SBC-3 and SSC-3) and cd/dvd drives (covered by MMC-5). The "prevent codes" described here are from MMC-5.

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

-a, --allow

allow medium removal. This is equivalent to setting to '--prevent=2'. Cannot be used with --prevent=PC option (i.e. either use no options (hence prevent removal), this option or --prevent=PC).

-h, --help

output the usage message then exit.

-p, --prevent=PC

where PC is a prevent code value. Defined values are: 0 allows removal, 1 prevents removal (default), 2 allows persistent removal while 3 prevents persistent removal. "Persistent" in this context means that the initiator (port) that successfully uses code 3 blocks other initiators (ports) from allowing removal. A "persistent prevent" state can be cleared by the owner allowing persistent removal (code 2) or a power cycle (or anything that resets the device (LU)) or some special commands (e.g. various service actions of Persistent Reserve Out, see SPC-3).

-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_prevent 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-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_start(sg3_utils), sg_persist(sg3_utils)


title: sg_raw(8)

text:
# sg_raw(8)

## NAME
sg_raw - send arbitrary SCSI or NVMe command to a device

## SYNOPSIS
sg_raw [--binary] [--cmdfile=CF] [--cmdset=CS] [--enumerate] [--help] [--infile=IFILE] [--nosense] [--nvm] [--outfile=OFILE] [--raw] [--readonly] [--request=RLEN] [--scan=FO,LO] [--send=SLEN] [--skip=KLEN] [--timeout=SECS] [--verbose] [--version] DEVICE [CDB0 CDB1 ...]

## DESCRIPTION
This utility sends an arbitrary SCSI command (between 6 and 256 bytes) to the DEVICE. There may be no associated data transfer; or data may be read from a file and sent to the DEVICE; or data may be received from the DEVICE and then displayed or written to a file. If supported by the pass through, bidirectional commands may be sent (i.e. containing both data to be sent to the DEVICE and received from the DEVICE).

The SCSI command may be between 6 and 256 bytes long. Each command byte is specified in plain hex format (00..FF) without a prefix or suffix. The command can be given either on the command line or via the --cmdfile=CF option. See EXAMPLES section below.

The commands pass through a generic SCSI interface which is implemented for several operating systems including Linux, FreeBSD and Windows.

Experimental support has been added to send NVMe Admin and NVM commands to the DEVICE. Since all NVMe commands are 64 bytes long it is more convenient to use the --cmdfile=CF option rather than type the 64 bytes of the NVMe command on the command line. See the section on NVME below. A heuristic based on command length is used to decide if the given command is SCSI or NVMe, to override this heuristic use the --cmdset=CS option.

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

-b, --binary

Dump data in binary form, even when writing to stdout.

-c, --cmdfile=CF

CF is the name of a file which contains the command to be executed. Without this option the command must be given on the command line, after the options and the DEVICE.

-C, --cmdset=CS

CS is a number to indicate which command set (i.e. SCSI or NVMe) to use. 0, the default, causes a heuristic based on command length to be used. Use a CS of 1 to override that heuristic and choose the SCSI command set. Use a CS of 2 to override that heuristic and choose the NVMe command set.

-h, --help

Display usage information and exit.

-i, --infile=IFILE

Read binary data from IFILE instead of stdin. This option is ignored if --send is not specified. That data, if used, will become the command's "data-out" buffer.

-n, --nosense

Don't display SCSI Sense information.

-N, --nvm

When sending NVMe commands, the Admin command set is assumed. To send the NVM command set (e.g. the Read and Write (user data) commands) this option needs to be given.

-o, --outfile=OFILE

Write data received from the DEVICE to OFILE. That data is the command's "data-in" buffer. The data is written in binary. By default, data is dumped in hex format to stdout. If OFILE is '-' then data is dumped in binary to stdout. This option is ignored if --request is not specified.

-w, --raw

interpret CF (i.e. the command file) as containing binary. The default is to assume that it contains ASCII hexadecimal.

-R, --readonly

Open DEVICE read-only. The default (without this option) is to open it read-write.

-r, --request=RLEN

Expect to receive up to RLEN bytes of data from the DEVICE. RLEN may be suffixed with 'k' to use kilobytes (1024 bytes) instead of bytes. RLEN is decimal unless it has a leading '0x' or a trailing 'h'.

If RLEN is too small (i.e. either smaller than indicated by the cdb (typically the "allocation length" field) and/or smaller than the DEVICE tries to send back) then the HBA driver may complain. Making RLEN larger than required should cause no problems. Most SCSI "data-in" commands return a data block that contains (in its early bytes) a length that the DEVICE would "like" to send back if the "allocation length" field in the cdb is large enough. In practice, the DEVICE will return no more bytes than indicated in the "allocation length" field of the cdb.

-Q, --scan=FO,LO

Scan a range of opcodes (i.e. first byte of each command). The first opcode in the scan is FO (which is decimal unless it has a '0x' prefix or 'h' suffix). The last opcode in the scan is LO. The maximum value of LO is 255. The remaining bytes of the SCSI/NVMe command are as supplied at invocation.

Warning: this option can be dangerous. Sending somewhat arbitrary commands to a device can have unexpected results. It is recommended that this option is used with the --cmdset=CS option where CS is 1 or 2 in order to stop the command set possibly changing during the scan.

-s, --send=SLEN

Read SLEN bytes of data, either from stdin or from a file, and send them to the DEVICE. In the SCSI transport, SLEN becomes the length (in bytes) of the "data-out" buffer. SLEN is decimal unless it has a leading '0x' or a trailing 'h'.

It is the responsibility of the user to make sure that the "data-out" length implied or stated in the cdb matches SLEN. Note that some common SCSI commands such as WRITE(10) have a "transfer length" field whose units are logical blocks (which are usually 512 or 4096 bytes long).

-k, --skip=KLEN

Skip the first KLEN bytes of the input file or stream. This option is ignored if --send is not specified. If --send is given and this option is not given, then zero bytes are skipped.

-t, --timeout=SECS

Wait up to SECS seconds for command completion (default: 20). Note that if a command times out the operating system may start by aborting the command and if that is unsuccessful it may attempt to reset the device. An alternate long option form is --tmo=SECS.

-v, --verbose

Increase level of verbosity. Can be used multiple times.

-V, --version

Display version and license information and exit.

## NOTES
The sg_inq utility can be used to send an INQUIRY command to a device to determine its peripheral device type (e.g. '1' for a streaming device (tape drive)) which determines which SCSI command sets a device should support (e.g. SPC and SSC). The sg_vpd utility reads and decodes a device's Vital Product Pages which may contain useful information.

The ability to send more than a 16 byte CDB (in some cases 12 byte CDB) may be restricted by the pass-through interface, the low level driver or the transport. In the Linux series 3 kernels, the bsg driver can handle longer CDBs, block devices (e.g. /dev/sdc) accessed via the SG_IO ioctl cannot handle CDBs longer than 16 bytes, and the sg driver can handle longer CDBs from lk 3.17 .

The CDB command name defined by T10 for the given CDB is shown if the '-vv' option is given. The command line syntax still needs to be correct, so /dev/null may be used for the DEVICE since the CDB command name decoding is done before the DEVICE is checked.

The intention of the --scan=FO,LO option is to slightly simplify the process of finding hidden or undocumented commands. It should be used with care; for example checking for vendor specific SCSI commands: 'sg_raw --cmdset=1 --scan=0xc0,0xff /dev/sg1 0 0 0 0 0 0'.

## NVME SUPPORT
Support for NVMe (a.k.a. NVM Express) is currently experimental. NVMe concepts map reasonably well to the SCSI architecture. A SCSI logical unit (LU) is similar to a NVMe namespace (although LUN 0 is very common in SCSI while namespace IDs start at 1). A SCSI target device is similar to a NVMe controller. SCSI commands vary from 6 to 260 bytes long (although SCSI command descriptor blocks (cdb_s) longer than 32 bytes are uncommon) while all NVMe commands are currently 64 bytes long. The SCSI architecture makes a clear distinction between an initiator (often called a HBA) and a target (device) while (at least on the PCIe transport) the NVMe controller plays both roles. This utility defaults to assuming the user provided 64 byte command belongs to NVMe's Admin command set. To issue commands from the "NVM" command set, the --nvm option must be given. Admin and NVM commands are sent to submission queue 0.

One significant difference is that SCSI uses a big endian representation for integers that are longer than 8 bits (i.e. longer than 1 byte) while NVMe uses a little endian representation (like most things that have originated from the Intel organisation). NVMe specifications talk about Words (16 bits), Double Words (32 bits) and sometimes Quad Words (64 bits) and has tighter alignment requirements than SCSI.

One difference that impacts this utility is that NVMe places pointers to host memory in its commands while SCSI leaves this detail to whichever transport it is using (e.g. SAS, iSCSI, SRP). Since this utility takes the command from the user (either on the command line or in a file named CF) but this utility allocates a data-in or data-out buffer as required, the user does not know in advance what the address of that buffer will be. Some special addresses have been introduced to help with this problem: the address 0xfffffffffffffffe is interpreted as "use the data-in buffer's address" while 0xfffffffffffffffd is interpreted as "use the data-out buffer's address". Since NVMe uses little endian notation then that first address appears in the NVMe command byte stream as "fe" followed by seven "ff"s. A similar arrangement is made for the length of that buffer (in bytes), but since that is a 32 byte quantity, the first 4 bytes (all "ff"s) are removed.

Several command file examples can be found in the inhex directory of this package's source tarball: nvme_identify_ctl.hex, nvme_dev_self_test.hex, nvme_read_ctl.hex and nvme_write_ctl.hex .

Beware: the NVMe standard often refers to some of its fields as "0's based". They are typically counts of something like the number of blocks to be read. For example in NVMe Read command, a "0's based" number of blocks field containing the value 3 means to read 4 blocks! No, this is not a joke.

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

sg_raw /dev/scd0 1b 00 00 00 02 00

Eject the medium in CD drive /dev/scd0.

sg_raw -r 1k /dev/sg0 12 00 00 00 60 00

Perform an INQUIRY on /dev/sg0 and dump the response data (up to 1024 bytes) to stdout.

sg_raw -s 512 -i i512.bin /dev/sda 3b 02 00 00 00 00 00 02 00 00

Showing an example of writing 512 bytes to a sector on a disk is a little dangerous. Instead this example will read i512.bin (assumed to be 512 bytes long) and use the SCSI WRITE BUFFER command to send it to the "data" buffer (that is mode 2). This is a safe operation.

sg_raw -r 512 -o o512.bin /dev/sda 3c 02 00 00 00 00 00 02 00 00

This will use the SCSI READ BUFFER command to read 512 bytes from the "data" buffer (i.e. mode 2) then write it to the o512.bin file. When used in conjunction with the previous example, if both commands work then 'cmp i512.bin o512.bin' should show a match.

sg_raw --infile=urandom.bin --send=512 --request=512 --outfile=out.bin "/dev/bsg/7:0:0:0" 53 00 00 00 00 00 00 00 01 00

This is a bidirectional XDWRITEREAD(10) command being sent via a Linux bsg device. Note that data is being read from "urandom.bin" and sent to the device (data-out) while resulting data (data-in) is placed in the "out.bin" file. Also note the length of both is 512 bytes which corresponds to the transfer length of 1 (block) in the cdb (i.e. the second last byte). urandom.bin can be produced like this:

dd if=/dev/urandom bs=512 count=1 of=urandom.bin

sg_raw.exe PhysicalDrive1 a1 0c 0e 00 00 00 00 00 00 e0 00 00

This example is from Windows and shows a ATA STANDBY IMMEDIATE command being sent to PhysicalDrive1. That ATA command is contained within the SCSI ATA PASS-THROUGH(12) command (see the SAT or SAT-2 standard at https://www.t10.org). Notice that the STANDBY IMMEDIATE command does not send or receive any additional data, however if it fails sense data should be returned and displayed.

For NVME examples see the files in this package's inhex directory that

start with 'nvme_' such as inhex/nvme_identify_ctl.hex .

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

## AUTHOR
Written by Ingo van Lil

## REPORTING BUGS
Report bugs to <inguin at gmx dot de> or to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2001-2023 Ingo van Lil

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

## SEE ALSO
sg_inq, sg_vpd, sg3_utils (sg3_utils), plscsi


title: sg_rbuf(8)

text:
# sg_rbuf(8)

## NAME
sg_rbuf - reads data using SCSI READ BUFFER command

## SYNOPSIS
sg_rbuf [--buffer=EACH] [--dio] [--help] [--mmap] [--quick] [--size=OVERALL] [--verbose] [--version] DEVICE

sg_rbuf [-b=EACH_KIB] [-d] [-m] [-q] [-s=OVERALL_MIB] [-t] [-v] [-V] DEVICE

## DESCRIPTION
This command reads data with the SCSI READ BUFFER command and then discards it. Typically the data being read is from a disk's memory cache. It is assumed that the data is sourced quickly (although this is not guaranteed by the SCSI standards) so that it is faster than reading data from the media. This command is designed for timing transfer speeds across a SCSI transport.

To fetch the data with a SCSI READ BUFFER command and optionally decode it see the sg_read_buffer utility. There is also a sg_write_buffer utility useful for downloading firmware amongst other things.

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.

This is a Linux only utility and only works when DEVICE is an sg device (e.g. "/dev/sg1"). The sg_read_buffer utility has similar functionality and is ported to other OSes and within Linux can use bsg and normal block device names (e.g. "/dev/sdc").

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

-b, --buffer=EACH

where EACH is the number of bytes to be transferred by each READ BUFFER command. The default is the actual available buffer size returned by the READ BUFFER (descriptor) command. The maximum is the same as the default, hence this argument can only be used to reduce the size of each transfer to less than the device's actual available buffer size.

-d, --dio

use direct IO if available. This option is only available if the DEVICE is a sg driver device node (e.g. /dev/sg1). In this case the sg driver will attempt to configure the DMA from the SCSI adapter to transfer directly into user memory. This will eliminate the copy via kernel buffers. If not available then this will be reported and indirect IO will be done instead.

-h, --help

print usage message then exit.

-m, --mmap

use memory mapped IO if available. This option is only available if the DEVICE is a sg driver device node (e.g. /dev/sg1). In this case the sg driver will attempt to configure the DMA from the SCSI adapter to transfer directly into user memory. This will eliminate the copy via kernel buffers.

-O, --old

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

-q, --quick

only transfer the data into kernel buffers (typically by DMA from the SCSI adapter card) and do not move it into the user space. This option is only available if the DEVICE is a sg driver device node (e.g. /dev/sg1).

-s, --size=OVERALL

where OVERALL is the size of total transfer in bytes. The default is 200 MiB (200*1024*1024 bytes). The actual number of bytes transferred may be slightly less than requested since all transfers are the same size (and an integer division is involved rounding towards zero).

-t, --time

times the bulk data transfer component of this command. The elapsed time is printed out plus a MB/sec calculation. In this case "MB" is 1,000,000 bytes. The gettimeofday() system call is used internally for the time calculation.

-v, --verbose

increase level of verbosity. Can be used multiple times.

-V, --version

print out version string then exit.

## NOTES
This command is typically used on modern SCSI disks which have a RAM cache in their drive electronics. If no IO to the magnetic media, or slower devices like flash RAM, is involved then the disk may be able to source data fast enough to saturate the bandwidth of the SCSI transport. The bottleneck may then be the DMA element in the HBA, the Linux drivers or the host machine's hardware (e.g. speed of RAM).

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

## EXAMPLES
On the test system /dev/sg0 corresponds to a fast disk on a U2W SCSI bus (max 80 MB/sec). The disk specifications state that its cache is 4 MB.

$ time ./sg_rbuf /dev/sg0

READ BUFFER reports: buffer capacity=3434944,

offset boundary=6

Read 200 MiB (actual 199 MiB, 209531584 bytes),

buffer size=3354 KiB

real 0m5.072s, user 0m0.000s, sys 0m2.280s

So that is approximately 40 MB/sec at 40 % utilization. Now with the addition of the "-q" option this throughput improves and the utilization drops to 0%.

$ time ./sg_rbuf -q /dev/sg0

READ BUFFER reports: buffer capacity=3434944,

offset boundary=6

Read 200 MiB (actual 199 MiB, 209531584 bytes),

buffer size=3354 KiB

real 0m2.784s, user 0m0.000s, sys 0m0.000s

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

-b=EACH_KIB

where EACH_KIB is the number of Kilobytes (i.e. 1024 byte units) to be transferred by each READ BUFFER command. Similar to the --buffer=EACH option in the main description but the units are different.

-d

use direct IO if available. Equivalent to the --dio option in the main description.

-m

use memory mapped IO if available. Equivalent to the --mmap option in the main description.

-N, --new

Switch to the newer style options.

-q

only transfer the data into kernel buffers (typically by DMA from the SCSI adapter card) and do not move it into the user space. Equivalent to the --quick option in the main description.

-s=OVERALL_MIB

where OVERALL_MIB is the size of total transfer in Megabytes (1048576 bytes). Similar to the --size=OVERALL option in the main description but the units are different.

-t

times the bulk data transfer component of this command. Equivalent to the --time option in the main description.

-v

increase level of verbosity. Can be used multiple times.

-V

print out version string then exit.

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

## AUTHOR
Written by Douglas Gilbert

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

## COPYRIGHT
Copyright © 2000-2017 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_read_buffer, sg_write_buffer, sg_test_rwbuf(all in sg3_utils)


title: sg_rdac(8)

text:
# sg_rdac(8)

## NAME
sg_rdac - display or modify SCSI RDAC Redundant Controller mode page

## SYNOPSIS
sg_rdac [-6] [-a] [-f=LUN] [-v] [-V] DEVICE

## DESCRIPTION
sg_rdac displays or modifies the RDAC controller settings via the Redundant Controller mode page (0x2C). When modifying the settings it allows one to transfer the ownership of individual drives to the controller the command was received on.

## OPTIONS
-6

Use the 6 byte cdb variants of the SCSI MODE SENSE and MODE SELECT commands. The default action (in the absence of this option) is to use the 10 byte cdb variants.

-a

Transfer all (visible) devices

-f=LUN

Transfer the device identified by LUN. This command will only work if the controller supports 'Dual Active Mode' (aka active/active mode). LUN is a decimal number which cannot exceed 31 when the -6 option is given, otherwise is cannot exceed 255.

-v

be verbose

-V

print version string then exit

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

## AUTHOR
Written by Hannes Reinecke <hare at suse dot com>, based on sg_emc_trespass.

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

## COPYRIGHT
Copyright © 2006-2017 Hannes Reinecke, 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_read(8)

text:
# sg_read(8)

## NAME
sg_read - read multiple blocks of data, optionally with SCSI READ commands

## SYNOPSIS
sg_read [blk_sgio=0|1] [bpt=BPT] [bs=BS] [cdbsz=6|10|12|16] count=COUNT [dio=0|1] [dpo=0|1] [fua=0|1] if=IFILE [mmap=0|1] [no_dxfer=0|1] [odir=0|1] [skip=SKIP] [time=TI] [verbose=VERB] [--help] [--version]

## DESCRIPTION
Read data from a Linux SCSI generic (sg) device, a block device or a normal file with each read command issued to the same offset or logical block address (lba). This can be used to test (or time) disk caching, SCSI (or some other) transport throughput, and/or SCSI command overhead.

When the COUNT value is positive, then up to BPT blocks are read at a time, until the COUNT is exhausted. Each read operation starts at the same lba which, if SKIP is not given, is the beginning of the file or device.

The COUNT value may be negative when IFILE is a sg device or is a block device with 'blk_sgio=1' set. Alternatively 'bpt=0' may be given. In these cases |COUNT| "zero block" SCSI READ commands are issued. "Zero block" means "do nothing" for SCSI READ 10, 12 and 16 byte commands (but not for the 6 byte variant). In practice "zero block" SCSI READ commands have low latency and so are one way to measure SCSI command overhead.

Please note: this is a very old utility that uses 32 bit integers for disk LBAs and the count. Hence it will not be able to address beyond 2 Terabytes on a disk with logical blocks that are 512 bytes long. Alternatives are the sg_dd and ddpt utilities.

## OPTIONS
blk_sgio=0 | 1

The default action of this utility is to use the Unix read() command when the IFILE is a block device. In lk 2.6 many block devices can handle SCSI commands issued via the SG_IO ioctl. So when this option is set the SG_IO ioctl sends SCSI READ commands to IFILE if it is a block device.

bpt=BPT

where BPT is the maximum number of blocks each read operation fetches. Fewer blocks will be fetched when the remaining COUNT is less than BPT. The default value for BPT is 128. Note that each read operation starts at the same lba (as given by skip=SKIP or 0). If 'bpt=0' then the COUNT is interpreted as the number of zero block SCSI READ commands to issue.

bs=BS

where BS is the size (in bytes) of each block read. This must be the block size of the physical device (defaults to 512) if SCSI commands are being issued to IFILE.

cdbsz=6 | 10 | 12 | 16

size of SCSI READ commands issued on sg device names, or block devices if 'blk_sgio=1' is given. Default is 10 byte SCSI READ cdbs.

count=COUNT

when COUNT is a positive number, read that number of blocks, typically with multiple read operations. When COUNT is negative then |COUNT| SCSI READ commands are performed requesting zero blocks to be transferred. This option is mandatory.

dio=0 | 1

default is 0 which selects indirect IO. Value of 1 attempts direct IO which, if not available, falls back to indirect IO and notes this at completion. This option is only active if IFILE is an sg device. If direct IO is selected and /sys/module/sg/parameters/allow_dio has the value of 0 then a warning is issued (and indirect IO is performed)

dpo=0 | 1

when set the disable page out (DPO) bit in SCSI READ commands is set. Otherwise the DPO bit is cleared (default).

fua=0 | 1

when set the force unit access (FUA) bit in SCSI READ commands is set. Otherwise the FUA bit is cleared (default).

if=IFILE

read from this IFILE. This argument must be given. If the IFILE is a normal file then it must be seekable (if (COUNT > BPT) or skip=SKIP is given). Hence stdin is not acceptable (and giving "-" as the IFILE argument is reported as an error).

mmap=0 | 1

default is 0 which selects indirect IO. Value of 1 causes memory mapped IO to be performed. Selecting both dio and mmap is an error. This option is only active if IFILE is an sg device.

no_dxfer=0 | 1

when set then DMA transfers from the device are made into kernel buffers but no further (i.e. there is no second copy into the user space). The default value is 0 in which case transfers are made into the user space. When neither mmap nor dio is set then data transfer are copied via kernel buffers (i.e. a double copy). Mainly for testing.

odir=0 | 1

when set opens an IFILE which is a block device with an additional O_DIRECT flag. The default value is 0 (i.e. don't open block devices O_DIRECT).

skip=SKIP

all read operations will start offset by SKIP bs-sized blocks from the start of the input file (or device).

time=TI

When TI is 0 (default) doesn't perform timing. When 1, times transfer and does throughput calculation, starting at the first issued command until completion. When 2, times transfer and does throughput calculation, starting at the second issued command until completion. When 3 times from third command, etc. An average number of commands (SCSI READs or Unix read()s) executed per second is also output.

verbose=VERB

as VERB increases so does the amount of debug output sent to stderr. Default value is zero which yields the minimum amount of debug output. A value of 1 reports extra information that is not repetitive.

--help

Output the usage message then exit.

--version

Output the version string then exit.

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

Data usually gets to the user space in a 2 stage process: first the SCSI adapter DMAs into kernel buffers and then the sg driver copies this data into user memory. This is called "indirect IO" and there is a "dio" option to select "direct IO" which will DMA directly into user memory. Due to some issues "direct IO" is disabled in the sg driver and needs a configuration change to activate it. This is typically done with "echo 1 > /sys/module/sg/parameters/allow_dio". An alternate way to avoid the 2 stage copy is to select memory mapped IO with 'mmap=1'.

## SIGNALS
The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIGPIPE output the number of remaining blocks to be transferred; then they have their default action. SIGUSR1 causes the same information to be output yet the copy continues. All output caused by signals is sent to stderr.

## EXAMPLES
Let us assume that /dev/sg0 is a disk and we wish to time the disk's cache performance.

sg_read if=/dev/sg0 bs=512 count=1MB mmap=1 time=2

This command will continually read 128 512 byte blocks from block 0. The "128" is the default value for 'bpt' while "block 0" is chosen because the 'skip' argument was not given. This will continue until 1,000,000 blocks are read. The idea behind using 'time=2' is that the first 64 KiB read operation will involve reading the magnetic media while the remaining read operations will "hit" the disk's cache. The output of third command will look like this:

time from second command to end was 4.50 secs, 113.70 MB/sec

Average number of READ commands per second was 1735.27

1000000+0 records in, SCSI commands issued: 7813

## EXIT STATUS
The exit status of sg_read 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 © 2000-2019 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
To time streaming media read or write time see sg_dd is in the sg3_utils package and ddpt in a package of the same name. The lmbench package contains lmdd which is also interesting. raw(8), dd(1)


title: sg_read_attr(8)

summary: send SCSI READ ATTRIBUTE command

text:
# sg_read_attr(8)

## NAME
sg_read_attr - send SCSI READ ATTRIBUTE command

## SYNOPSIS
sg_read_attr [--cache] [--enumerate] [--ea=EA] [--filter=FL] [--first=FAI] [--help] [--hex] [--in=FN] [--lvn=LVN] [--maxlen=LEN] [--pn=PN] [--quiet] [--raw] [--readonly] [--sa=SA] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SCSI READ ATTRIBUTE command to DEVICE and outputs the data returned. This command was introduced in SPC-3 revision 1 and thus is applicable to all SCSI devices. In practice it is used mainly for tape systems. This utility is based on the SPC-5 draft standard, revision 17 (spc5r17.pdf).

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

-c, --cache

sets the CACHE bit in the READ ATTRIBUTE cdb. This instructs the device server to return cached attributes. By default that bit is cleared which instructs the device server not to return cached attributes.

-e, --enumerate

enumerates all known attributes and service actions. Attributes include an identifier, length, format and a name as defined by T10. If DEVICE is given then it is ignored.

-E, --ea=EA

where EA is an element address which is placed in the READ ATTRIBUTE cdb. This field is only found in SMC-2 and SMC-3 drafts for medium changers usually associated with tape libraries. By default this field is set to zero.

-f, --filter=FL

where FL is an attribute identifier in the range 0 to 65535 or -1. Attribute identifiers are typically given in hexadecimal in which case the hex number should be prefixed by "0x" or has a trailing "h". "-1" is the default value and means 'match all'; for all other values of FL on the matching attribute is output.

-F, --first=FAI

where FAI is the "first attribute identifier" field in the cdb. It seems as though the intent of this field is that only attributes whose identifiers are equal to or greater than FAI are returned. The default value of FAI is zero. Attributes are returned in ascending identifier order.

-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 with a leading address (starting at 0) on each line. When used twice each attribute 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).

Output generated by '-HHH' (or --hex used three times) can be redirected to a file. That file will be in suitable format for --in=FN to use in a later invocation.

-i, --in=FN

FN is treated as a file name (or '-' for stdin) which contains ASCII hexadecimal or binary representing the response to a READ ATTRIBUTE command with service action 0x0 (i.e (fetch) attribute values). When this option is given then DEVICE (if also given) is ignored.

By default FN is assumed to contain ASCII hexadecimal arranged as bytes which a space, tab or comma delimited. All characters from (and including) "#" to the end of line are ignored. If the --raw option is also given then FN is assumed to contain binary data. When the --raw option is given then after processing the input the internal raw variable is reset to 0 so it has no effect on the output.

Since the READ ATTRIBUTE response does not contain the service action number that it is a response to, then the --sa=SA should be given (if not service action 0 (attribute values) is assumed.

-l, --lvn=LVN

where LVN is placed in the "logical volume number" field of the cdb. The default value is zero which is required to be the logical volume number if the device only has one volume.

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

-p, --pn=PN

where PN is placed in the "partition number" field of the cdb. If the DEVICE only has one partition then its partition number must be zero. The default value of PN is zero.

-q, --quiet

this option reduces the amount of information output. For example when used once (SA=0), it suppresses the header line announcing the output of attributes; when used twice it suppresses the name of each attribute, leaving only the associated attribute values (or strings).

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

-s, --sa=SA

where SA is placed on the "service action" field of the cdb. Values of 0 to 63 are accepted with a default of 0. spc5r08.pdf defines five service actions: 0 for attributes values ; 1 for an attribute list (names, not values), 2 for the logical volume list; 3 for the partition list; 4 is restricted for SMC-3; and 5 for the supported attribute list.

Alternatively an acronym can be given for SA. The acronym should be one of "av", "al", "lvl", "pn", "smc" or "sa" for service actions 0 to 5 respectively. The acronyms can also be given in upper case.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
Only tape systems seem to implement the SCSI READ ATTRIBUTE command. The vast majority of its definition is in the SPC standard so other device types could use it.

Much of the information provided by READ ATTRIBUTE can also be found in pages returned by LOG SENSE (see the sg_logs utility) and in the VPD pages returned by the INQUIRY command.

## EXAMPLES
To list the attributes of a tape drive whose DEVICE is /dev/sg1 , the following could be used:

\# sg_read_attr -s al /dev/sg1

Attribute list:

Remaining capacity in partition [MiB]

Maximum capacity in partition [MiB]

TapeAlert flags

Load count

MAM space remaining [B]

Assigning organization

Format density code

...

To check the number of partitions:

\# sg_read_attr -s pl /dev/sg1

Partition number list:

First partition number: 0

Number of partitions available: 2

And to see the attribute values (which is the default service action):

\# sg_read_attr /dev/sg1

Attribute values:

Remaining capacity in partition [MiB]: 1386103

Maximum capacity in partition [MiB]: 1386103

TapeAlert flags: 0

....

To redirect the attribute values response to a file for later decoding:

\# sg_read_attr -HHH /dev/sg1 > av.hex

And later the response held in the av.hex file could be decoded with:

\# sg_read_attr -s av --in=av.hex

Attribute values:

Remaining capacity in partition [MiB]: 1386103

Maximum capacity in partition [MiB]: 1386103

TapeAlert flags: 0

....

## EXIT STATUS
The exit status of sg_read_attr 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 © 2016-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,sg_logs(sg3_utils)


title: sg_read_block_limits(8)

summary: send SCSI READ BLOCK LIMITS command

text:
# sg_read_block_limits(8)

## NAME
sg_read_block_limits - send SCSI READ BLOCK LIMITS command

## SYNOPSIS
sg_read_block_limits [--help] [--hex] [--mloi] [--raw] [--readonly] [--verbose] [--version] DEVICE

## DESCRIPTION
Send a SCSI READ BLOCK LIMITS command to DEVICE and outputs the response. This command is defined for tape (drives) and its description is found in the SSC documents at https://www.t10.org .

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

-h, --help

output the usage message then exit.

-H, --hex

output response in hex (rather than decode it).

-m, --mloi

sets the MLOI bit in the READ BLOCK LIMITS command and if that succeeds, prints out the Maximum Logical Object Identifier (MLOI) value. The MLOI bit was introduced in the ssc4r02.pdf draft.

-r, --raw

output response in binary to stdout.

-R, --readonly

open DEVICE in read-only mode. The default is to open it in read-write mode.

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

## EXAMPLES
It is usually okay to use no options. Here is an invocation (on the first line following the "#" command prompt) followed by some typical output:

\# sg_read_block_limits /dev/st0

Read Block Limits results:

Minimum block size: 1 byte(s)

Maximum block size: 16777215 byte(s), 16383 KB, 15 MB

Granularity: 0

## AUTHORS
Written by Douglas Gilbert.

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

## COPYRIGHT
Copyright © 2009-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_read_buffer(8)

summary: send SCSI READ BUFFER command

text:
# sg_read_buffer(8)

## NAME
sg_read_buffer - send SCSI READ BUFFER command

## SYNOPSIS
sg_read_buffer [--eh_code=EHC] [--help] [--hex] [--id=ID] [--inhex=FN] [--length=LEN] [--mode=MO] [--no_output] [--offset=OFF] [--raw] [--readonly] [--specific=MS] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SCSI READ BUFFER command to the DEVICE, and if there is a response either decodes it, prints it in hexadecimal or sends it in binary to stdout. If a response is received for a "descriptor" mode then, in the absence of --hex and --raw, it is decoded. Response for non-descriptor modes are output in hexadecimal unless the --raw option is given.

The responses to the Read microcode status ('rd_microc_st' [0xf]) and Error history ('err_hist' [0x1c]) modes are decoded as described in spc6r06.pdf and earlier T10 documents.

This utility may be called without a DEVICE but with a --inhex=FN option instead. FN is expected to be a file name (or

'-' for stdin). The contents of the file (or stdin stream) is assumed to be hexadecimal (or binary) data that represents a SCSI READ BUFFER command response and is decoded as such.

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

-e, --eh_code=EHC

EHC is the error history code placed in the Buffer ID field of the cdb. The Mode field is set to err_hist [0x1c]. The option is equivalent to using the '--mode=eh --id=EHC' options. If this option and one of the other options is given, then an error will be generated if they contradict. The default (maximum) response length is increased to 64 bytes when may need to be increased (if so that is noted if the output is truncated).

An example is setting EHC to 0 in which case the error history directory will be decoded (unless --hex or --raw options is given).

-h, --help

output the usage message then exit. If used multiple times also prints the mode names and their acronyms.

-H, --hex

output the response in hexadecimal. When given twice the response is output in hex with the corresponding representation in ASCII to the right of each line. When given three time the hex is printed without addresses (indexes) at the start of each line; this type of format is suitable for the --inhex=FN option on a subsequent invocation.

-i, --id=ID

this option sets the Buffer ID field in the cdb. ID is a value between 0 (default) and 255 inclusive. The meaning of the Buffer ID field varies with the value in the Mode field of the cdb.

-I, --inhex=FN

FN is expected to be a file name (or '-' for stdin) which contains ASCII hexadecimal or binary representing a READ BUFFER response. If known this utility will then decode that response. It is preferable to also supply the --mode=MO, --id=ID and possible --specific=MS options, since these are not present in the response. 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 is treated as binary.

-l, --length=LEN

where LEN is the length, in bytes, that is placed in the "allocation length" field in the cdb. The default value is 4 (bytes) which is increased to 64 if the 'err_hist' mode [0x1c] is given or implied. The device may respond with less bytes.

If the --inhex=FN option is given, then the default value of the length is increased to 8192 bytes. This length may then be reduced to match the number of bytes decoded from the contents of FN.

-m, --mode=MO

this option sets the mode field in the cdb. MO is a value between 0 (default) and 31 inclusive. Alternatively an abbreviation can be given. See the MODES section below. To list the available mode abbreviations use an invalid one (e.g. '--mode=xxx'). As an example, to fetch the read buffer descriptor give '--mode=desc' .

-N, --no_output

when this option is given after sending the SCSI command to the DEVICE the response is processed, looking for any errors, and then this utility exits. Any data read by the READ BUFFER command is ignored.

May be useful for timing larger reads from the DEVICE buffer in 'data' mode [0x2].

-o, --offset=OFF

this option sets the buffer offset field in the cdb. OFF is a value between 0 (default) and 2**24-1 . It is a byte offset.

-r, --raw

if a response is received then it is sent in binary to stdout. When this option is given together with --inhex=FN then the contents of FN is assumed to be binary and the output of this utility is normal ASCII (i.e. _not_ in binary).

-R, --readonly

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

-S, --specific=MS

this option sets the mode specific field in the cdb. MS is a value between 0 and 7 as this is a 3 bit field.

-v, --verbose

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

-V, --version

print the version string and then exit.

## MODES
Following is a list of READ BUFFER command settings for the MODE field. First is an acronym accepted by the MO argument of this utility. Following the acronym in square brackets are the corresponding decimal and hex values that may also be given for MO. The following are listed in numerical order.

hd [0, 0x0]

Combined header and data (obsolete in SPC-4).

vendor [1, 0x1]

Vendor specific.

data [2, 0x2]

Data.

desc [3, 0x3]

Descriptor: yields 4 bytes that contain an offset boundary field (1 byte) and buffer capacity (3 bytes).

echo [10, 0xa]

Read data from echo buffer (was called "Echo buffer" in SPC-3).

echo_desc [11, 0xb]

Echo buffer descriptor: yields 4 bytes of which the last (lowest) 13 bits represent the echo buffer capacity. The maximum echo buffer size is 4096 bytes.

rd_microc_st [15, 0xf]

Read microcode status. Added in spc5r20 .

en_ex [26, 0x1a]

Enable expander communications protocol and Echo buffer. Made obsolete in SPC-4.

err_hist|eh [28, 0x1c]

Error history. Either 'err_hist' or the short 'eh' abbreviation can be used for this mode. Introduced in SPC-4.

## NOTES
All numbers given with options are assumed to be decimal. Alternatively numerical values can be given in hexadecimal preceded by either "0x" or "0X" (or has a trailing "h" or "H").

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

## AUTHORS
Written by Luben Tuikov and Douglas Gilbert.

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

## COPYRIGHT
Copyright © 2006-2023 Luben Tuikov 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_write_buffer(sg3_utils)