Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

sg_logs (8)

Name

sg_logs - access log pages with SCSI LOG SENSE command

Synopsis

sg_logs   [--All]  [--all]  [--brief]  [--filter=FL]  [--hex]  [--list]
[--maxlen=LEN] [--name] [--no_inq]  [--page=PG]  [--paramp=PP]  [--pcb]
[--ppc]   [--pdt=DT]   [--raw]   [--readonly]   [--sp]  [--temperature]
[--transport] [--vendor=VP] [--verbose] DEVICE

sg_logs [--brief] [--filter=FL]  [--hex]  --in=FN  [--name]  [--pdt=DT]
[--raw] [--vendor=VP]

sg_logs [--control=PC] [--in=FN] [--page=PG] [--raw] [--reset] --select
[--sp] [--verbose] DEVICE

sg_logs [--enumerate] [--filter=FL] [--help] [--vendor=VP] [--version]

sg_logs [-a] [-A] [-b] [-D=DT] [-c=PC] [-e] [-f=FL] [-h]  [-H]  [-i=FN]
[-l] [-L] [-m=LEN] [-M=VP] [-n] [-p=PG] [-paramp=PP] [-pcb] [-ppc] [-r]
[-R] [-select] [-sp] [-t] [-T] [-v] [-V] [-?]  [-x] DEVICE

Description

SG_LOGS(8)                         SG3_UTILS                        SG_LOGS(8)



NAME
       sg_logs - access log pages with SCSI LOG SENSE command

SYNOPSIS
       sg_logs   [--All]  [--all]  [--brief]  [--filter=FL]  [--hex]  [--list]
       [--maxlen=LEN] [--name] [--no_inq]  [--page=PG]  [--paramp=PP]  [--pcb]
       [--ppc]   [--pdt=DT]   [--raw]   [--readonly]   [--sp]  [--temperature]
       [--transport] [--vendor=VP] [--verbose] DEVICE

       sg_logs [--brief] [--filter=FL]  [--hex]  --in=FN  [--name]  [--pdt=DT]
       [--raw] [--vendor=VP]

       sg_logs [--control=PC] [--in=FN] [--page=PG] [--raw] [--reset] --select
       [--sp] [--verbose] DEVICE

       sg_logs [--enumerate] [--filter=FL] [--help] [--vendor=VP] [--version]

       sg_logs [-a] [-A] [-b] [-D=DT] [-c=PC] [-e] [-f=FL] [-h]  [-H]  [-i=FN]
       [-l] [-L] [-m=LEN] [-M=VP] [-n] [-p=PG] [-paramp=PP] [-pcb] [-ppc] [-r]
       [-R] [-select] [-sp] [-t] [-T] [-v] [-V] [-?]  [-x] DEVICE

DESCRIPTION
       This utility sends a SCSI LOG SENSE command to the DEVICE and then out-
       puts  the  response.  The  LOG SENSE command is used to fetch log pages
       which, if known, are  decoded  by  default.  When  the  --reset  and/or
       --select  option  is  given then a SCSI LOG SELECT command is issued to
       the DEVICE. Alternatively one or more log page responses can  be  in  a
       file  read  using  the --in=FN option; in this case those responses are
       decoded and the DEVICE argument, if given, is ignored.

       In SPC-4 revision 5 a subpage code was introduced to both the LOG SENSE
       and  LOG  SELECT command. At the same time a page code field was intro-
       duced to the to the LOG SELECT command. The log subpage code can  range
       from  0  to  255  (0xff)  inclusive.  The subpage code value 255 can be
       thought of as a wildcard.

       The SYNOPSIS section above is divided into five forms. The  first  form
       shows  the  options that can be used to send a LOG SENSE command to the
       DEVICE and decode its response. The second form  fetches  data  from  a
       file  (named  FN)  and  decodes  it as if it were a response from a LOG
       SENSE command. The third form shows the options that  can  be  used  to
       send  a  LOG  SELECT command. The fourth form groups various management
       options.  The last form shows the older, deprecated command line inter-
       face which is maintained for backward compatibility.

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.

       -A, --All
              fetch and decode all the log pages and subpages supported by the
              DEVICE.  This requires a two stage process: first the "supported
              log pages and subpages" log page is fetched, then for each entry
              in its response, the corresponding  log  page  (or  subpage)  is
              fetched  and  displayed.  Note  that there are many SCSI devices
              that do not support LOG  SENSE  subpages  and  respond  to  this
              option with an illegal request sense key (or ignored the subpage
              field).

       -a, --all
              outputs all the log pages supported by the DEVICE. This requires
              a two stage process: first the "supported log pages" log page is
              fetched, then for each entry in its response, the  corresponding
              log  page is fetched and displayed. When used twice (e.g. '-aa')
              all log pages and subpages are fetched.

       -b, --brief
              shorten the amount of output for some log pages. For example the
              Tape  Alert log page only outputs parameters whose flags are set
              when --brief is given.

       -c, --control=PC
              accepts 0, 1, 2 or 3 for the PC argument:
                0 : current threshold values
                1 : current cumulative values
                2 : default threshold values
                3 : default cumulative values
              The default value is 1 (i.e. current cumulative values).

       -e, --enumerate
              this option is used to output information held in this utility's
              internal  tables  about  known  log  pages including their name,
              acronym and fields. If given, the DEVICE  argument  is  ignored.
              When  given  once (e.g. '-e') all known pages are listed, sorted
              in ascending alphabetical acronym order.
              When given twice, vendor pages are excluded.  When  given  three
              times,  all  known pages are listed, sorted in ascending numeric
              order listed; when given four times, vendor pages  are  excluded
              from the numeric order.
              The  --filter=FL  and --verbose options reduce the output of the
              enumeration.

       -f, --filter=FL
              FL is either a parameter code when DEVICE is given, or a periph-
              eral device type (pdt) (or other) if --enumerate is given.
              In  the  parameter  code  case FL is a value between 0 and 65535
              (0xffff) and only the parameter section matching  that  code  is
              output. If the --hex option is given the log parameter is output
              in hexadecimal rather than decoding it. If the --hex  option  is
              used  twice  then  the  leading  address  on each line of hex is
              removed. If the --raw option is given then the log parameter  is
              output in binary. Most log pages contain one or more log parame-
              ters. Examples of those that don't follow  that  convention  are
              those pages that list supported log pages (and subpages).
              In  the  --enumerate  case, when FL >= zero it is taken as a pdt
              value and only log pages associated with that pdt  plus  generic
              pages  listed in SPC are enumerated. If FL is -1 then the filter
              does nothing which is the same as not giving this  option;  when
              FL  is  -2 then only generic pages listed in SPC are enumerated.
              If FL is -10 then only generic direct access  like  (e.g.  disk)
              pages  are  enumerated. If FL is -11 then only generic tape like
              pages (e.g. includes ADC) are enumerated.

       -h, --help
              print out the usage message then exit.

       -H, --hex
              The default action is to decode known log page numbers (and sub-
              page  numbers)  into  text.  When  this option is used once, the
              response is output in hexadecimal. When used twice, each line of
              hex has the ASCII equivalent shown to the right. When used three
              times, the hex has no leading address nor trailing ASCII  making
              it  suitable  to be placed in a file (or piped). That file might
              later be used by another invocation using the --in=FN option.

       -i, --in=FN
              This option may be used in two different contexts. One  is  with
              the  --select  to send a LOG SELECT command to the given DEVICE;
              see the LOG SELECT section below.
              The other context is with no DEVICE argument given in which case
              the  contents  of FN are decoded as if it were the response of a
              LOG SENSE command (i.e. a log page). For decoding the  page  and
              subpage  numbers  are  taken from FN while the peripheral device
              type is either generic (i.e. from SPC) or  the  value  given  by
              --pdt=DT.
              FN  is  treated as a file name (or '-' for stdin) which contains
              ASCII hexadecimal or binary representing a log page.  The  hexa-
              decimal  should be arranged as 1 or 2 digits representing a byte
              each of which is whitespace or comma  separated.  Anything  from
              and  including a hash mark to the end of line is ignored. If the
              --raw option is also given then FN is treated as binary.

       -l, --list
              lists the names of  all  logs  sense  pages  supported  by  this
              device.  This  is  done by reading the "supported log pages" log
              page. When used twice (e.g. '-ll') lists the names of  all  logs
              sense  pages  and  subpages  supported by this device, excluding
              pages whose subpage number is 0xff (apart from  page  0x0,0xff).
              When  used  three  times  then  all supported pages and subpages
              reported by the device are list. So the page/subpage  names  and
              not  thrie content is shown with this option. There is a list of
              common log page codes below.

       -m, --maxlen=LEN
              sets the "allocation length" field in the LOG SENSE cdb. The  is
              the  maximum  length in bytes that the response will be. Without
              this option (or LEN equal to 0) this utility first fetches the 4
              byte  response  then  does a second access with the length indi-
              cated in the first (4 byte) response. Negative values and 1  for
              LEN   are  not  accepted.  LEN  cannot  exceed  65535  (0xffff).
              Responses can be quite large (e.g. the background  scan  results
              log  page)  and  this  option can be used to limit the amount of
              information returned.

       -n, --name
              decode some log pages into 'name=value' entries, one  per  line.
              The  name contains no space and may be abbreviated and the value
              is decimal unless prefixed by  '0x'.  Nesting  is  indicated  by
              leading  spaces.  This  form  is  meant to be relatively easy to
              parse.

       -x, --no_inq
              suppresses the output of information obtained  from  an  initial
              call  to  the  INQUIRY  command  for  the standard response. The
              default (assuming some other options that suppress  this  output
              are  also  not given) is to output several device identification
              strings.
              If this option is given twice (or more) then no INQUIRY  command
              is sent hence there will be no device identification string out-
              put either. Also the peripheral device type (PDT) field will not
              be  obtained  so  this utility will not be able to differentiate
              between some log pages that are device dependent. It will assume
              a PDT of 0 (i.e. a disk).

       -O, --old
              Switch to older style options. Please use as first option.

       -p, --page=PG
              log  page name/number to access. PG is either an acronym, a page
              number, or a page, subpage number pair. Available  acronyms  can
              be  listed  with the --enumerate option. Page (0 to 63) and sub-
              page (0 to 255) numbers are comma separated.  They  are  decimal
              unless  a  hexadecimal indication is given. A hexadecimal number
              can be specified by a leading "0x" or a trailing "h".
              A few acronyms specify a range of subpage values in  which  case
              the  acronym  may  be followed by a comma then a subpage number.
              This method can also be used to fetch the Supported subpages log
              page (e.g. --page=temp,0xff).

       -P, --paramp=PP
              PP  is  the  parameter pointer value to place in a field of that
              name in the LOG SENSE cdb. A decimal number in the  range  0  to
              65535 (0xffff) is expected. When a value greater than 0 is given
              the --ppc option should be selected. The default value is 0.

       -q, --pcb
              show Parameter Control Byte settings  (only  relevant  when  log
              parameters being output in ASCII).

       -Q, --ppc
              sets  the  Parameter  Pointer Control (PPC) bit in the LOG SENSE
              cdb. Default is 0 (i.e. cleared). This bit was made obsolete  in
              SPC-4 revision 18.

       -D, --pdt=DT
              DT  is  the  peripheral  device type that is used when it is not
              available from the DEVICE. There are two  main  cases  of  this:
              with  the  --pdt=DT  without  a DEVICE and when --no_inq is used
              with a DEVICE.

       -r, --raw
              output the response in binary  to  stdout.  Error  messages  and
              warnings are output to stderr.
              This  option  may  also  be given together with --in=FN in which
              case the contents of FN are interpreted as binary data (and  the
              response is decoded as normal, not dumped as binary).

       -R, --readonly
              open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
              The default action is to try and open DEVICE read-write then  if
              that  fails  try  to  open  again with read-only. However when a
              read-write open succeeds there may still be unwanted actions  on
              the  close  (e.g.  some  OSes try to do a SYNCHRONIZE CACHE com-
              mand). So this option forces a read-only open on DEVICE  and  if
              it  fails,  this  utility  will  exit.  Note  that  options like
              --select most likely need a read-write open.

       -R, --reset
              use SCSI LOG SELECT command (with the PCR bit set) to reset  the
              all log pages (or the given page). Exactly what is reset depends
              on the accompanying SP bit (i.e. --sp option which  defaults  to
              0) and the PC ("page control") value (which defaults to 1). Sup-
              plying this option implies the --select  option  as  well.  This
              option  seems  to clear error counter log pages but leaves pages
              like self-test results, start-stop cycle counter and temperature
              log  pages  unaffected. This option may be required to clear log
              pages if a counter reaches its maximum value since the log  page
              in which the counter is found will remain "stuck" at its maximum
              value until some user interaction  (e.g.  calling  sg_logs  with
              this option).

       -S, --select
              use  a LOG SELECT command. The default action (i.e. when neither
              this option nor --reset is given) is to do a LOG SENSE  command.
              See the LOG SELECT section.

       -s, --sp
              sets  the  Saving  Parameters  (SP)  bit.  Default  is  0  (i.e.
              cleared). When set this instructs the device to store  the  cur-
              rent log page parameters (as indicated by the DS and TSD parame-
              ter codes) in some non-volatile location.  Hence the log parame-
              ters will be preserved across power cycles. This option is typi-
              cally not needed, especially if the GLTSD flag is clear  in  the
              control  mode  page as this instructs the device to periodically
              save all saveable log parameters to non-volatile locations.

       -t, --temperature
              outputs the temperature. First looks in the temperature log page
              and  if that is not available tries the Informational Exceptions
              log page which may also have the current temperature (especially
              on older disks).

       -T, --transport
              outputs  the  transport  ('Protocol  specific  port')  log page.
              Equivalent to setting '--page=18h'.

       -M, --vendor=VP
              where VP is a vendor/manufacturer (e.g. "sea"  for  Seagate)  or
              product  (group) acronym (e.g. "lto5" for the 5th generation LTO
              (tape) consortium). Either the whole log page is vendor specific
              (e.g.  page  numbers  0x30 to 0x3f) or part of a T10 defined log
              page is vendor specific.  For example  SPC-5  defines  parameter
              code  0x0  of  page 0x2f (the Informational Exceptions log page)
              and states that the  remaining  parameter  codes  (i.e.  0x1  to
              0xffff)  are  vendor specific. Using a VP of "xxx" will list the
              available acronyms.
              If this option is used with --page=PG and PG is an acronym  then
              this option is ignored. If PG is a number (e.g. 0xc0) then VP is
              used to choose the which vendor specific page (e.g. sharing page
              number 0xc0) to decode.

       -v, --verbose
              increase  level of verbosity. When used with --enumerate, in the
              list of known log page names,  those  that  have  no  associated
              decode logic are followed by "[hex only]".

       -V, --version
              print out version string then exit.

LOG SELECT
       The  SCSI LOG SELECT command can be used to reset certain parameters to
       vendor specific defaults, save them to non-volatile storage  (i.e.  the
       media),  or  supply new page contents. This command has changed between
       SPC-3 and SPC-4 with the addition of the Page and Subpage  Code  fields
       which can only be non zero when the Parameter list length is zero.

       The --select (or --reset) option is required to issue a LOG SELECT com-
       mand. If the --in=FN option is not given (or FN is  effectively  empty)
       then  the  Parameter  list  length field is set to zero. If the --in=FN
       option is is given then its decoded data is placed in the data-out buf-
       fer  and  its  length  in  bytes is placed in the Parameter list length
       field.

       Other options that are active with the LOG SELECT  command  are  --con-
       trol=PC, --reset (which sets the PCR bit) and --sp.

APPLICATION CLIENT
       This  is  the name of a log page that acts as a container for data pro-
       vided by the user. An application client is a SCSI term for the program
       that  issues  commands  to  a SCSI initiator (often known as a Host Bus
       Adapter (HBA)). So, for example, this utility  is  a  SCSI  application
       client.

       The  Application  Client log page has 64 log parameters with parameters
       codes 0 to 63. Each can hold 252 bytes of user binary  data.  That  252
       bytes  (or less) of user data, with a 4 byte prefix (for a total of 256
       bytes) can be provided with the --in=FN option. A typical prefix  would
       be  '0,n,83,fc'.  The  "n" is the parameter code in hex so the last log
       parameter would be '0,3f,83,fc'. That log parameter could be read  back
       at some later time with '--page=0xf --filter=0x<n>'.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+--------------------------+
       |ATTRIBUTE TYPE |     ATTRIBUTE VALUE      |
       +---------------+--------------------------+
       |Availability   | system/storage/sg3_utils |
       +---------------+--------------------------+
       |Stability      | Pass-through uncommitted |
       +---------------+--------------------------+

NOTES
       This  utility will usually do a double fetch of log pages with the SCSI
       LOG SENSE command. The first fetch requests a  4  byte  response  (i.e.
       place  4  in  the  "allocation  length"  field  in  the cdb). From that
       response it can calculate the actual length of the  response  which  is
       what  it asks for on the second fetch. This is typical practice in SCSI
       and guaranteed to work in the standards.  However  some  older  devices
       don't comply. For those devices using the --maxlen=LEN option will do a
       single fetch.  A value of 252 should be a safe starting point.

       Various log pages hold information  error  rates,  device  temperature,
       start  stop cycles since the device was produced and the results of the
       last 20 self tests. Self tests can be initiated by  the  sg_senddiag(8)
       utility.   The  smartmontools  package provides much of the information
       found with sg_logs in a form suitable for monitoring the health of SCSI
       disks and tape drives.

       The simplest way to find which log pages can be decoded by this utility
       is to use the --enumerate option. Some page names are known  but  there
       is  no  decode  logic;  such cases have "[hex only]" after the log page
       name when the --verbose option is given with --enumerate.

       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was downloaded from  http://sg.danny.cz/sg/p/sg3_utils-1.46.tgz.

       Further information about this software can be found on the open source
       community website at http://sg.danny.cz/sg/sg3_utils.html.

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

       Options with arguments or with two or more letters can  have  an  extra
       '-' prepended. For example: both '-pcb' and '--pcb' are acceptable.

       -a     outputs  all  the log pages supported by the device.  Equivalent
              to --all in the main description.

       -A     outputs all the log pages and subpages supported by the  device.
              Equivalent to '--all --all' in the main description.

       -c=PC  Equivalent to --control=PC in the main description.

       -e     enumerate  internal  tables  to show information about known log
              pages.  Equivalent to --enumerate in the main description.

       -h     suppresses decoding of known log sense pages and prints out  the
              response in hex instead.

       -i=FN  FN  is  treated as a file name (or '-' for stdin) which contains
              ASCII hexadecimal representing a log page that will be  sent  as
              parameter  data of a LOG SELECT command. See the LOG SELECT sec-
              tion.

       -H     same action as '-h' in this section and equivalent to  --hex  in
              the main description.

       -l     lists  the  names  of  all  logs  sense  pages supported by this
              device.  Equivalent to --list in the main description.

       -L     lists the names of all logs sense pages and  subpages  supported
              by  this  device.  Equivalent  to  '--list  --list'  in the main
              description.

       -m=LEN request only LEN bytes of response data. Default is 0  which  is
              interpreted  as  all that is available. LEN is decimal unless it
              has a leading '0x' or trailing 'h'.  Equivalent to  --maxlen=LEN
              in the main description.

       -M=VP  Equivalent to --vendor=VP in the main description.

       -n     Equivalent to --name in the main description.

       -N, --new
              Switch to the newer style options.

       -p=PG  log page code to access. PG is either an acronym, a page number,
              or a page, subpage pair. Available acronyms can be  listed  with
              the  --enumerate  option.  Page  (0 to 3f) and subpage (0 to ff)
              numbers are comma separated. The numbers are assumed to be hexa-
              decimal.

       -paramp=PP
              PP  is the parameter pointer value (in hex) to place in command.
              Should be a number between 0 and ffff inclusive.

       -pcb   show Parameter Control Byte settings  (only  relevant  when  log
              parameters being output in ASCII).

       -ppc   sets the Parameter Pointer Control (PPC) bit. Default is 0 (i.e.
              cleared).

       -r     use SCSI LOG SELECT command (PCR bit set) to reset the  all  log
              pages  (or  the  given  page). Equivalent to --reset in the main
              description.

       -R     Equivalent to --readonly in the main description.

       -select
              use a LOG SELECT command. Equivalent to  --select  in  the  main
              description.

       -sp    sets  the  Saving  Parameters  (SP)  bit.  Default  is  0  (i.e.
              cleared).  Equivalent to --sp in the main description.

       -t     outputs the temperature. Equivalent to --temperature in the main
              description.

       -T     outputs  the  transport  ('Protocol  specific  port')  log page.
              Equivalent to --transport in the main description.

       -v     increase level of verbosity.

       -V     print out version string then exit.

       -x     suppress the INQUIRY command. Equivalent to --no_inq in the main
              description.

       -?     output usage message 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 environ-
       ment 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 (C) 2002-2020 Douglas Gilbert
       This  software is distributed under the GPL version 2. There is NO war-
       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR-
       POSE.

SEE ALSO
       smartctl(smartmontools), sg_senddiag(8)




sg3_utils-1.45                   January 2020                       SG_LOGS(8)