Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SG_READ_ATTR(8)			   SG3_UTILS		       SG_READ_ATTR(8)

NAME
       sg_read_attr - send SCSI	READ ATTRIBUTE command

SYNOPSIS
       sg_read_attr    [--cache]    [--enumerate]    [--ea=EA]	 [--filter=FL]
       [--first=FAI] [--help]  [--hex]	[--in=FN]  [--lvn=LVN]	[--maxlen=LEN]
       [--pn=PN]  [--quiet] [--raw] [--readonly] [--sa=SA] [--verbose] [--ver-
       sion] DEVICE

DESCRIPTION
       Sends a SCSI READ ATTRIBUTE command to DEVICE and outputs the data  re-
       turned. This command was	introduced in SPC-3 revision 1 and thus	is ap-
       plicable	to all SCSI devices. In	practice it is used  mainly  for  tape
       systems.	This utility is	based on the SPC-5 draft standard, revision 17
       (spc5r17.pdf).

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

       -c, --cache
	      sets the CACHE bit in the	READ ATTRIBUTE cdb. This instructs the
	      device  server  to return	cached attributes. By default that bit
	      is cleared which instructs  the  device  server  not  to	return
	      cached attributes.

       -e, --enumerate
	      enumerates  all known attributes and service actions. Attributes
	      include an identifier, length, format and	a name as  defined  by
	      T10. If DEVICE is	given then it is ignored.

       -E, --ea=EA
	      where  EA	 is an element address which is	placed in the READ AT-
	      TRIBUTE cdb. This	field is only found in SMC-2 and SMC-3	drafts
	      for  medium  changers usually associated with tape libraries. By
	      default this field is set	to zero.

       -f, --filter=FL
	      where FL is an attribute identifier in the range 0 to  65535  or
	      -1.  Attribute identifiers are typically given in	hexadecimal in
	      which case the hex number	should be prefixed by "0x"  or	has  a
	      trailing	"h".  "-1" is the default value	and means 'match all';
	      for all other values of FL on the	matching attribute is output.

       -F, --first=FAI
	      where FAI	is the "first attribute	identifier" field in the  cdb.
	      It  seems	 as  though  the intent	of this	field is that only at-
	      tributes whose identifiers are equal to or greater than FAI  are
	      returned.	 The  default value of FAI is zero. Attributes are re-
	      turned in	ascending identifier order.

       -h, --help
	      output the usage message then exit.

       -H, --hex
	      output the response in hexadecimal to stdout. When used once the
	      whole response is	output in ASCII	hexadecimal with a leading ad-
	      dress (starting at 0) on each line. When used twice each	attri-
	      bute descriptor in the response is output	separately in hexadec-
	      imal. When used thrice the whole response	is output in hexadeci-
	      mal with no leading address (on each line).
	      Output  generated	 by  '-HHH' (or	--hex used three times)	can be
	      redirected to a file. That file will be in suitable  format  for
	      --in=FN to use in	a later	invocation.

       -i, --in=FN
	      FN  is  treated as a file	name (or '-' for stdin)	which contains
	      ASCII hexadecimal	or binary representing the response to a  READ
	      ATTRIBUTE	command	with service action 0x0	(i.e (fetch) attribute
	      values). When this option	is given then DEVICE (if  also	given)
	      is ignored.
	      By  default  FN is assumed to contain ASCII hexadecimal arranged
	      as bytes which a space, tab or comma delimited.  All  characters
	      from  (and including) "#"	to the end of line are ignored.	If the
	      --raw option is also given then FN is assumed to contain	binary
	      data.  When  the --raw option is given then after	processing the
	      input the	internal raw variable is reset to 0 so it has  no  ef-
	      fect on the output.
	      Since  the  READ ATTRIBUTE response does not contain the service
	      action number that it is a response to, then the --sa=SA	should
	      be given (if not service action 0	(attribute values) is assumed.

       -l, --lvn=LVN
	      where  LVN is placed in the "logical volume number" field	of the
	      cdb.  The	default	value is zero which is required	to be the log-
	      ical volume number if the	device only has	one volume.

       -m, --maxlen=LEN
	      where  LEN  is  the  (maximum)  response	length in bytes. It is
	      placed in	the cdb's "allocation length" field. If	not given  (or
	      LEN is zero) then	8192 is	used. The maximum allowed value	of LEN
	      is 1048576.

       -p, --pn=PN
	      where PN is placed in the	"partition number" field of  the  cdb.
	      If  the  DEVICE only has one partition then its partition	number
	      must be zero. The	default	value of PN is zero.

       -q, --quiet
	      this option reduces the amount of	information output. For	 exam-
	      ple  when	 used  once  (SA=0), it	suppresses the header line an-
	      nouncing the output of attributes; when used twice it suppresses
	      the  name	 of each attribute, leaving only the associated	attri-
	      bute values (or strings).

       -r, --raw
	      output the SCSI response (i.e. the data-out  buffer)  in	binary
	      (to stdout).

       -R, --readonly
	      open the DEVICE read-only	(e.g. in Unix with the O_RDONLY	flag).
	      The default is to	open it	read-write.

       -s, --sa=SA
	      where SA is placed on the	"service action"  field	 of  the  cdb.
	      Values  of 0 to 63 are accepted with a default of	0. spc5r08.pdf
	      defines five service actions: 0 for attributes values ; 1	for an
	      attribute	 list  (names,	not  values), 2	for the	logical	volume
	      list; 3 for the partition	list; 4	is restricted for SMC-3; and 5
	      for the supported	attribute list.
	      Alternatively an acronym can be given for	SA. The	acronym	should
	      be one of	"av", "al", "lvl", "pn", "smc" or "sa" for service ac-
	      tions 0 to 5 respectively. The acronyms can also be given	in up-
	      per case.

       -v, --verbose
	      increase the level of verbosity, (i.e. debug output).

       -V, --version
	      print the	version	string and then	exit.

NOTES
       Only tape systems seem to implement the SCSI  READ  ATTRIBUTE  command.
       The vast	majority of its	definition is in the SPC standard so other de-
       vice types could	use it.

       Much of the information provided	by READ	ATTRIBUTE can also be found in
       pages  returned	by  LOG	SENSE (see the sg_logs utility)	and in the VPD
       pages returned by the INQUIRY command.

EXAMPLES
       To list the attributes of a tape	drive whose xxxx is /dev/sg1 the  fol-
       lowing could be used:

       # sg_read_attr -s al /dev/sg1
       Attribute list:
	 Remaining capacity in partition [MiB]
	 Maximum capacity in partition [MiB]
	 TapeAlert flags
	 Load count
	 MAM space remaining [B]
	 Assigning organization
	 Format	density	code
	 ...

       To check	the number of partitions:

       # sg_read_attr -s pl /dev/sg1
       Partition number	list:
	 First partition number: 0
	 Number	of partitions available: 2

       And to see the attribute	values (which is the default service action):

       # sg_read_attr /dev/sg1
       Attribute values:
	 Remaining capacity in partition [MiB]:	1386103
	 Maximum capacity in partition [MiB]: 1386103
	 TapeAlert flags: 0
	 ....

       To redirect the attribute values	response to a file for later decoding:

       # sg_read_attr -HHH /dev/sg1 > av.hex

       And later the response held in the av.hex file could be decoded with:

       # sg_read_attr -s av --in=av.hex
       Attribute values:
	 Remaining capacity in partition [MiB]:	1386103
	 Maximum capacity in partition [MiB]: 1386103
	 TapeAlert flags: 0
	 ....

EXIT STATUS
       The  exit  status of sg_read_attr is 0 when it is successful. Otherwise
       see the sg3_utils(8) man	page.

AUTHORS
       Written by Douglas Gilbert.

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

COPYRIGHT
       Copyright (C) 2016-2017 Douglas Gilbert
       This software is	distributed under a FreeBSD license. There is NO  war-
       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
       POSE.

SEE ALSO
       sg_vpd,sg_logs(sg3_utils)

sg3_utils-1.43			 November 2017		       SG_READ_ATTR(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | EXAMPLES | EXIT STATUS | AUTHORS | REPORTING BUGS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sg_read_attr&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help