.TH SG3_UTILS "8" "June 2022" "sg3_utils\-1.48" SG3_UTILS
.SH NAME
sg3_utils \- JSON output for some utilities
.SH SYNOPSIS
.B sg_*
\fI\-\-json[=JO]\fR [\fIOTHER_OPTIONS\fR] \fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
sg3_utils is a package of utilities that send SCSI commands to the given
\fIDEVICE\fR 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, human-readable output. The default remains
human-readable output.
.PP
JSON is an open standard file format that can be used for data exchange
between systems. 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" convention
for JSON object names: all in lower case with separate words joined with
a single underscore (e.g. "starting_lba"). 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.
.PP
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.
.PP
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).
.PP
This manpage discusses the \fI\-\-json\fR option which may or may not itself
have an optional argument. In its shorter form it may either be \fI\-j\fR or
\fI\-J\fR (lower case preferred if not already in use). The shorter form may
also take an argument but there must not be a space (or whitespace) between
\fI\-j\fR and that argument.  
.SH ENVIRONMENT VARIABLES
The SG3_UTILS_JSON_OPTS environment variable
yyyyyyyy
 is explained in the previous
section. It is only for backward compatibility of the command line options
for older utilities.
.PP
The SG3_UTILS_DSENSE environment variable may be set to a number. It is
only used by the embedded SNTL within the library used by the utilities in
this library. SNTL is a SCSI to NVMe Translation Layer. This environment
variable defaults to 0 which will lead to any utility that issues a SCSI
command that is translated to a NVMe command (by the embedded SNTL) that
fails at the NVMe dvice, to return SCSI sense in 'fixed' format. If this
variable is non\-zero then then the returned SCSI sense will be in 'descriptor'
format.
.PP
Several utilities have their own environment variable setting (e.g.
sg_persist has SG_PERSIST_IN_RDONLY). See individual utility man pages
for more information.
.PP
There is a Linux specific environment variable called SG3_UTILS_LINUX_NANO
that if defined and the sg driver in the system is 4.0.30 or later, will
show command durations in nanoseconds rather than the default milliseconds.
Command durations are typically only shown if \-\-verbose is used 3 or more
times. Due to an interface problem (a 32 bit integer that should be 64 bits
with the benefit of hindsight) the maximum duration that can be represented
in nanoseconds is about 4.2 seconds. If longer durations may occur then
don't define this environment variable (or undefine it).
.SH OPTIONS
Since the argument to \fI\-\-json[=JO]\fR is optional, in the shorter form
there can be no space(s) between the option and its argument.
.TP
\fB\-j[JO]\fR, \fB\-\-json\fR\fI[=JO]\fR
yyyyyyyyy
utilities that can cause lots of user data to be lost or overwritten
sometimes have a \fI\-\-dry\-run\fR option. Device modifying actions are
typically bypassed (or skipped) to implement a policy of "do no harm".
This allows complex command line invocations to be tested before the
action required (e.g. format a disk) is performed. The \fI\-\-dry\-run\fR
option has become a common feature of many command line utilities (e.g.
the Unix 'patch' command), not just those from this package.
.br
Note that most hyphenated option names in this package also can be given
with an underscore rather than a hyphen (e.g.  \fI\-\-dry_run\fR).
.SH WEB SITE
There is a web page discussing this package at
https://sg.danny.cz/sg/sg3_utils.html . The device naming used by this
package on various operating systems is discussed at:
https://sg.danny.cz/sg/device_name.html . There is a git code mirror at
https://github.com/hreinecke/sg3_utils . The principle code repository
uses subversion and is on the author's equipment. The author keeps track
of this via the subversion revision number which is an ascending integer
(currently at 922 for this package). The github mirror gets updated
periodically from the author's repository. Depending on the time of
update, the above Downloads section at sg.danny.cz may be more up to
date than the github mirror.
.SH AUTHORS
Written by Douglas Gilbert. Some utilities have been contributed, see the
CREDITS file and individual source files (in the 'src' directory).
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2022 Douglas Gilbert
.br
Some utilities are distributed under a GPL version 2 license while
others, usually more recent ones, are under a FreeBSD license. The files
that are common to almost all utilities and thus contain the most reusable
code, namely sg_lib.[hc], sg_cmds_basic.[hc] and sg_cmds_extra.[hc] are
under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg3_utils(sg3_utils), smartctl(smartmontools)