unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



volprint(8)							  volprint(8)



NAME

  volprint - Displays records from the Logical Storage Manager configuration

SYNOPSIS

  /sbin/volprint [-AvpsdGhnlafmtqQ] [-g	diskgroup] [-e pattern]	[-D database]
  [-F [type:] format_spec] [name...]

  /sbin/volprint [-SAq]	[-g diskgroup]

OPTIONS

  The following	options	are recognized:

  -S  Displays configuration summary information. The output consists of a
      header line followed by a	line containing	the total number of subdisks,
      plexes and volumes; the number of	unassociated subdisks; and the number
      of unassociated plexes.

  -A  Prints records from all active (imported)	disk groups. Each disk group
      represented in the output	is separated from other	disk groups by blank
      lines. A short header line introduces each disk group.

  -g diskgroup
      Displays records from the	specified disk group. The diskgroup option
      argument can be either a disk group name or disk group ID.

  -v  Displays volumes and their hierarchies (associated plexes	and sub-
      disks). If used with the -n option, displays volume names	only. If used
      with the -e option, the database records matched will primarily be
      reduced to volumes. If a name operand names a plex or subdisk, a diag-
      nostic is	written	to the standard	error output.

  -p  Displays plexes and their	hierarchies (associated	subdisks). If used
      with the -n option, displays plex	names only. If used with the -e
      option, the database records matched will	primarily be reduced to
      plexes. If a name	operand	names a	volume or subdisk, a diagnostic	is
      written to the standard error output.

  -s  Displays only subdisks. If a name	operand	names a	volume or plex,	a
      diagnostic is written to the standard error output.

  -d  Displays only disk media records.

  -G  Displays only disk group records.








				       Note

	 The -v, -p, -s, -d, and -G options can	be combined to specify that
	 more than one record type is allowed. Specifying all these options
	 is equivalent to the default behavior.

  -e pattern
      Uses a volume configuration search expression to select records to be
      displayed. See vol_pattern(4) for	a description of search	patterns.

  -h  Lists complete hierarchies below selected	records. For volumes, this
      list includes all	associated plexes and subdisks.	For plexes, this list
      includes all associated subdisks.	Hierarchies are	separated in the out-
      put by a blank line. Each	object listed occupies its own line. The
      order of output is a volume name,	followed by one	associated plex, fol-
      lowed by all of the subdisks for that plex, followed by another associ-
      ated plex, followed by all of the	subdisks for the second	plex, and so
      on.

      The -v, -p, and -s options limit the selection only of the head of a
      hierarchy. They do not prevent the display of associated records
      through the -h option.

      Unless objects are named explicitly with name operands, a	record is
      never displayed in two separate hierarchies. Thus, a selected plex is
      not displayed as a separate hierarchy if the volume that is associated
      with the plex is also selected.

  -n  Displays only the	names of selected records.

  -l  Displays all information from each selected record. This information is
      in a free	format that is not intended for	use by scripts.	This format
      is more convenient than the -m format for	looking	at records directly,
      because the density of information is more appropriate for human view-
      ing.

  -a  Displays all information about each selected record, one record per
      line. The	format is the same as for the -m option, except	that the -a
      option format appears on a single	line with one space character between
      each field, and the list of associated records is	not displayed. This
      format is	useful for processing output through filters such as sed and
      grep that	operate	exclusively on one-line	records, although the fields
      are not readily distinguishable. It is not a practical format from the
      viewpoint	of human readability.

  -m  Displays all information about each selected record in a format that is
      useful as	input to both the volmake utility and to awk scripts. The
      format used is the volmake description format (see volmake(4)).  In
      addition to record information, the list of plex or subdisk records
      associated with selected volume or plex records is displayed. Each
      field is displayed on a separate line, indented by a single tab
      ('\\t'). Values for fields that contain comment-style strings are
      always preceded by one double-quote character ('"') and terminated with
      the end-of-line character	('\\n').

  -f  Displays information about each record as	one-line output	records	con-
      taining the following fields, from left to right:

       1.  Record type

       2.  Record name

       3.  Usage-type, volume association, or plex association (or - for
	   unassociated	plexes and subdisks)

       4.  Enabled state (or - for subdisks, disks, or disk groups)

       5.  Length, in units of system sectors

       6.  Plex	association offset (or - for volumes, plexes, disks, or	disk
	   groups). This field will appear as LOG for log subdisks.

       7.  Usage-dependent state (or - for subdisks).  If an exception condi-
	   tion	is recognized (a plex I/O failure, removed or inaccessible
	   disk, or an unrecovered stale data condition), that condition is
	   listed instead of any usage-type-dependent state.

       8.  The tutil[0]	field. This field is set by usage-types	as a lockout
	   mechanism.

       9.  The putil[0]	field. This field can be set to	prevent	associations
	   of plex or subdisk records.

      A	one-line header	is written before any record information.

  -t  Prints single-line output	records	that depend upon the configuration
      record type.

      For disk groups, the output consists of the following fields, in order
      from left	to right:

       1.  Record type (dg)

       2.  Disk	group name

       3.  Number of configuration copies to enable

       4.  Number of log copies	to enable

       5.  Base	number for minor of device

       6.  Disk	group ID

      For disk media records, the output consists of the following fields, in
      order from left to right:

       1.  Record type (dm)

       2.  Record name

       3.  Underlying disk access record

       4.  Disk	access record type (sliced, simple, or nopriv)

       5.  Length of the disk's	private	region

       6.  Length of the disk's	public region

       7.  Usage-dependent state (or -)

      For subdisks, the	output consists	of the following fields, from left to
      right:

       1.  Record type (sd)

       2.  Record name

       3.  Associated plex, or a dash (-) if the subdisk is dissociated

       4.  Name	of the disk media record used by the subdisk

       5.  Device offset in sectors

       6.  Subdisk length in sectors

       7.  Plex	association offset, optionally preceded	by subdisk column
	   number for subdisks associated to striped plexes, LOG for log
	   subdisks, or	the putil[0] field if the subdisk is dissociated.
	   The putil[0]	field can be nonempty to reserve the subdisk's space
	   for nonvolume uses. If the putil[0] field is	empty, a dash (-) is
	   displayed for dissociated subdisks.

       8.  Underlying device name.

       9.  A string representing the state of the subdisk (ENA if the subdisk
	   is usable; DIS if the subdisk is disabled; RCOV if the subdisk is
	   part	of a RAID 5 plex and has stale content;	DET if the subdisk
	   has been detached; KDET if the subdisk has been detached in the
	   kernel due to an error; RMOV	if the media record on which the sub-
	   disk	is defined has been removed from its disk access record	by a
	   utility; or NDEV if the media record	on which the subdisk is
	   defined has no access record	associated).

      For plexes, the output consists of the following fields, from left to
      right:

       1.  Record type (pl)

       2.  Record name

       3.  Associated volume, or a dash	(-) if the plex	is dissociated

       4.  Plex	kernel state

       5.  Plex	utility	state. If an exception condition is recognized on the
	   plex	(an I/O	failure, a removed or inaccessible disk, or an
	   unrecovered stale data condition), that condition is	listed
	   instead of the value	of the plex record's state field.

       6.  Plex	length in sectors

       7.  Plex	layout type

       8.  Number of columns and plex stripe width, or a dash (-) if the plex
	   is not striped

       9.  Plex	I/O mode, either RW (read-write), WO (write-only), or RO
	   (read-only)

      For volumes, the output consists of the following	fields,	from left to
      right:

       1.  Record type (v)

       2.  Record name

       3.  Associated usage type

       4.  Volume kernel state

       5.  Volume utility state

       6.  Volume length in sectors

       7.  Volume read policy

       8.  The preferred plex, if the read-policy uses a preferred plex, or a
	   dash	(-) if not applicable to the type of its read-policy.

      A	header line is printed before any record information, for each type
      of record	that could be selected based on	the -v,	-p, -s,	and -h
      options. These header lines are followed by a single blank line.

  -q  Suppresses headers that would otherwise be printed for the default and
      the -t and -f output formats.

  -Q  Suppresses the disk group	header that separates each disk	group. A sin-
      gle blank	line still separates each disk group.

  -F [type:]format_spec
      Sets a literal format string to use for displaying record	information.
      If the option argument begins with a comma-separated list	of zero	or
      more record types	(sd, plex, or vol) followed by a colon,	the
      format_spec after	the colon is used when printing	the indicated record
      types. If	no record types	are specified, all record types	are assumed.

      The order	of -F options is significant, with specifications later	in
      the option list overriding earlier specifications. Any use of -F over-
      rides any	other option letter specifying a type of format	for the	indi-
      cated record types. Thus,	-F vol:format_spec can be used with the	-t
      option to	change the format used for volumes, while still	using the -t
      format for plex and subdisk records.

      The format_spec string consists of literal text with embedded confi-
      guration record variables. Configuration record variables	are intro-
      duced with a percent sign	(%). The percent sign is followed by a vari-
      able name	or by a	variable name and optional field width in braces. The
      following	formats	are allowed for	a variable specification:


	   %field_name
	   %{field_name}
	   %{field_name:[[-]width][*]}
	   %{field_spec|field_spec[|...]}

      The first	format specifies the exact field name. The second format
      allows a field to	be specified with immediately surrounding text that
      would otherwise be taken as part of the field name. The third format
      allows the specification of a justification and a	field width. The
      fourth format allows alternate specifications to be used,	either with
      or without justification and width specifications.  For the fourth, the
      first specification is used if the specified field name is applicable
      to the record and	is nonempty; otherwise,	the next available specifica-
      tion is used. Any	number of alternate specifications can be used.

      If no field width	is specified, the number of output column positions
      used for the field is the	smallest possible to contain the value;	oth-
      erwise spaces are	added in the output to make it width columns in
      length. A	field is not truncated if the minimum number of	column posi-
      tions necessary for a value is greater than width.

      If a field width is specified with a leading dash	(-) character, an
      output field is lengthened by adding spaces after	the field value,
      yielding a left-justified	field. Otherwise, spaces are added before the
      value, yielding a	right-justified	field.

      If a field width is followed or replaced by an asterisk (*) character,
      an unrecognized or inappropriate field yields either no output for the
      field or a field containing all blanks. Without the asterisk, the
      printed field contains the dash (-) character.

      One % character can be displayed by including two	% characters in
      format_spec.

      See the RECORD FIELDS section for	a description of the field names that
      can be specified.	An invalid format string may yield unexpected output,
      but does not generate an error.

  -D database
      Gets a configuration from	the specified location.	The database option
      argument can be one of:

      vold
	  (Default). Gets a configuration from the volume configuration	dae-
	  mon.

      -	  Reads	a configuration	from the standard input. The standard input
	  is expected to be in standard	volmake	input format.

DESCRIPTION

  The volprint utility displays	complete or partial information	from records
  in Logical Storage Manager disk group	configurations.	Records	can be
  selected by name or with special search expressions (see vol_pattern(4)).
  Additionally,	record association hierarchies can be displayed	in a way that
  makes	the structure of records more apparent.

  Dashes (-) are displayed in the output wherever there	is no applicable
  record value.

  If no	options	are specified, the default output uses -f, -h, and -A. How-
  ever,	specifying certain options can override	-h or -A, making it necessary
  to specify -h	or -A explicitly with some option combinations.

  By default, record information is displayed on single	lines with fields for
  record type, name, usage type	or object association, enabled state, length,
  and others. A	one-line header	is written before the record information.

  The default output includes all records for all active disk groups.  Sub-
  disks	are sorted primarily by	the subdisk device, secondarily	by the device
  offset. Plex and volume records are sorted by	name.

				     Note

       The volprint utility displays only disk group, disk media, volume,
       plex, and subdisk records. To display disk access records or physical
       disk information, use the voldisk list operation.

RECORD FIELDS

  You can use the field	names displayed	by the volprint	-a and volprint	-m
  commands as input to volmake.	You can	also use the same fields that you
  specify with the -F format_spec string as input to volmake. For a list of
  these	field names, see volmake(4). Some additional pseudo fields are also
  supported. These are:

  name
      The name of the record being displayed. Because the record name is
      specified	positionally within volmake description	formats, the volmake
      utility and the -m and -a	options	to volprint do not explicitly provide
      this field name.

  rec_type or rtype
      Either dg	(disk group), dm (disk), vol (volume), plex (plex), or sd
      (subdisk), depending on the record being displayed.

  short_type or	type
      Either dg, dm, v,	pl, or sd, depending upon the record type. This
      pseudo variable can be used in a 2-character field, if a full
      4-character field	(required by rec_type) is too large.

  dgname or dg_name
      The name of the disk group containing the	record.

  assoc
      The name of the volume or	plex to	which a	plex or	subdisk	record is
      associated. If the record	is not associated, this	field is empty.

  use_assoc
      The usage	type for volume	records	and the	association name for associ-
      ated plexes and subdisks.	 For dissociated plexes	and subdisks, this is
      an empty string.

  aslist
      A	comma-separated	list of	subdisks or plexes that	are associated with a
      plex or volume record.

  sdaslist
      A	comma-separated	list of	subdisks associated with a plex. Each subdisk
      name is followed by a colon and the subdisk's plex association offset,
      in sectors. For volume records, this field is equivalent to aslist.

  admin_state
      The persistent state for a plex or volume	record,	accounting for any
      exceptional conditions.  For volume records, this	displays the state
      field. For plex records, this displays one of the	following in the
      given precedence order: NODEVICE if an expected underlying disk could
      not be found; REMOVED if an underlying disk is in	the removed state;
      IOFAIL if	an unrecovered I/O failure caused the plex to be detached;
      RECOVER if a disk	replacement left the plex in need of recovery, either
      from another plex	or from	a backup.

  vname	or v_name
      The name of an associated	volume record. For a volume record, this is
      the volume's name; for a plex record, this is the	associated volume's
      name (if any); for a subdisk record, this	is the associated volume of
      the associated plex (if any).

  plname or pl_name
      The name of an associated	plex record. For a plex	record,	this is	the
      plex's name; for a subdisk record, this is the associated	plex's name
      (if any).

  ncolumn_st_width
      For a striped plex, the number of	columns	and stripe unit	size for a
      plex, separated by a /, or - if the plex is not striped.

  column_pl_offset
      For a subdisk associated with a striped plex, the	column number and
      column offset of the subdisk separated by	a / or the plex	offset (if
      the subdisk is associated	in a nonstriped	plex) or - (if the plex	is
      not associated).

  sd_flag
      For a subdisk associated with a RAID 5 plex, this	will display flags
      relating to the status of	the subdisk. An	S indicates that the subdisk
      is considered to contain stale data. A d indicates that the subdisk has
      been detached from the RAID 5 plex.

  Displaying a Boolean value always yields on or off. If a field containing a
  length or offset is specified	in a format_spec string, the result is the
  length or offset in sectors.	When the field is displayed with -m or -a,
  the length or	offset is displayed in sectors with a suffix of	s.



EXAMPLES

   1.  The following command displays all records in all disk groups, with
       clearly displayed associations and with output lines tailored to	each
       record type:


	    # volprint -Ath

       To simplify the output, you can add the -q option to suppress the
       display of header lines.

   2.  The following command displays information on all subdisks and all
       disk groups, in sorted order by disk:


	    # volprint -Gts

       This form of volprint can be useful for viewing information in large
       configurations where all	plex names are based on	volume names. The
       association field for each subdisk gives	the plex name, and the form
       of the plex name	usually	implies	a volume association.

   3.  The following command displays the names	of all unassociated plexes:


	    # volprint -n -A -p	-e !assoc

       When issued from	csh, the negation prefix (!) must be escaped (\!).

   4.  The following command displays information for all subdisks, including
       the subdisk name	and either the subdisk plex association	offset or the
       putil0 field for	dissociated subdisks:


	    # volprint -As -F "%{name:-14} %{pl_offset|putil0}"



EXIT CODES

  The volprint utility exits with a nonzero status if the attempted operation
  fails. A nonzero exit	code is	not a complete indicator of the	problems
  encountered but rather denotes the first condition that prevented further
  execution of the utility.

  See volintro(8) for a	list of	standard exit codes.

SEE ALSO

  awk(1), grep(1), sed(1), volmake(4), vol_pattern(4), volinfo(8), volin-
  tro(8), volmake(8)