Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sg_logs (8)

Name

sg_logs - access log pages with SCSI LOG SENSE command

Synopsis

sg_logs   [--All]   [--all]   [--brief]   [--control=PC]  [--enumerate]
[--enum_vendor]  [--filter=FL]  [--help]  [--hex]  [--in=FN]   [--list]
[--maxlen=LEN]  [--name]  [--no_inq]  [--page=PG] [--paramp=PP] [--pcb]
[--ppc] [--raw] [--readonly] [--reset]  [--select]  [--sp]  [--tempera-
ture] [--transport] [--verbose] [--version] DEVICE

sg_logs [-a] [-A] [-b] [-c=PC] [-e] [-E] [-f=FL] [-h] [-H] [-i=FN] [-l]
[-L]  [-m=LEN]  [-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]   [--control=PC]  [--enumerate]
       [--enum_vendor]  [--filter=FL]  [--help]  [--hex]  [--in=FN]   [--list]
       [--maxlen=LEN]  [--name]  [--no_inq]  [--page=PG] [--paramp=PP] [--pcb]
       [--ppc] [--raw] [--readonly] [--reset]  [--select]  [--sp]  [--tempera-
       ture] [--transport] [--verbose] [--version] DEVICE

       sg_logs [-a] [-A] [-b] [-c=PC] [-e] [-E] [-f=FL] [-h] [-H] [-i=FN] [-l]
       [-L]  [-m=LEN]  [-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.
       Known log pages can be decoded. When the --reset and/or --select option
       is given then a SCSI LOG SELECT command is issued.

       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.

       This utility supports two command line syntaxes, the preferred  one  is
       shown first in the synopsis and explained in this section. A later sec-
       tion on the old command  line  syntax  outlines  the  second  group  of
       options.

OPTIONS
       Arguments to long options are mandatory for short options as well.

       -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 the 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.

       -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 the 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 internal
              tables about known log pages including their names and acronyms.
              If  given  DEVICE  is  ignored.  When given once (e.g. '-e') all
              known pages are listed, sorted in ascending 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 modify the output  of  the
              enumeration.

       -E, --enum_vendor
              this  option  is  used  to  output  information held in internal
              tables about known vendor specific  log  pages  including  their
              names and acronyms.

       -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.  The --hex option outputs log parameter  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 parameters.  Examples  of
              those that don't are those pages that list supported log pages.
              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  mode  page  numbers  (and
              subpage  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 device type is
              either generic (i.e. from SPC) or  the  value  given  by  --fil-
              ter=FL.
              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. 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.

       -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.

       -r, --raw
              output  the  response  in  binary  to stdout. Error messages and
              warnings are output to stderr.

       -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 (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).  Supplying
              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"  until  something
              is done.

       -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'.

       -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 LOG SELECT command can be used to reset certain parameters to  ven-
       dor  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 option is required to issue a LOG SELECT command.  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 buffer 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 device 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.

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 . In sg3_utils  version  1.23  and  later  these
       older  options can be selected by either setting the SG3_UTILS_OLD_OPTS
       environment variable or using '--old' (or '-O) as the first option.

       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.

       -E     enumerate internal tables to show information about known vendor
              specific  log  pages.  Equivalent  to  --enum_vendor 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.

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

       -N     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.

AUTHOR
       Written by Douglas Gilbert

REPORTING BUGS
       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT
       Copyright (C) 2002-2016 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)


       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.42.tgz

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



sg3_utils-1.42                   February 2016                      SG_LOGS(8)