{ "content": [ { "type": "text", "text": "# SG_DECODE_SENSE(8) (man)\n\n**Summary:** sgdecodesense - decode SCSI sense and related data\n\n**Synopsis:** sgdecodesense [--binary=BFN] [--cdb] [--err=ES] [--file=HFN] [--help] [--hex] [--nospace]\n[--status=SS] [--verbose] [--version] [--write=WFN] [H1 H2 H3 ...]\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| -b | --binary | — | the sense data is read in binary from a file called BFN. |\n| -c | --cdb | — | treat the given string of hex arguments as bytes in a SCSI CDB and decode the command name. |\n| -e | --err | — | ES should be an \"exit status\" value between 0 and 255 that is available from the shell (i.e. the utility's execution con |\n| -f | --file | — | the sense data is read in ASCII hexadecimal from a file called HFN. The sense data should appear as a sequence of bytes |\n| -h | --help | — | output the usage message then exit. |\n| -H | --hex | — | this option is used in conjunction with --write=WFN in order to change the output written to WFN to lines of ASCII hex b |\n| -n | --nospace | — | expect ASCII hexadecimal to be a string of hexadecimal digits with no spaces between them. Bytes are decoded by taking t |\n| -s | --status | — | where SS is a SCSI status byte value, given in hexadecimal. The SCSI status byte is related to, but distinct from, sense |\n| -v | --verbose | — | increase the degree of verbosity (debug messages). |\n| -V | --version | — | output version string then exit. |\n| -w | --write | — | writes the sense data out to a file called WFN. If necessary WFN is created. If WFN exists then it is truncated prior to |\n\n## Examples\n\n- `Sense data is often printed out in kernel logs and sometimes on the command line when verbose`\n- `or debug flags are given. It will be at least 8 bytes long, often 18 bytes long but may be`\n- `longer. A sense data string might look like this:`\n- `f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00`\n- `00 00`\n- `Cut and paste it after the sgdecodesense command:`\n- `sgdecodesense f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00 00 00`\n- `and for this sense data the output should look like this:`\n- `Fixed format, current; Sense key: Medium Error`\n- `Additional sense: Unrecovered read error`\n- `Info fld=0x1234 [4660]`\n- `For a medium error the Info field is the logical block address (LBA) of the lowest numbered`\n- `block that the associated SCSI command was not able to read (verify or write).`\n\n## See Also\n\n- sgraw(sg3utils)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (3 lines)\n- **DESCRIPTION** (27 lines)\n- **OPTIONS** (2 lines) — 11 subsections\n - -b --binary (2 lines)\n - -c --cdb (3 lines)\n - -e --err (8 lines)\n - -f --file (6 lines)\n - -h --help (2 lines)\n - -H --hex (4 lines)\n - -n --nospace (8 lines)\n - -s --status (3 lines)\n - -v --verbose (2 lines)\n - -V --version (2 lines)\n - -w --write (7 lines)\n- **NOTES** (7 lines)\n- **EXAMPLES** (20 lines)\n- **EXIT STATUS** (3 lines)\n- **AUTHORS** (2 lines)\n- **REPORTING BUGS** (2 lines)\n- **COPYRIGHT** (4 lines)\n- **SEE ALSO** (5 lines)\n\n## Full Content\n\n### NAME\n\nsgdecodesense - decode SCSI sense and related data\n\n### SYNOPSIS\n\nsgdecodesense [--binary=BFN] [--cdb] [--err=ES] [--file=HFN] [--help] [--hex] [--nospace]\n[--status=SS] [--verbose] [--version] [--write=WFN] [H1 H2 H3 ...]\n\n### DESCRIPTION\n\nThis utility takes SCSI sense data in binary or as a sequence of ASCII hexadecimal bytes and\ndecodes it. The primary reference for the decoding is SPC-4 ANSI INCITS 513-2015 and the most\nrecent draft SPC-5 revision 19 which can be found at http://www.t10.org and other locations\non the internet.\n\nSCSI sense data is often found in kernel log files as a result of something going wrong or\nmay be an informative warning. It is often shown as a sequence of hexadecimal bytes, starting\nwith 70, 71, 72, 73, f0 or f1. Sense data could be up to 252 bytes long but typically is\nmuch shorter than that, 18 bytes long is often seen and is usually associated with the older\n\"fixed\" format sense data.\n\nThe sense data can be provided on the command line or in a file. If given on the command line\nthe sense data should be a sequence of hexadecimal bytes separated by space. Alternatively a\nfile can be given with the contents in binary or ASCII hexadecimal bytes. The latter form can\ncontain several lines each with none, one or more ASCII hexadecimal bytes separated by space\n(comma or tab). The hash symbol may appear and it and the rest of the line is ignored making\nit useful for comments.\n\nIf the --cdb option is given then rather than viewing the given hex arguments as sense data,\nit is viewed as a SCSI command descriptor block (CDB). In this case the command name is\nprinted out. That name is based on the first hex byte given (know as the opcode) and option‐\nally on another field called the \"service action\".\n\nAnother alternate action is when the --err=ES is given. ES is assumed to be an \"exit status\"\nvalue between 0 and 255 from one of the utilities in this package. A descriptive string is\nprinted. Other options are ignored apart from --verbose.\n\n### OPTIONS\n\nArguments to long options are mandatory for short options as well.\n\n#### -b --binary\n\nthe sense data is read in binary from a file called BFN.\n\n#### -c --cdb\n\ntreat the given string of hex arguments as bytes in a SCSI CDB and decode the command\nname.\n\n#### -e --err\n\nES should be an \"exit status\" value between 0 and 255 that is available from the shell\n(i.e. the utility's execution context) after the utility is finished. By default an\nindicative error message is printed to stdout; and if the --verbose option is given\nonce (or an odd number of times) then the message is instead printed to stderr. If\n--verbose is given two or more times a longer form of the message is output. In all\ncases the message is less than 128 characters long with one trailing line feed. All\nother command line options and arguments are ignored.\n\n#### -f --file\n\nthe sense data is read in ASCII hexadecimal from a file called HFN. The sense data\nshould appear as a sequence of bytes separated by space, comma, tab or newline. Every‐\nthing from and including a hash symbol to the end of that line is ignored. If\n--nospace is set then no separator is required between the ASCII hexadecimal digits in\nHFN with bytes decoded from pairs of ASCII hexadecimal digits.\n\n#### -h --help\n\noutput the usage message then exit.\n\n#### -H --hex\n\nthis option is used in conjunction with --write=WFN in order to change the output\nwritten to WFN to lines of ASCII hex bytes suitable for a C language compiler. Each\nline contains up to 16 bytes (e.g. a line starting with \"0x3b,0x07,0x00,0xff\").\n\n#### -n --nospace\n\nexpect ASCII hexadecimal to be a string of hexadecimal digits with no spaces between\nthem. Bytes are decoded by taking two hexadecimal digits at a time, so an even number\nof digits is expected. The string of hexadecimal digits may be on the command line\n(replacing \"H1 H2 H3\") or spread across multiple lines the HFN given to --file=. On\nthe command line, spaces (or other whitespace characters) between sequences of hexa‐\ndecimal digits are ignored; the maximum command line hex string is 1023 characters\nlong.\n\n#### -s --status\n\nwhere SS is a SCSI status byte value, given in hexadecimal. The SCSI status byte is\nrelated to, but distinct from, sense data.\n\n#### -v --verbose\n\nincrease the degree of verbosity (debug messages).\n\n#### -V --version\n\noutput version string then exit.\n\n#### -w --write\n\nwrites the sense data out to a file called WFN. If necessary WFN is created. If WFN\nexists then it is truncated prior to writing the sense data to it. If the --hex option\nis also given then ASCII hex is written to WFN (see the --hex option description);\notherwise binary is written to WFN. This option is a convenience and may be helpful in\nconverting the ASCII hexadecimal representation of sense data (or anything else) into\nthe equivalent binary or a compilable ASCII hex form.\n\n### NOTES\n\nUnlike most utilities in this package, this utility does not access a SCSI device (logical\nunit). This utility accesses a library associated with this package. Amongst other things the\nlibrary decodes SCSI sense data.\n\nThe sgraw utility takes a ASCII hexadecimal sequence representing a SCSI CDB. When sgraw is\ngiven the '-vvv' option, it will attempt to decode the CDB name.\n\n### EXAMPLES\n\nSense data is often printed out in kernel logs and sometimes on the command line when verbose\nor debug flags are given. It will be at least 8 bytes long, often 18 bytes long but may be\nlonger. A sense data string might look like this:\n\nf0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00\n00 00\n\nCut and paste it after the sgdecodesense command:\n\nsgdecodesense f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00 00 00\n\nand for this sense data the output should look like this:\n\nFixed format, current; Sense key: Medium Error\nAdditional sense: Unrecovered read error\nInfo fld=0x1234 [4660]\n\nFor a medium error the Info field is the logical block address (LBA) of the lowest numbered\nblock that the associated SCSI command was not able to read (verify or write).\n\n### EXIT STATUS\n\nThe exit status of sgdecodesense is 0 when it is successful. Otherwise see the sg3utils(8)\nman page.\n\n### AUTHORS\n\nWritten by Douglas Gilbert.\n\n### REPORTING BUGS\n\nReport bugs to .\n\n### COPYRIGHT\n\nCopyright © 2010-2019 Douglas Gilbert\nThis software is distributed under a FreeBSD license. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\n### SEE ALSO\n\nsgrequests,sgraw(sg3utils)\n\n\n\nsg3utils-1.45 June 2019 SGDECODESENSE(8)\n\n" } ], "structuredContent": { "command": "SG_DECODE_SENSE", "section": "8", "mode": "man", "summary": "sgdecodesense - decode SCSI sense and related data", "synopsis": "sgdecodesense [--binary=BFN] [--cdb] [--err=ES] [--file=HFN] [--help] [--hex] [--nospace]\n[--status=SS] [--verbose] [--version] [--write=WFN] [H1 H2 H3 ...]", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "-b", "long": "--binary", "arg": null, "description": "the sense data is read in binary from a file called BFN." }, { "flag": "-c", "long": "--cdb", "arg": null, "description": "treat the given string of hex arguments as bytes in a SCSI CDB and decode the command name." }, { "flag": "-e", "long": "--err", "arg": null, "description": "ES should be an \"exit status\" value between 0 and 255 that is available from the shell (i.e. the utility's execution context) after the utility is finished. By default an indicative error message is printed to stdout; and if the --verbose option is given once (or an odd number of times) then the message is instead printed to stderr. If --verbose is given two or more times a longer form of the message is output. In all cases the message is less than 128 characters long with one trailing line feed. All other command line options and arguments are ignored." }, { "flag": "-f", "long": "--file", "arg": null, "description": "the sense data is read in ASCII hexadecimal from a file called HFN. The sense data should appear as a sequence of bytes separated by space, comma, tab or newline. Every‐ thing from and including a hash symbol to the end of that line is ignored. If --nospace is set then no separator is required between the ASCII hexadecimal digits in HFN with bytes decoded from pairs of ASCII hexadecimal digits." }, { "flag": "-h", "long": "--help", "arg": null, "description": "output the usage message then exit." }, { "flag": "-H", "long": "--hex", "arg": null, "description": "this option is used in conjunction with --write=WFN in order to change the output written to WFN to lines of ASCII hex bytes suitable for a C language compiler. Each line contains up to 16 bytes (e.g. a line starting with \"0x3b,0x07,0x00,0xff\")." }, { "flag": "-n", "long": "--nospace", "arg": null, "description": "expect ASCII hexadecimal to be a string of hexadecimal digits with no spaces between them. Bytes are decoded by taking two hexadecimal digits at a time, so an even number of digits is expected. The string of hexadecimal digits may be on the command line (replacing \"H1 H2 H3\") or spread across multiple lines the HFN given to --file=. On the command line, spaces (or other whitespace characters) between sequences of hexa‐ decimal digits are ignored; the maximum command line hex string is 1023 characters long." }, { "flag": "-s", "long": "--status", "arg": null, "description": "where SS is a SCSI status byte value, given in hexadecimal. The SCSI status byte is related to, but distinct from, sense data." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "increase the degree of verbosity (debug messages)." }, { "flag": "-V", "long": "--version", "arg": null, "description": "output version string then exit." }, { "flag": "-w", "long": "--write", "arg": null, "description": "writes the sense data out to a file called WFN. If necessary WFN is created. If WFN exists then it is truncated prior to writing the sense data to it. If the --hex option is also given then ASCII hex is written to WFN (see the --hex option description); otherwise binary is written to WFN. This option is a convenience and may be helpful in converting the ASCII hexadecimal representation of sense data (or anything else) into the equivalent binary or a compilable ASCII hex form." } ], "examples": [ "Sense data is often printed out in kernel logs and sometimes on the command line when verbose", "or debug flags are given. It will be at least 8 bytes long, often 18 bytes long but may be", "longer. A sense data string might look like this:", "f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00", "00 00", "Cut and paste it after the sgdecodesense command:", "sgdecodesense f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00 00 00", "and for this sense data the output should look like this:", "Fixed format, current; Sense key: Medium Error", "Additional sense: Unrecovered read error", "Info fld=0x1234 [4660]", "For a medium error the Info field is the logical block address (LBA) of the lowest numbered", "block that the associated SCSI command was not able to read (verify or write)." ], "see_also": [ { "name": "sgraw", "section": "sg3utils", "url": "https://www.chedong.com/phpMan.php/man/sgraw/sg3utils/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 3, "subsections": [] }, { "name": "DESCRIPTION", "lines": 27, "subsections": [] }, { "name": "OPTIONS", "lines": 2, "subsections": [ { "name": "-b --binary", "lines": 2, "flag": "-b", "long": "--binary" }, { "name": "-c --cdb", "lines": 3, "flag": "-c", "long": "--cdb" }, { "name": "-e --err", "lines": 8, "flag": "-e", "long": "--err" }, { "name": "-f --file", "lines": 6, "flag": "-f", "long": "--file" }, { "name": "-h --help", "lines": 2, "flag": "-h", "long": "--help" }, { "name": "-H --hex", "lines": 4, "flag": "-H", "long": "--hex" }, { "name": "-n --nospace", "lines": 8, "flag": "-n", "long": "--nospace" }, { "name": "-s --status", "lines": 3, "flag": "-s", "long": "--status" }, { "name": "-v --verbose", "lines": 2, "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "lines": 2, "flag": "-V", "long": "--version" }, { "name": "-w --write", "lines": 7, "flag": "-w", "long": "--write" } ] }, { "name": "NOTES", "lines": 7, "subsections": [] }, { "name": "EXAMPLES", "lines": 20, "subsections": [] }, { "name": "EXIT STATUS", "lines": 3, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] } ] } }