unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



voledit(8)							   voledit(8)



NAME

  voledit - Creates, removes, and modifies Logical Storage Manager (LSM)
  records

SYNOPSIS

  /sbin/voledit	[-g diskgroup] [-e pattern] [-vpsdGrf] set attribute=value...
  [name...]

  /sbin/voledit	[-g diskgroup] [-e pattern] [-vpsdGr] cc /search/replace/
  [gp] [name...]

  /sbin/voledit	[-g diskgroup] [-vpsdrf] rm name...

  /sbin/voledit	[-g diskgroup] [-vpsd] rename oldname newname

OPTIONS

  The following	options	are recognized:

  -g diskgroup
      Specifies	the disk group for the operation, either by disk group ID or
      by disk group name.  By default, the disk	group is chosen	based on the
      name and oldname operands.

  -f  Forces an	operation that the Logical Storage Manager considers poten-
      tially dangerous or is not a normal operation for	the command. This
      enables a	limited	set of operations that would otherwise be disallowed.
      Some operations may be disallowed	even with this flag.  The voledit
      operations that are allowed with this flag are changing a	non-empty
      tutil0 or	putil0 field, and removing enabled volumes.

  -v, -p, -s, -d, -G
      Selects only volume, plex, subdisk, disk media, or disk group records,
      respectively.  If	more than one of these options are specified, records
      of any of	the indicated types may	be selected.

  -r  Operates recursively on records associated with the selected records.
      For selected volume records, this	affects	associated plex	and subdisk
      records.	For selected plex records, this	affects	associated subdisk
      records.

  -e pattern
      Uses a Logical Storage Manager configuration search expression to
      select records from the selected disk group configuration.  Search pat-
      terns are	currently limited to a selection of volume, plex, and subdisk
      records.






DESCRIPTION

  The voledit utility sets and changes various attributes for Logical Storage
  Manager configuration	records	that do	not depend upon	volume usage types.
  See volume(8)	for operations that can	set attributes that are	dependent
  upon usage types.  In	particular, setting the	length and logging type	for a
  volume requires use of the volume set	operation.

  Each invocation can be applied to only one disk group	at a time, due to
  internal implementation constraints.	Any name or oldname operands will be
  used as record names to determine a default disk group, according to the
  standard disk	group selection	rules described	in volintro(8).	If no name or
  oldname operands are given, the disk group defaults to rootdg. A specific
  disk group can be forced with	-g diskgroup.

KEYWORDS

  These	are the	recognized operation keywords:

  set Sets a field within a volume, plex, subdisk, disk	media, or disk group
      record in	the selected disk group.  The records to be changed are	those
      that match the pattern specified with the	-e pattern option and those
      specified	by the name operands.

      The attribute names specify the field to set within the selected
      records.	More than one attribute	can be specified in a single invoca-
      tion.  The operands that indicate	attribute settings end at the first
      operand that does	not contain an equal sign.  An operand of -- can be
      used to separate the attribute list from record names, even if the
      first record name	contains an equal sign.

      If the -r	option is given, the operation is applied recursively to
      records associated with the selected records (to plexes and subdisks
      for selected volume records, and to subdisks for selected	plex
      records).	 Recursion applies regardless of whether the -p	and -s
      options are specified.

      The following values can be set for all record types except for disk
      access records:

      comment or c
	  Sets the comment string for the selected records to the given
	  value. The comment string cannot be longer than 40 characters	and
	  cannot contain a newline character.

      tutil0, tutil1, tutil2
	  Sets one of the non-persistent (temporary) utility fields in the
	  record.

      putil0, putil1, putil2
	  Sets one of the persistent (permanent) utility fields	in the
	  record.  The six utility fields cannot be longer than	14 characters
	  and cannot contain a newline character.  The tutil0 and putil0
	  fields are reserved for use by the the base Logical Storage Manager
	  utility set, and by usage types.  The	tutil1 and putil1 fields are
	  reserved for use by higher-level utilities. The tutil2 and putil2
	  fields are reserved for any desired use by system administrators.

	  The putil0 field for a plex and subdisk record can be	set to
	  prevent utilities from associating the record	to a volume or plex.
	  This is a convenient means for reserving a plex, or for reserving a
	  region of disk space (a subdisk).

	  Changing a non-empty putil0 or tutil0	field requires use of -f.
	  Setting these	fields for dissociated plex and	subdisk	records	is
	  generally not	a problem.  However, for an associated plex or sub-
	  disk that is associated (through a plex) with	a volume, setting
	  either of these fields can be	dangerous, as it can affect the
	  operation of usage types that	expect to manage these fields them-
	  selves during	an operation.

      The following attributes can only	be set for volume records:

      fstype
	  If a volume contains a file system, fstype can be used to indicate
	  what type of file system it is.

	  Any of the following values can be used for the fstype setting:

	  unused
	      Available	for use.

	  swap
	      Used as swap space.

	  4.2BSD, ufs, or UFS
	      Use by a UNIX file system.

	  AdvFS
	      Used by an AdvFS file system.

	  database
	      Used by a	database.

	  raw Used for raw data.

      writecopy
	  Sets (on) or clears (off) a volume policy that affects consistency
	  of data written to a volume when dirty region	logging	is in effect
	  on the volume.  When the operating system hands off a	write request
	  to the volume	driver,	the operating system may continue to change
	  the memory that is being written to disk. The	Logical	Storage
	  Manager cannot detect	that the memory	is changing, so	it can inad-
	  vertently leave plexes with inconsistent contents.

	  This is not normally a problem, because the operating	system
	  ensures that any such	modified memory	is rewritten to	the volume
	  before the volume is closed, such as by a clean system shutdown.
	  However, if the system crashes, plexes may be	inconsistent.  Since
	  the dirty region logging feature prevents recovery of	the entire
	  volume, it may not ensure that plexes	are entirely consistent.

	  Setting the writecopy	flag often causes the Logical Storage Manager
	  to copy the data for a write request to a new	section	of memory
	  before writing it to disk.  Because the write	is done	from the
	  copied memory, it can't change, so the data written to each plex is
	  guaranteed to	be the same.

      writeback
	  Sets (on) or clears (off) a volume policy that affects recovery
	  after	read failures on a mirrored volume.  If	the writeback flag is
	  set (which is	normally the default), a read failure for a plex will
	  cause	data to	be read	from an	alternate plex and then	written	back
	  to the plex that got the read	failure. This will usually fix the
	  error.  Only if the writeback	fails will the plex be detached	for
	  having an unrecoverable I/O failure.

	  If this flag is clear, data from an alternate	plex will be read to
	  satisfy the volume read operation, but the failing plex will be
	  detached with	no action taken	to try to fix the problem.

	  There	is seldom (if ever) a reason to	turn off this feature.

      user
	  Sets the user	that owns a volume record to the user specified	as
	  the attribute	value.	The attribute value can	be either a login
	  name from the	/etc/passwd database, or a numeric user	ID.

      group
	  Sets the group that owns a volume record to the group	specified as
	  the attribute	value.	The attribute value can	be either a group
	  name from the	/etc/group database, or	a numeric group	ID.

      mode
	  Sets the access permissions for the volume to	the permission mode
	  specified in the attribute value.  The attribute value can be	a
	  symbolic permission mode or an octal mode.  The format is compati-
	  ble with permission modes as used by the chmod utility (see
	  chmod(1)).

      The following special attribute can be set for subdisk records:

      len Sets the length of the subdisk to the	given length.  The attribute
	  value	is a standard Logical Storage Manager length number (see vol-
	  intro(8)).  The length of a subdisk can be changed only if the sub-
	  disk is dissociated.	The length of a	subdisk	cannot be increased
	  to the point where it	would extend past the end of the disk, or to
	  where	it would overlap a reserved disk region	or another subdisk.

      The following special attributes can be set for disk media records:

      reserve
	  Sets (on) or clears (off) the	disk reservation flag. If the reserve
	  flag is set for a disk, volassist will not allocate a	subdisk	on
	  that disk unless the disk is specified on the	volassist command
	  line.

      spare
	  Sets (on) or clears (off) the	disk hot spare flag. If	the hot	spare
	  flag is set for a disk, that disk is designated for use by the
	  hot-sparing facility.	 A disk	media record with the spare flag set
	  will be used only for	relocation. The	volassist utility will not
	  allocate a subdisk on	that disk unless forced	to by command-line
	  arguments.

      failing
	  Sets (on) or clears (off) the	disk failing flag. If the failing
	  flag is set for a disk, the disk space is not	used as	free space or
	  used by the hot-sparing facility.

  cc  Changes a	comment	using a	search-replacement specification similar to
      that used	by sed(1) in volume, plex, subdisk, disk media,	or disk	group
      records within the selected disk group.  The records to be changed are
      those that match the pattern specified with -e pattern option and	those
      specified	by the name operands.  See volintro(8) for a description of
      Logical Storage Manager search patterns.	If no search pattern is
      specified	with -e, and no	name operands are given, the change is made
      to all records whose comment field matches the search regular expres-
      sion.

      The search string	is a regular expression, in the	form accepted by the
      function regcmp(3). This regular expression is used to determine which
      substring	of the comment field is	to be changed.	The replace string
      represents the new string	to use as a replacement	for the	matched	part
      of the comment.

      An occurrence of && in the	replace	string will be replaced	by the
      substring	of the comment matched by the regular expression.  An
      occurrence of \n in the replace string, where n is a single digit
      between 1	and 9, will be replaced	by the substring matched by a
      parenthetical section of the regular expression; the regular expression
      is followed by $n.

      The / character following	the replace string is optional.	If the / is
      given, it	can be followed	by the letters g or p, or both.	 If a g	is
      given, all matches in a comment are replaced, rather than	just the
      first match.  If the letter p is given, the resulting comment strings
      are written to the standard output, immediately preceded (on the same
      line) by the name	of the record.

      If the -r	option is given, the operation is applied recursively to
      records associated with the selected records (to plexes and subdisks
      for selected volume records, and to subdisks for selected	plex
      records).	 Recursion (when selected) applies regardless of the -p, and
      -s options.

      Each record to be	changed	is changed only	once, even if the record
      could be matched several times through combinations of name arguments,
      search patterns, and the -r option.

      For example, the following command changes all subdisk comments that
      begin with ``Henry'' and a second	word beginning with an uppercase
      letter to	begin with ``Frank'' and the same second word:


	   /sbin/voledit -s cc '/^Henry	([A-Z])$1/Frank	\1/p'

      This command also	lists the resulting comment fields.

  rm  Removes volume, plex, or subdisk records from the	selected disk group.
      Disk media records can be	removed	with voldg rmdisk.  Disk access
      records can be removed with voldisk rm.

      Removing a subdisk requires that the subdisk be dissociated.  Removing
      a	plex requires that the plex be dissociated and that it have no asso-
      ciated subdisks.	Removing a volume requires that	it have	no associated
      plexes.  The -r option can be specified to recursively remove a volume
      and all plex and subdisk records associated with it, or to remove	a
      plex and all subdisk records associated with it.	Even when removing
      with -r, a named plex or subdisk cannot be associated with a volume or
      plex, respectively.

      The -f option is required	to remove an enabled volume.  A	volume cannot
      be removed, even with -f,	if the corresponding volume block or raw dev-
      ice is open or mounted.

  rename
      Changes the name of a volume, plex, subdisk, or disk media record	from
      oldname to newname.  A record cannot be renamed if the tutil0 field is
      set, which indicates that	an operation is	in progress that involves the
      record.

EXIT CODES

  The voledit 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

  chmod(1), regcmp(3), volintro(8), volmake(8),	volmend(8), volume(8)