voledit(1M) Volume Manager Utilities voledit(1M)
NAME
voledit - Creates, removes, and modifies Volume Manager
records
SYNOPSIS
voledit [ -vpsrf ] [ -e pattern ] set what=value ... [ -- ]
[ record ... ]
voledit [ -vpsr ] [ -e pattern ] cc /search/replace/[gp]
[ record ... ]
voledit [ -vpsr ] rm record ...
voledit [ -vps ] rename oldname newname
DESCRIPTION
The voledit utility performs Volume Manager record-
manipulation operations that do not depend upon volume
usage-types. The first operand is a keyword that determines
the specific operation to perform. Interpretation of the
remaining operands is dependent upon that operation keyword.
The recognized operation keywords-set, cc, rm, and rename-
are discussed in this section.
set Set a field within a volume, plex, or subdisk record in
the database. The records to be changed are those
specified through the -e pattern option and those
specified with record operands. See volpattern(3X)
for a description of Volume Manager search patterns.
The what string is the name of a field to be set by the
voledit utility. value is the new value to use for
that field. More than one what=value operand can be
specified, with the set of such operands being
terminated by the first operand that does not contain
an = character. Also, an operand of -- terminates the
set of what=value operands.
If the -r option is given, then the operation is
applied recursively to associated records (to plexes
and subdisks for selected volume records, and to
subdisks for selected plex records). Recursion applies
even in the presence of -v, -p, and -s options.
The following values can be set for volumes:
comment or c Set the comment string for the volume.
A comment string cannot be longer than
40 characters (COMMENTLEN, as defined
in the include file sys/vol.h).
tutil0, tutil1, tutil2
Set one of the temporary utility fields
in the volume record. These fields can
Page 1 (printed 1/21/92)
voledit(1M) Volume Manager Utilities voledit(1M)
be set to any string value that does not
contain a new line. A utility field
cannot be set to a string that is longer
than 14 characters (UTILLEN, as defined
in the include file sys/vol.h).
Temporary utility fields are not
preserved across system reboots. The
tutil0 field is reserved for use by
usage-type utilities. As a result,
setting tutil0 may adversely effect
data, and requires that the -f option be
specified, if the field is not currently
empty.
The tutil1 field is reserved for use by
higher-level Volume Manager utilities
such as OA&M and the Visual
Administrator. The tutil2 field is
reserved for use by local installations.
putil0, putil1, putil2
Set one of the permanent utility fields
in the volume record. Permanent utility
fields are preserved across reboots.
The putil0 field is reserved for use by
usage-type utilities. As a result,
setting putil0 may adversely effect
data, and requires that the -f option be
specified, if the field is not currently
empty.
The putil1 field is reserved for use by
higher-level Volume Manager utilities
such as OA&M scripts. The putil2 field
is reserved for use by local
installations.
fstype If a volume contains a file system,
fstype can be used to indicate what type
of filesystem it is.
writecopy Turns on or off the VPFLAGWRITECOPY
flag in the volume structure, depending
upon value, which can be on or off. If
it is on, data written to a multiple-
plex volume from regions that can be
modified during the I/O get copied off
to nonvolatile buffers. If this flag is
off, a system crash may result in
undetectable inconstitencies of data
between plexes upon reboot.
Page 2 (printed 1/21/92)
voledit(1M) Volume Manager Utilities voledit(1M)
writeback Turns on or off the VPFLAGWRITEBACK
flag in the volume structure, depending
upon value, which can be on or off. If
it is on, then after a read error occurs
to a plex in a multiple-plex volume, an
attempt is made to rewrite the region
that returned the error, using data from
another plex. If the rewrite and a
subsequent read operation succeed, then
the original read is considered
successful.
user This value is either a user in the
password database or a numeric user ID.
user sets the vuid field for a volume
structure and changes the ownership for
a volume.
group Either a group name from the group
database, or a numeric group ID. group
sets the vgid field for a volume
structure and changes the group for a
volume.
mode Either a symbolic mode change, using the
same format as chmod(1), or a string
representing an octal number. A
symbolic mode causes the vmode field
for a volume structure to be changed as
specified. An octal number causes the
value for vmode to be set explicitly.
To change the length of a volume, use the volume
utility. The operation for changing a volume's length
depends upon the volume's usage-type. The voledit
utility performs only operations that are independent
of usage-type.
The following values can be set for plexes:
comment or c Set the comment string for the plex.
tutil0, tutil1, tutil2
Set one of the temporary utility fields
in the plex record. Setting the tutil0
field for an unassociated plex to a
nonempty string effectively prevents a
volume usage-type from trying to use
that plex.
putil0, putil1, putil2
Set one of the permanent utility fields
Page 3 (printed 1/21/92)
voledit(1M) Volume Manager Utilities voledit(1M)
in the plex record. If the putil0 field
for a plex is set to a nonempty string,
then future attempts to associate the
plex will fail. However, unlike use of
the tutil0 field, other plex operations
can succeed.
The following values can be set for subdisks:
tutil0, tutil1, tutil2
Set one of the temporary utility fields
in the subdisk record. Setting the
tutil0 field for an unassociated subdisk
to a nonempty string effectively
prevents a volume usage-type from trying
to use that subdisk.
putil0, putil1, putil2
Set one of the permanent utility fields
in the subdisk record. If the putil0
field is set to a nonempty string, then
future attempts to associate the subdisk
will fail. Setting this field can be
used as a means of reserving subdisks or
disk regions. For example, it is good
practice to create subdisk regions to
cover system swap areas and vold
databases. This causes the Volume
Manager to fail requests to create
subdisks within those regions. Setting
the putil0 flag can be used as an
additional safeguard to prevent use of
the subdisk as well.
comment or c Set the comment string for the subdisk.
len Set the subdisk length. This change can
be applied only to unassociated
subdisks. A subdisk length can be
specified using a C-style decimal,
hexadecimal, or octal number and can be
given a suffix of b, k, m, or g to
indicate blocks, kilobytes, megabytes,
or gigabytes. This suffix can be in
upper- or lowercase. See volsscan(3X)
for more information.
volatile This value can be on or off to signify
whether the contents of the subdisk are
volatile. on signifies that the
contents of the subdisk may not survive
across a reboot. The most common
Page 4 (printed 1/21/92)
voledit(1M) Volume Manager Utilities voledit(1M)
devices for which the contents of a
subdisk do not survive reboot are RAM
disks, which are normally cleared, along
with the rest of memory, when the system
starts up. The volatile flag is
inherited by any plex to which the
subdisk is associated. See volume(1M)
for the gen and fsgen usage-types for
more information on how the volatile
flag is used.
cc Change a comment using a search-replacement
specification similar to that used by sed(1). The
records to be affected are those specified through the
-e pattern option, and those specified with record
operands. If -e pattern is not given and there are no
record operands, then the change is made to all records
whose comment field matches the search regular
expression. A warning is written to the standard error
if no records were selected for change.
The search string is a regular expression, in the form
accepted by the function regcmp(), that is used to
determine which substring of a comment field should be
changed. The replace string represents the new string
to use as a replacement. An occurrence of & in the
replace string will be replaced by the substring
matched by the search regular expression. An
occurrence of \n in the replace string, where n is a
single digit from 1 to 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 / character is given, then it can be
followed by the letters g or p, or by both of them. If
a g is given, then all matches in a comment are
replaced, rather than just the first match. If the
letter p is given, then the resulting comment strings
are written to the standard output preceded, on the
same line, by the name of the record.
If the -r option is given, then the operation is
applied recursively to associated records (to plexes
and subdisks for selected volume records, and to
subdisks for selected plex records). Recursion applies
even in the presence of -p and -s options. Each record
to be changed is changed only once (even if the record
is referenced more than once) through the -r option, or
through both a -e expression option and a record
operand.
Page 5 (printed 1/21/92)
voledit(1M) Volume Manager Utilities voledit(1M)
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:
voledit -s cc '/^Henry ([A-Z])$1/Frank 1/p'
The command also lists the resulting comment fields.
rm Remove records from the volume configuration database.
The records to be removed are those specified with
record operands. Search patterns cannot be used with
the rm operation.
For a subdisk to be removed, it must not be associated
with a plex. For a plex to be removed, it must not be
associated with a volume. In addition, without the -r
option, a volume cannot have associated plexes and a
plex cannot have associated subdisks. With the -r
option, any plexes and subdisks associated with a
specified volume or any subdisks associated with a
specified plex are removed as well.
A volume that is currently opened, or that contains a
mounted file system, cannot be removed. The -f option
is required to remove a volume that is enabled.
rename
Change the name of a record in the configuration
database from oldname to newname. A plex cannot be
renamed if it is associated with a volume and the
corresponding plex device is currently open. A volume
cannot be renamed if it is open, or if it contains a
mounted file system, or if one of the plex devices
associated with the volume is open.
OPTIONS
The following options are recognized:
-f Force an operation to occur even if it is an operation
not normally performed as part of the operational mode
of the Volume Manager, and may have an adverse effect
on data. The operations that using -f affects are
attempts to set a nonempty putil0 or tutil0 field for a
record, and attempts to remove enabled volumes.
-v Operate only on volumes. This restricts the set of
records that can be matched with a search pattern, and
results in a diagnostic on the standard error if a
record or oldname operand does not specify a volume.
-p Operate only on plex records.
Page 6 (printed 1/21/92)
voledit(1M) Volume Manager Utilities voledit(1M)
-s Operate only on subdisk records.
-r Operate recursively on associated records. For a
volume, the operation is applied to associated plexes
and subdisks. For a plex record, the operation is
applied to associated subdisks. Recursion is applied
independently of the -v, -p, and -s options.
-e pattern
Use a volume configuration search expression to select
records to operate upon. The format for pattern is
described in volpattern(3X).
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(1M) for a list of standard exit codes.
SEE ALSO
volintro(1M), volpattern(3X), volsscan(3X), volmake(4),
regcmp(3G), and chmod(1).
Page 7 (printed 1/21/92)