SG3_UTILS_JSON(8) | SG3_UTILS | SG3_UTILS_JSON(8) |
sg3_utils_json - JSON output for some sg3_utils utilities
sg_* --json[=JO] [--js-file=JFN] [OTHER_OPTIONS] [DEVICE]
sg3_utils is a package of utilities that send SCSI commands to the given DEVICE via a SCSI pass through interface provided by the host operating system. Some utilities, mainly those decoding structured data returned by SCSI commands (e.g. sg_vpd) can optionally provide JSON output, rather than simple, plain text output. The default remains plain text output.
JavaScript Object Notation (JSON) is an open standard file format that can be used for data exchange between programs including across a network. See https://en.wikipedia.org/wiki/JSON . JSON comes in many flavours and this one uses the json-builder C implementation found at https://github.com/json-parser/json-builder which implements four simple JSON data types: string, integer, boolean and null. Its other data types are JSON object and JSON array.
This project uses the 'snake_case' convention for JSON object names: all in lower case letters or numerals with individual words joined with a single underscore (e.g. "starting_lba"). There should be no leading or trailing underscore characters. The json-builder library uses the SPDX-License-Identifier: BSD-2-Clause which is the same license as the bulk of the utilities in the sg3_utils package.
The json-builder library is relatively lightweight (700 lines of C code) and is 'hidden' fully within the sg3_utils library so that its function interface and data types are not available (directly) to the utilities in the sg3_utils package. That is why the json-builder interface (a file named sg_json_builder.h) is in the lib directory and not in the include directory. As presented on github, json-builder shares some header files with its companion json-parser. The author has modified the json-builder header to include what is needed from the json-parser header so that only the builder and not the parser are built. The parser could be added later, but currently there seems to be no need for it.
The user interface to JSON functionality in the sg3_utils package is heavily based on what has been done by Christian Franke and others in smartctl, a utility in the smartmontools package for getting S.M.A.R.T. information from disks (and other storage devices).
This manpage discusses the --json[=JO] and --js-file=JFN command line options. Notice that the argument to --json is itself optional. In its shorter form the --json option may either be -j or -J (lower case preferred if not already in use). The shorter form may also take an argument but an "=" must precede the JO argument with no spaces either side of the "=".
Some care has been taken with quotes in this manpage. Double quotes are used around JSON object names, single quotes are used for all other purposes.
The SG3_UTILS_JSON_OPTS environment variable allows the user to override the default values of the JO settings. Those settings can again be overridden by the command line --json[=JO] option. If the string associated with SG3_UTILS_JSON_OPTS cannot be parsed this error message is sent to stderr: 'error parsing SG3_UTILS_JSON_OPTS environment variable, ignore'.
Since the argument to --json[=JO] is optional, in the shorter form there can be no space(s) between the option and its argument.
Each JO string is made up of zero or more of the following JSON control characters.
The default remains the same for all utilities that support the --json option, namely the decoded information is sent to stdout in plain text form. Errors are reported to stderr and may cause the early termination of a utility (e.g. command line option syntax error).
When the --json option is given and no errors are detected, then only JSON is normally sent to stdout. As the SCSI response is parsed, a JSON representation is built as a tree in memory. After all other actions (perhaps apart from the final exit status report) that JSON tree is 'dumped' to stdout. This means if there is any non-JSON output sent to stdout that it will appear _before_ the JSON output.
If the 'o' control character is in the JO argument to the
--json option, then the former plain text output is placed in a JSON
array named "plain_text_output" within a JSON object named
"utility_invoked".
Each line of the former 'plain text' output is placed in its own element of
the JSON array.
A JSON tree is built in memory as the utility parses the data returned from the SCSI device (e.g. sg_vpd parsing a VPD page returned from a SCSI INQUIRY command). SCSI 'list's become JSON named arrays (e.g. in the Device Identification VPD page there is a 'Designation descriptor list' that becomes a JSON array named "designation_descriptor_list").
At the completion of the utility that JSON tree is 'measured' taking into account the form of output (i.e. pretty-printed, single line or packed single line). For the pretty-printed JSON output, the size of each indentation in spaces is also given (i.e. the tab width). The JSON is then output to a single C string, then sent to stdout. If a NULL character (ASCII zero and C string terminator) somehow finds its way into a field that should (according to the spec) be space padded, then the JSON output may appear truncated.
Note that this JSON processing means that if a utility is aborted for whatever reason then no JSON output will appear. With the normal, plain text output processing, some output may appear before the utility aborts in such bad situations.
In general, the JSON generated by this package outputs 1 bit SCSI fields as the integer value 0 (for false) and 1 (for true). This follows the SCSI convention which predates the common use of boolean. Also SCSI reserved fields are output as the integer value 0. Extensions to SCSI commands and associated data descriptors typically use parts of commands or data descriptors that were previously reserved.
As stated above, the default output is in plain text form using 7 bit ASCII. The --json[=JO] option is designed to be an alternative to that plain text form. There are other alternative output formats such as the response output as a hexadecimal sequence of bytes or in 'raw' binary output; both of those take precedence over the --json[=JO] option. Other specialized output format (e.g. 'sg_inq --export') will usually take precedence over JSON output.
When the --raw option is used together with the --inhex=FN option only the data input to the utility is interpreted as binary. So the output format defaults to plain text form and thus can be changed to JSON if the --json[=JO] option is also used.
There is typically only one form of JSON output so options like --brief and --quiet are ignored in the JSON output. In some cases (i.e 'sg_inq --descriptors') the JSON output is expanded.
No attempts have been made to translate errors into JSON form, apart from the final "exit_status" JSON object where a value of 0 means 'no errors'. Exit status values indicating a problem range from 1 to 255.
The sg_decode_sense utility will parse SCSI sense data into JSON form if requested. So if another utility is failing with a sense data report (most often seen when the --verbose option is used). That sense data (in hex bytes) could be cut-and-pasted onto the command line following 'sg_decode_sense -j ' which should then render that sense data in JSON.
Otherwise, when a error is detected while JSON output is selected, the error message is sent to stderr in plain text form. Typically once an error is detected the utility will exit, first dumping the JSON in-memory tree as discussed above and a non-zero exit status will be set. The JSON output will be well formed but missing any fields or list elements following the point that the error was detected.
The summary is that when JSON output is selected and an error occurs each utility will process the error the same way as it would if JSON output had not been selected. In most cases error messages, in plain text form, are sent to stderr.
Written by Douglas Gilbert. Some utilities have been contributed, see the CREDITS file and individual source files (in the 'src' directory).
Report bugs to <dgilbert at interlog dot com>.
Copyright © 2022-2023 Douglas Gilbert
This software is distributed under the GPL version 2 or the BSD-2-Clause
license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.
sg3_utils(sg3_utils), smartctl(smartmontools)
August 2023 | sg3_utils-1.48 |