doc/sg_opcodes.8

.TH SG_OPCODES "8" "September 2022" "sg3_utils\-1.48" SG3_UTILS
.SH NAME
sg_opcodes \- report supported SCSI commands or task management functions
.SH SYNOPSIS
.B sg_opcodes
[\fI\-\-alpha\fR] [\fI\-\-compact\fR] [\fI\-\-enumerate\fR] [\fI\-\-help\fR]
[\fI\-\-hex\fR] [\fI\-\-inhex=FN\fR] [\fI\-\-json[=JO]\fR] [\fI\-\-mask\fR]
[\fI\-\-mlu\fR] [\fI\-\-no-inquiry\fR] [\fI\-\-opcode=OP[,SA]\fR]
[\fI\-\-pdt=DT\fR] [\fI\-\-raw\fR] [\fI\-\-rctd\fR] [\fI\-\-repd\fR]
[\fI\-\-sa=SA\fR] [\fI\-\-tmf\fR] [\fI\-\-unsorted\fR] [\fI\-\-verbose\fR]
[\fI\-\-version\fR] \fIDEVICE\fR
.PP
.B sg_opcodes
[\fI\-a\fR] [\fI\-c\fR] [\fI\-e\fR] [\fI\-H\fR] [\fI\-i=FN\fR] [\fI\-j\fR]
[\fI\-m\fR] [\fI\-M\fR] [\fI\-n\fR] [\fI\-o=OP\fR] [\fI\-p=DT\fR] [\fI\-q\fR]
[\fI\-R\fR] [\fI\-s=SA\fR] [\fI\-t\fR] [\fI\-u\fR] [\fI\-v\fR] [\fI\-V\fR]
[\fI\-?\fR] \fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
This utility sends a SCSI REPORT SUPPORTED OPERATION CODES or a REPORT
SUPPORTED TASK MANAGEMENT FUNCTIONS command to the \fIDEVICE\fR 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
\fI\-\-opcode=OP\fR option (perhaps with additional information from the
\fI\-\-sa=SA\fR option).
.PP
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.
.PP
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.
.PP
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.
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
.TP
\fB\-a\fR, \fB\-\-alpha\fR
when all supported commands are being listed there is no requirement for
the device server (i.e. the \fIDEVICE\fR) 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 \fB\-\-unsorted\fR option are
both _not_ given then the list of supported commands is sorted
numerically (first by operation code and then by service action).
.TP
\fB\-c\fR, \fB\-\-compact\fR
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.
.TP
\fB\-e\fR, \fB\-\-enumerate\fR
this option prints the name of the SCSI command based on the given opcode,
peripheral device type and optionally the service action. If given,
\fIDEVICE\fR 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).
.TP
\fB\-h\fR, \fB\-\-help\fR
outputs the usage message summarizing command line options
then exits. Ignores \fIDEVICE\fR if given.
.TP
\fB\-H\fR, \fB\-\-hex\fR
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 "." .
.br
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 \fI\-\-inhex=FN\fR option.
.TP
\fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR
where \fIFN\fR is a file name whose contents are assumed to be ASCII
hexadecimal. If \fIDEVICE\fR is also given then \fIDEVICE\fR is ignored,
a warning is issued and the utility continues, decoding the file named
\fIFN\fR. See the "FORMAT OF FILES CONTAINING ASCII HEX" section in the
sg3_utils manpage for more information. If the \fI\-\-raw\fR option is
also given then the contents of \fIFN\fR are treated as binary.
.TP
\fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR]
output is in JSON format instead of human readable form. See sg3_utils_json
manpage or use '?' for \fIJO\fR for a summary.
.TP
\fB\-m\fR, \fB\-\-mask\fR
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".
.TP
\fB\-M\fR, \fB\-\-mlu\fR
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.
.TP
\fB\-n\fR, \fB\-\-no-inquiry\fR
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 \fIDEVICE\fR 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 \fI\-\-raw\fR option)
is given then that summary is not printed on stdout.
.TP
\fB\-O\fR, \fB\-\-old\fR
Switch to older style options. Please use as first option.
.TP
\fB\-o\fR, \fB\-\-opcode\fR=\fIOP[,SA]\fR
the \fIDEVICE\fR will be queried for the given operation code (i.e. the
\fIOP\fR value) which is the first byte of a SCSI command. Optionally, if
a \fISA\fR value is given, it will be used as that SCSI command's service
action. Note that \fIOP\fR and \fIOP,0\fR are not the same thing, as SCSI
does allow the service action to be 0 (but not in this command). \fIOP\fR
and \fISA\fR are decimal unless prefixed by "0x" or they have a
trailing "h". \fIOP\fR should be in the range 0 to 255 (0xff) inclusive.
\fISA\fR should be in the range 0 to 65535 (0xffff) inclusive. When this
option is not given then all available SCSI commands supported by the
\fIDEVICE\fR are listed.
.TP
\fB\-p\fR, \fB\-\-pdt\fR=\fIDT\fR
where \fIDT\fR is the peripheral device type. This is used together with
the \fI\-\-enumerate\fR to differentiate when a command opcode (and perhaps
service action) is shared by multiple device types.
.br
This option may also be used with the \fI\-\-no-inquiry\fR 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 \fIDEVICE\fR.
.TP
\fB\-r\fR, \fB\-\-raw\fR
output response in binary (to stdout) unless the \fI\-\-inhex=FN\fR option
is also given. In that case the input file name (\fIFN\fR) is decoded as
binary (and the output is _not_ in binary (but may be hex)).
.TP
\fB\-R\fR, \fB\-\-rctd\fR
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 "\-".
.TP
\fB\-q\fR, \fB\-\-repd\fR
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).
.TP
\fB\-s\fR, \fB\-\-sa\fR=\fISA\fR
the \fIDEVICE\fR will be queried for a command with the given service
action (i.e. the \fISA\fR value). Used in conjunction with the
\fI\-\-opcode=OP\fR option. If this option is not given, \fI\-\-opcode=OP\fR
is given and the command in question does have a service action then a value
of 0 will be assumed. \fISA\fR is decimal and expected to be in the range 0
to 65535 (0xffff) inclusive.
.TP
\fB\-t\fR, \fB\-\-tmf\fR
list supported task management functions. This is done with the SCSI REPORT
SUPPORTED TASK MANAGEMENT FUNCTIONS command.  When this option is chosen
the \fI\-\-alpha\fR, \fI\-\-opcode=OP\fR, \fI\-\-rctd\fR, \fI\-\-sa=SA\fR
and \fI\-\-unsorted\fR options are ignored.
.TP
\fB\-u\fR, \fB\-\-unsorted\fR
when all supported commands are being listed there is no requirement for
the device server (i.e. the \fIDEVICE\fR) to sort the list of commands. When
this option is given the list of supported commands is in the order given by
the \fIDEVICE\fR. When this option is not given the supported commands
are sorted numerically (first by operation code and then by service action).
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase level of verbosity. Can be used multiple times.
.TP
\fB\-V\fR, \fB\-\-version\fR
print out version string then exit.
.SH 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.
.PP
In the 2.4 series of Linux kernels the \fIDEVICE\fR 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.
.SH EXIT STATUS
The exit status of sg_opcodes is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH 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 \fI\-\-old\fR (or \fI\-O\fR) as the
first option. See the ENVIRONMENT VARIABLES section for another way to
force the use of these older command line options.
.TP
\fB\-a\fR
sort command alphabetically. Equivalent to \fI\-\-alpha\fR in main
description.
.TP
\fB\-c\fR
see the \fI\-\-compact\fR option above.
.TP
\fB\-e\fR
see the \fI\-\-enumerate\fR option above.
.TP
\fB\-H\fR
see the \fI\-\-hex\fR option above.
.TP
\fB\-m\fR
see the \fI\-\-mask\fR option above.
.TP
\fB\-n\fR
don't print a summary of the SCSI INQUIRY response on stdout.
.TP
\fB-N\fR, \fB\-\-new\fR
Switch to the newer style options.
.TP
\fB\-o\fR=\fIOP\fR
the \fIDEVICE\fR will be queried for the given operation code (i.e.
\fIOP\fR) which is the first byte of a SCSI command. \fIOP\fR 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 \fIDEVICE\fR are listed.
.TP
\fB\-p\fR=\fIDT\fR
see the \fI\-\-pdt=DT\fR option above.
.TP
\fB\-q\fR
set the read extended parameter data (REPD) bit in report TMF cdb.
Equivalent to \fI\-\-repd\fR in main description.
.TP
\fB\-R\fR
set the report command timeout descriptor (RCTD) bit in cdb. Equivalent
to \fI\-\-rctd\fR in main description.
.TP
\fB\-s\fR=\fISA\fR
the \fIDEVICE\fR will be queried for a command with the given service
action (i.e. \fISA\fR). Used in conjunction with the \fI\-o=OP\fR
option. If this option is not given, \fI\-o=OP\fR is given and the command
in question does have a service action then a value of 0 will be assumed.
\fISA\fR is hexadecimal and expected to be in the range 0 to ffff inclusive.
.TP
\fB\-t\fR
list supported task management functions. Equivalent to \fI\-\-tmf\fR in
the main description.
.TP
\fB\-u\fR
output all supported commands in the order given by \fIDEVICE\fR.
Equivalent to \fI\-\-unsorted\fR in main description.
.TP
\fB\-v\fR
increase level of verbosity. Can be used multiple times.
.TP
\fB\-V\fR
print out version string then exit.
.TP
\fB\-?\fR
output usage message. Ignore all other parameters.
.SH 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.
.PP
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:
.PP
   # sg_opcodes \-\-op=93h /dev/sdb
.PP
  Opcode=0x93
.br
  Command_name: Write same(16)
.br
  Command supported [conforming to SCSI standard]
.br
  Usage data: 93 e2 00 00 00 00 ff ff ff ff 00 00 ff ff 00 00
.PP
The next example shows the supported task management functions:
.PP
   # sg_opcodes \-\-tmf \-n /dev/sdb
.PP
Task Management Functions supported by device:
.br
    Abort task
.br
    Abort task set
.br
    Clear ACA
.br
    Clear task set
.br
    Logical unit reset
.br
    Query task
.PP
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:
.PP
   # sg_opcodes \-\-enumerate \-\-op=0x9b,0xa
.PP
  SCSI command:
.br
    Read buffer(16), read data from echo buffer
.br
.SH 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 \fI\-\-old\fR (or \fI\-O\fR) as the first command line option.
.SH AUTHOR
Written by Douglas Gilbert
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2004\-2022 Douglas Gilbert
.br
This software is distributed under the GPL version 2. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg_inq,sg3_utils_json(sg3_utils)