volintro(1M) Volume Manager Utilities volintro(1M)
NAME
volintro - Introduction to Volume Manager utilities
SYNOPSIS
voladm
vold
voledit
volinfo
voliod
volmake
volmend
volplex
volprint
volsd
volstat
voltrace
volume
DESCRIPTION
The Volume Manager utilities provide a shell-level command
interface to the system administrator, or to a shell script
or another type of program, as a means for examining and
changing the state of the Volume Manager configuration as
well as data stored on devices within the Volume Manager's
control.
The Volume Manager utilities come in three basic types:
utilities that operate on Volume Manager configuration
database records in a manner that is dependent upon a volume
usage-type; usage-type-independent administrative utilities;
and the volume daemon.
A volume usage-type is a set of attributes, policies, and
operations that apply to volumes that are used for a
specific purpose. For example, volumes that contain file
systems have different attributes and policies from other
volumes. To allow a usage-type to manipulate records
according to those attributes, usage-type-dependent
operations are split into two kinds of utilities: a
switchout utility that handles the general aspects of the
operation and which determines the volume usage type
involved; and a usage-type-specific utility that handles the
operations that depend upon the specific volume usage-type.
The usage-type-specific utilities are stored under
subdirectories of the directory /usr/lib/VxVM/type.
The utilities that have both switchout and usage-type-
specific parts are:
volinfo Prints the operating status of a volume
volmake Creates new configuration records
volmend Repairs or sets volume and plex states
Page 1 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
volplex Performs operations on plexes
volsd Performs operations on subdisks
volume Performs operations on volumes
Except for volmake, these utilities do not perform
operations themselves, but rely on the usage-type specific
form of the utility to do the work. The volmake utility, in
contrast, makes use of a usage-type-specific utility only to
verify the state of a volume, and its associated plexes and
subdisks, and to filter the initial states for all fields in
volumes, plexes, and subdisks. With volmake, the switchout
utility makes the actual changes by itself.
Usage-type-independent administrative utilities are:
voladm Administrates the state of the volume daemon
voledit Makes usage-type-independent changes to
configuration records
voliod Starts, stops, and reports on volume error
daemons, and volume log I/O daemons
volprint Prints configuration records
voltrace Prints tracing and statistics information
volstat Prints statistics information for volume devices
The fundamental utility for the Volume Manager is the Volume
Manager configuration daemon (vold). This utility
initializes the Volume Manager configuration, and is called
by other utilities to query and make changes to the
configuration. Typically, vold is started as part of system
initialization and is never started again unless the volume
daemon dies from a signal or exits after encountering a
serious error.
ARGUMENT CONVENTIONS
Many Volume Manager utilities provide the following command
line syntax:
utility [- options] keyword [arg ...]
The keyword argument selects a specific operation. Because
the keyword is an operand and not an option, any options
(arguments beginning with - that specify boolean flags or
optional values) must precede the keyword argument.
All Volume Manager utilities that communicate with the
volume daemon (that is, all utilities other than the vold
itself) take an extra, otherwise undocumented, option: -R.
This option is used in the form:
-R rendezvous_point
to specify a specific rendezvous point to use for connecting
Page 2 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
to the volume daemon. This option may be useful in the
process of porting the Volume Manager, because it allows the
use of utilities with private versions of vold that are not
the real vold. Outside of this use, the option is not
generally useful. For more information on rendezvous
points, see volsetrendezvous(3X).
SYNOPSIS FOR FSGEN AND GEN USAGE-TYPES
volinfo
volmake
volmend
volplex
volsd
volume
FSGEN USAGE-TYPE DESCRIPTION
The fsgen volume-usage-type for the Volume Manager provides
support for single-plex and multiple-plex volumes that
contain file systems, or that have contents with an
identifiable modification timestamp. Through the use of
this modification timestamp, the start operation of the
volume utility can decide which of several plexes in a
volume is the most recent. The primary purpose of this
capability is to prevent the use of a plex that was detached
before a system failure for reviving the remaining plexes in
a volume.
This release of the Volume Manager supports the s5 and ufs
file system types. For s5 and ufs, the timestamp is taken
from the superblock. However, this timestamp is not updated
after every change. As a result there is a small
possibility where-between an I/O error to a disk that causes
the kernel to detach a plex and a system failure-a
subsequent start operation will choose the plex with the I/O
error. However, the possibility of this situation occurring
is small in comparison with the frequency of I/O errors on
modern disk drives.
The fsgen usage-type also supports logging of blocks that
are to be changed. If the block change logging feature is
used, then selection of the most up-to-date plex reduces the
likelihood that an inconsistent or out-of-date plex will be
chosen on restart of a failed disk or system crash. The
failing I/O that causes a plex to detach will have logged
the successful write to an alternate plex. The log-recovery
feature of block change logging then selects that plex to
use as the most up-to-date plex from which to recover.
In addition, use of logging eliminates the need to
completely copy all blocks of one plex to another when
restarting a multiple-plex volume after a system failure.
Instead, only those blocks listed as being in transition are
Page 3 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
copied. However, logging affects normal run-time
performance by introducing extra disk writes.
The utilities provided for the fsgen usage-type should be
executed from other utilities provided with the Volume
Manager, and should not be used directly. For a discussion
of the interface between these switchout operational
utilities (the utilities executed directly by a system
administrator or by OA&M) and the fsgen utilities, see
volinfo(1M), volmake(1M), volmend(1M), volplex(1M),
volsd(1M), and volume(1M).
GEN USAGE-TYPE DESCRIPTION
The gen volume-usage-type for the Volume Manager provides
generic support for single-plex and multiple-plex volumes.
No assumptions are made about the contents of the volume, so
the capabilities are limited for multiple-plex volume
recovery after a system failure.
The gen usage-type is provided with the Volume Manager for
situations where no other usage-type is appropriate, or for
situations where the contents of a volume are rewritten
after a reboot. Under most circumstances, if a volume
contains a file system or database for which a specific
usage-type exists, then that usage type should be used
instead. If a volume contains a file system for which no
specific usage-type exists, but for which a volverify
utility exists (see the fsgen volume(1M) manual page), then
the fsgen usage-type should normally be used.
The gen usage-type does provide special support for volumes
with contents that do not need to be consistent across a
reboot. An example in which gen usage-type support would be
appropriate concerns the /tmp file system. It is common for
the /tmp file system to be recreated, with mkfs(1M), after a
reboot. It may also be appropriate to put the /tmp file
system on a two-plex volume to increase throughput of read
operations. However, there is no need to revive one plex
from the other plex, for a volume start, if the contents are
going to be recreated. The gen-type volume start operation
supports a norecov operation for this.
The gen usage type also supports logging of blocks that are
to be changed. If this feature is used, then knowledge of
the volume contents are not necessary to perform proper plex
recovery after a system failure. In addition, use of
logging eliminates the need to completely copy all blocks of
one plex to another, when restarting a multiple-plex volume
after a system failure. Instead, only those blocks listed
as being in transition will be copied. However, logging
affects normal run-time performance by introducing extra
disk writes.
Page 4 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
The utilities provided for the gen usage-type should be
executed from other utilities provided with the Volume
Manager, and should not be used directly. For a discussion
of the interface between these switchout operational
utilities (the utilities executed directly by a system
administrator or by OA&M) and the gen utilities, see
volinfo(1M), volmake(1M), volmend(1M), volplex(1M),
volsd(1M), and volume(1M).
OPERATIONAL STATES USED BY FSGEN AND GEN
The usage-type-specific utilities for the gen usage-type
store permanent state information in the plstate field of
plex configuration records associated with gen-type volumes.
The fsgen usage-type-specific utilities perform the same
function with regard to fsgen-type volumes. This state is
used to track state transitions that are important for
deciding how plex consistency should be handled.
The plex states used by the fsgen and gen usage-types are:
CLEAN The volume was shut down cleanly using the stop
operation of the volume utility. If a set of
plexes associated with a volume are CLEAN, then
those plexes are considered consistent by a
subsequent volume start operation.
ACTIVE Indicates that a plex is available for active use
by the volume, or that the plex may have been in
active use before a system failure. The volume
start operation sets plex states to ACTIVE and
enables them. In a multiple-plex volume, the
start operation uses existing ACTIVE states as an
indication that the contents of the ACTIVE plexes
may not be consistent.
Under normal operation, plexes may become
inconsistent because a write did not complete on
all plexes before a system failure, but did
complete on at least one. Under unusual
circumstances, plexes may become inconsistent
because of an I/O error. In the case of an I/O
error, the kernel may detach a plex, thus
preventing future I/O to the plex. However, this
state is not communicated directly to the
permanent configuration records.
STALE The plex contents are not consistent relative to
other plexes associated with the volume. The plex
must be revived before it can fully participate in
normal volume I/O. The volume stop operation sets
states for detached plexes to STALE to prevent
subsequent start operations from directly enabling
Page 5 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
the plex without revival. A subsequent volume
start operation attempts to revive plex from other
plexes associated with the volume. The volplex
det operation also sets the state for plexes that
it detaches to STALE.
EMPTY If the plexes associated with a gen-type volume
are all EMPTY, then no assumptions can be made
about the contents of the volume. After a volume
is created by volmake, the state of its associated
plexes are set to EMPTY. Until the volume is
initialized with a volume init operation, the
volume cannot be started with the volume start
operation.
OFFLINE The plex was disabled by the off operation of the
volmend utility.
TEMP This marks a plex that was temporarily associated
with an already-started volume for an extended
operation. If a plex is in this state when a
system failure occurs, then the operation does not
complete. For this reason, the volume start
operation dissociates such plexes.
TEMPRM This marks a plex that was created temporarily for
an extended operation. If a plex is in this state
when a system failure occurs, then the operation
does not complete. For this reason, the volume
start operation dissociates and removes such
plexes.
In accordance with the fast startup capability provided with
the gen usage-type, if -o norecov is given as an option to
the volume start operation, then STALE and ACTIVE plexes are
treated as equivalent to CLEAN plexes.
State Transitions
The following table lists the persistent utility states and
the utility operations that can be used to convert a plex
from one state into another state. It also notes any
restrictions that apply.
Page 6 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
Plex State Transition Table
delim $$ gfont 4
+----------+-----------------------------------------------------------------+
| | To State |
|From State|CLEAN |ACTIVE |STALE |EMPTY |OFFLINE|
==============================================================================
| CLEAN |n.a. |start[2] |fix stale[2]|fix empty[2] |off[1] |
+----------+--------------+--------------+------------+--------------+-------+
| | | |stop | | |
| ACTIVE |stop |n.a. |start[2] |fix empty[1,2]|off[1] |
| | | |fix stale[2]| | |
+----------+--------------+--------------+------------+--------------+-------+
| | |volplex att[4]| | | |
| STALE |fix clean[2,3]|fix active[2] |n.a. |fix empty[2] |off |
| | | | | | |
+----------+--------------+--------------+------------+--------------+-------+
| EMPTY |init[2,3] |init[2] |init |n.a. |off |
+----------+--------------+--------------+------------+--------------+-------+
| OFFLINE |n.a. |volplex att[4]|volmend on |fix empty[2] |n.a. |
+----------+--------------+--------------+------------+--------------+-------+
1. Use of -o force is required.
2. The volume must be disabled.
3. The volume must not have other CLEAN plexes.
4. The volume must have at least one ACTIVE plex
and must be enabled.
delim off gfont I
The various fix operations referenced in this table refer to
use of the fix keyword with the volmend utility.
Also, the start, stop, and init operations are performed by
the volume utility, and the off operation is performed by
the volmend utility.
FSGEN AND GEN VOLUME ERROR POLICIES
In the following description, the term ``complete plex'' is
used to refer to a plex that is compact and is at least as
long as a volume. A compact plex is one that has a subdisk
mapped for every block in the address space of the plex. An
incomplete plex is a plex that is either sparse or is not as
large as the associated volume.
The fsgen and gen usage-types always set the error-handling
policy for volumes to V_GEN_DET_SPARSE. This error policy
has the following effects:
1. For a volume that has only one plex in use, any I/O
Page 7 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
error results in failure of the operation, but does not
change the state of the volume or its plexes.
2. For a volume that has more than one complete plex and
no incomplete plexes, an I/O error to a plex results in
that plex being detached. However, if detaching a plex
would result in no usable plexes remaining associated,
then at least one plex is left attached and a failure
is returned for all future I/O errors.
3. For a volume that has one or more complete plexes, and
one or more incomplete plexes, an I/O error to a plex
results in that plex being detached. However, if
detaching a complete plex would result in no complete
plexes remaining, then all incomplete plexes that
contain blocks in the same address range as the I/O
error is detached, and a failure is returned for all
future I/O errors.
The reason for policies 2 and 3 is to prevent a non-
persistent I/O error from resulting in plexes having a
different version of the volume's contents. The only action
that the virtual disk driver can take without intervention
by a utility is to stop doing I/O to a plex (i.e., detach
the plex). Thus, the goal is to detach plexes that have
failures, so that future volume I/O is left to plexes that
do not have failures.
Policy 3 is complicated by the fact that detaching all
complete plexes would result in a volume with blocks that
are not mapped by any usable plex. If an I/O failure
occurred to a complete plex, and not to an incomplete plex,
then detaching the complete plex would leave some blocks
unmapped, while leaving both plexes attached could result in
silent data incompatibilities between the two plexes. The
solution is to detach the incomplete plex. This leaves the
I/O failure in place, unless the failure is not persistent.
However, if a block with an I/O failure is not mapped by an
incomplete plex, then detaching it is not necessary, because
future volume reads of that block will not be inconsistent,
with only the complete plex being able to satisfy requests
to that block. This allows parts of a volume to be
replicated either for redundancy reasons or for increased
performance, without I/O failures in other regions
eliminating that redundancy or performance increase.
Multiple-plex volumes work well with most modern disk
drivers to prevent the need for returning I/O failures or
detaching plexes. Most disk drivers reassign bad blocks if
a write error is encountered. However, if a disk driver
reassigns a block on a read error, then a future read does
Page 8 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
not return valid results, because the disk driver cannot
know what the block should contain when the block number is
reassigned. To aid disk drivers, if the writeback flag is
on (see voledit(1M)), and if a read from one plex encounters
an error, the virtual disk driver reads a block from an
alternate plex and rewrites it. This allows the disk driver
to safely reassign the bad block, because the data the block
should contain is known.
USE OF UTILITY FIELDS WITH FSGEN AND GEN
The tutil[0] fields, for volumes, plexes and subdisks are
used to mark operations performed in multiple transactions.
For example, when data is to be copied for an operation
(such as for volplex att or volplex mv), a transaction
before the copy sets the tutil[0] field for any relevant
plexes, and a second transaction clears the tutil[0] field
after the operation completes.
The fsgen and gen utility sets do not use the additional
tutil fields. These utility sets only use the putil fields
to prevent associations of plex and subdisk records. If the
putil[0] field for an unassociated plex is not empty, then
the volplex att refuses to associate it. Similarly, the
volsd assoc operation refuses to associate a subdisk that
has a nonempty putil[0] field.
Higher-level utilities are free to use the additional
utility fields. The putil[0] field for volumes and for
associated plex and subdisk records are reserved for future
use by the fsgen and gen usage-types.
Volume tutil[0] Field Values
Most extended operations for the fsgen and gen usage-types
involve copying data from one plex, or from a volume, onto
one or more plexes. More than one such operation can occur
simultaneously, as long as the operations do not involve the
same plex or subdisk records.
The volume tutil[0] field keeps track of the number of
plexes involved as the destination of extended operations.
When the first such operation starts, it sets the tutil[0]
field for the volume record to ATTnumber, where number is
the count of destination plexes. Subsequent operations
increase the number that follows ATT by the number of plexes
involved. As each operation completes, this number is
decreased by the number of involved plexes. When this
number reaches zero, the tutil[0] field is cleared.
For the fsgen usage-type, there are five additional values
that may be stored in the volume tutil[0] field:
ACTIVE Used when a volume is being set to active by the
Page 9 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
volume init active operation. This state is only
necessary when one or more plexes in the volume
have a log subdisk.
ZERO Used when volume contents are being cleared by the
volume init zero operation.
START Used when a multiple-plex volume is being started
after a system failure. Before the volverify
utility can be used to read the modification
timestamp for a plex, the plexes must be enabled,
and the volume kernel state must be set to
DETACHED. During this phase both the volume and
the plex tutil[0] fields are set to START.
ASLOG Used when the log type for a volume is being
changed implicitly, in a two-transaction
operation, by a volsd aslog operation. This is
used only when associating a log subdisk for a
volume with a logging type of UNDEF.
LOGATT Used when the log type for a volume is being
changed implicitly, in a two-transaction
operation, by a volplex att operation. This is
used only when attaching a plex with a log to a
volume with a logging type of UNDEF.
For the gen usage-type, there are two additional values that
may be stored in the tutil[0] field for a volume:
ACTIVE Used when a volume is being set to active by the
volume init active operation. This state is only
necessary when one or more plexes in the volume
have a log subdisk.
ZERO Used when volume contents are being cleared by the
volume init zero operation.
With both fsgen and gen, an attach operation cannot occur if
the volume tutil[0] field is not clear and does not begin
with ATT. Most other operations cannot occur if the volume
tutil[0] field has any value other than an empty string.
Plex tutil[0] Field Values
These are the possible values that both the fsgen and gen
usage-types store in plex tutil[0] fields:
ATT The plex is being attached by an extended volplex
att operation.
CP The plex is the destination of a copy for the
volplex cp operation.
Page 10 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
MVSRC The plex is the source of a plex move for the
volplex mv operation.
MVDST The plex is the destination of a plex move for the
volplex mv operation.
SDASDST A subdisk is being associated with the plex in an
extended volsd assoc operation.
SDASTMP The plex is a temporary plex created for an
extended volsd assoc operation.
SDMV The plex is the permanent plex involved with a
volsd mv operation.
SDMVTMP The plex is a temporary plex created for a volsd
mv operation.
These are the possible values that only the fsgen usage-type
stores in the plex tutil[0] fields:
START The plex is involved with a two-transaction volume
start operation.
DET The plex is the object of a volplex det operation.
This field value is used only if the volume and
plex are both enabled, and the volume device is
open.
DIS The plex is the object of a volplex dis operation.
This field value is used only if the volume and
plex are both enabled, and the volume device is
open.
Subdisk tutil[0] Field Values
These are the possible values that the fsgen and gen usage-
types store in subdisk tutil[0] fields:
ASSOC The subdisk is being associated in an extended
volsd assoc operation.
SDMVSRC The subdisk is the source of a subdisk move for
the volsd mv operation.
SDMVDST The subdisk is the destination of a subdisk move
for the volsd mv operation.
COMMON FSGEN AND GEN USAGE-TYPE OPTIONS
A small set of conventions exist in the gen usage-type for
options that can be specified with the -o option letter.
These are options that are recognized in an appropriate
context:
Page 11 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
force Force an operation that is not normally performed
as part of the operations model of the Volume
Manager. Forcing an operation may have adverse
effects on data. -o does not force operations
that put the configuration into an unsupported
state.
iosize=size
Specify the number of sectors to copy or write in
one volume or plex I/O system call. This option
is passed when one fsgen utility calls another,
such as when the volume utility calls the volplex
utility to revive any STALE plexes.
The default I/O size is 32 kilobytes (Kb). The
I/O size value is silently truncated to 128Kb
which is the size of VOL_MAXSPECIALIO in the
include file sys/vol.h. An I/O size must be an
integer multiple of the system sector size, which
is 512 bytes for the reference port of of the
Volume Manager. A large I/O size generally
increases the speed of the operation at the
expense of regular volume I/O. Smaller I/O sizes
decrease memory requirements for the operation and
have a smaller impact on throughput of regular
volume I/O.
An I/O size can be specified using a C-style
decimal, hexadecimal, or octal number, and can be
given a suffix of s, b, k, m, or g to indicate
sectors (the default), 512-byte blocks, kilobytes,
megabytes, or gigabytes. This suffix can be in
upper- or lowercase. See volsscan(3X) for more
information.
slow[=iodelay]
Reduce the system performance impact of an attach,
move, or copy operation for volsd assoc, volsd mv,
volplex att, volplex cp, volplex mv, or volume
start. The plex-to-plex copies required for these
operations can have a serious impact on I/O
throughput of other processes using the affected
disk drives. To reduce this impact, at the
expense of the plex-to-plex copy speed, the slow
option introduces a delay of milliseconds between
each individual I/O request (iosize defines the
size of each I/O request). Either specify an
explicit number of milliseconds, or a system
default is used.
FSGEN AND GEN USAGE-TYPE-DEPENDENT OPERATIONS
For complete details on the use of fsgen and gen usage-
Page 12 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
type-dependent operations, see the specific manual page for
the appropriate utilities.
Volume Initialization Operations
The state for a newly created volume must be initialized
with the volume init operation before the volume can be used
with the normal volume start/volume stop cycle. The various
init operations can be used only if all associated plexes
are EMPTY.
These are the recognized invocations of the volume init
operation:
volume init clean vol [ plex ]
Set the state for one plex associated with the
volume to CLEAN, so that the given plex is used to
revive any other plexes in a subsequent volume
start operation. The plex operand need not be
specified if only one plex is associated with the
volume.
volume init active vol
Enable the volume and its associated plexes, and
set the state for all plexes to ACTIVE. This
operation can be considered a combination of
setting all associated plexes to CLEAN and then
starting the volume.
volume init enable vol
Enable the volume and its associated plexes, but
leave the plex states defined as EMPTY.
volume init zero vol
Enable the volume and its associated plexes, then
write zeroes for the length of the volume. After
the operation completes (assuming that there are
no I/O errors), all associated plexes are set to
ACTIVE.
Additional Field-Clearing Operations
The fsgen and gen usage-types support one additional volmend
clear operation that is not mentioned in the usage-type-
independent volmend(1M) manual page. This operation is:
attnumber This operation can be applied only to volume
records. It decreases the attach count stored in
the volume tutil[0] field. If the count reaches
or drops below zero, then the tutil[0] field is
cleared.
Volume and Plex State fix Operations
The fsgen and gen usage-types allow the volmend fix
Page 13 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
operation only on disabled volumes.
The following are the recognized invocations of the volmend
fix operation:
volmend fix clean plex
Set the state for the plex to CLEAN. This can be
applied only under limited circumstances. See the
volmend(1M) manual pages for details.
volmend fix active plex
Set the state for a plex to ACTIVE. This can be
applied only to plexes that are STALE.
volmend fix stale plex
Set the state for a plex to STALE. This can be
applied only to plexes that are CLEAN or ACTIVE.
volmend fix empty volume
Set the state for all plexes associated with a
volume to EMPTY. Before the volume can
participate in the normal volume start/volume stop
cycle, the volume state must be reinitialized with
volume init.
oem-Keyword Operations
The fsgen and gen usage-types do not support any additional
operations through the oem keywords that are available in
the volmend, volplex, volsd and volume operational
utilities.
FSGEN AND GEN EXIT CODES
The fsgen and gen utilities may return additional exit codes
that are specific to the fsgen or gen volume-usage-type.
These exit codes are listed in the include file volgen.h,
for use by C programs. For shell scripts, these are the
extended exit codes for fsgen:
(32) VEX_FSGEN_BADCNFG
The configuration of records associated with a
volume is not consistent with the possible
configurations that can be generated by the fsgen
usage-type.
(33) VEX_FSGEN_STATE
The state of a plex prevents the operation from
succeeding.
(34) VEX_FSGEN_GEOM
The pattern of mapped and unmapped regions between
a set of plexes prevent an operation from
succeeding.
Page 14 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
(35) VEX_FSGEN_SPARSE
An incomplete plex (one that is either sparse or
is not as large as the associated volume) prevents
an operation from succeeding.
(36) VEX_FSGEN_BADLOGS
This error is returned by volume start when log
read failures, or logs with invalid contents,
prevent a volume from starting.
(40) VEX_FSGEN_NO_FSTYPE
The file system type for a volume cannot be
determined, either from the vfstype field of the
volume record, or by executing the fstype utility.
This is returned only by the volume start
operation.
(41) VEX_FSGEN_BAD_FSTYPE
The file system type for a volume does not have an
accompanying volverify utility. See the fsgen
information under the volume(1M) manual page for
details on the volverify utility.
For shell scripts, these are the extended exit codes for
gen:
(32) VEX_GEN_BADCNFG
The configuration of records associated with a
volume is inconsistent with the possible
configurations that can be generated by the gen
usage-type.
(33) VEX_GEN_STATE
The state of a plex prevents the operation from
succeeding.
(34) VEX_GEN_GEOM
The pattern of mapped and unmapped regions between
a set of plexes prevents an operation from
succeeding.
(35) VEX_GEN_SPARSE
An incomplete plex (one that is either sparse or
is not as large as the associated volume) prevents
an operation from succeeding.
(36) VEX_GEN_BADLOGS
This error is returned by volume start, when log
read failures, or logs with invalid contents,
prevent a volume from starting.
SEE ALSO (FSGEN AND GEN)
Page 15 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
The fsgen and gen sections of volinfo(1M), volmake(1M),
volmend(1M), volplex(1M), volsd(1M), volume(1M), and
volsscan(3X).
EXIT CODES
The majority of the Volume Manager utilities use a common
set of exit codes, which can be used by shell scripts or
other types of programs to react to specific problems
detected by the utilities. For C programmers, these exit
status codes are defined in the include file volclient.h.
The number and macro name for each distinct exit code is
described below. Shell script writers must directly compare
against the numbers specified.
(0) VEX_OK
The utility is not reporting any error through the exit
code.
(1) VEX_USAGE
Some command line arguments to the utility were
invalid.
(2) VEX_SYNTAX
A syntax error occurred in a command or description, or
a specified record name is too long or contains invalid
characters. This code is returned only by utilities
that implement a command or description language. This
code may also be returned for errors in search
patterns.
(3) VEX_NOVOLD
The volume daemon does not appear to be running.
(4) VEX_IPC
An unexpected error was encountered while communicating
with the volume daemon.
(5) VEX_OSERR
An unexpected error was returned by a system call or by
the C library. This can also indicate that the utility
ran out of memory.
(6) VEX_LOST
The status for a commit was lost because the volume
daemon was killed and restarted during the commit of a
transaction, but after restart the volume daemon did
not know whether the commit succeeded or failed.
(7) VEX_UTILERR
The utility encountered an error that it should not
have encountered. This generally implies a condition
that the utility should have tested for but did not, or
Page 16 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
a condition that results from the volume daemon
returning a value that did not make sense.
(8) VEX_TIMEOUT
The time required to complete a transaction exceeded 60
seconds, causing the transaction locks to be lost. As
most utilities will reattempt the transaction at least
once if a timeout occurs, this usually implies that a
transaction timed out two or more times.
(9) VEX_TIMEOUT_DIS
The processing of a transaction commit request timed
out after five minutes, causing the volume to set the
state for one or more data-locked volumes to DETACHED.
(10) VEX_CHANGED
A change made to the database by another process caused
the utility to stop. This code is also returned by a
usage-type-dependent utility if it is given a record
that is associated with a different usage-type. If
this situation occurs when the usage-type-dependent
utility is called from a switchout utility, then the
database was changed after the switchout utility
determined the proper usage-type to invoke.
(11) VEX_NOENT
A requested subdisk, plex, or volume record was not
found in the configuration database. This may also
mean that a record was an inappropriate type.
(12) VEX_EXIST
A name used to create a new configuration record
matches the name of an existing record.
(13) VEX_BUSY
A subdisk, plex, or volume is locked against concurrent
access. This code is used for inter-transaction locks
associated with usage-type utilities. The code is also
used for the dissociated plex or subdisk lock
convention, which writes a non-blank string to the
tutil[0] field in a plex or subdisk structure to
indicate that the record is being used. This exit code
may also be returned if a plex or volume is opened or
mounted, or if a subdisk or plex is part of an open
plex or volume. Some operations cannot be performed on
opened or mounted objects.
(14) VEX_NOUSETYPE
No usage-type could be determined for a utility that
requires a usage type.
(15) VEX_BADUSETYPE
Page 17 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
An unknown or invalid usage-type was specified.
(16) VEX_ASSOC
A plex or subdisk is associated, but the operation
requires a dissociated record.
(17) VEX_DISASSOC
A plex or subdisk is dissociated, but the operation
requires an associated record. This code can also be
used to indicate that a subdisk or plex is not
associated with a specific plex or volume.
(18) VEX_LAST
A plex or subdisk was not dissociated because it was
the last record associated with a volume or plex.
(19) VEX_TOOMANY
Association of a plex or subdisk would surpass the
maximum number that can be associated to a volume or
plex.
(20) VEX_INVAL
A specified operation is invalid within the parameters
specified. This code is returned when an attempt is
made, for example, to split a subdisk on a striped
plex, or to use a split size that is greater than the
size of the plex.
(21) VEX_IOERR
An I/O error was encountered that caused the utility to
abort an operation.
(22) VEX_NOPLEX
A volume involved in an operation did not have any
associated plexes, although at least one was required.
(23) VEX_NOSUBDISK
A plex involved in an operation did not have any
associated subdisks, although at least one was
required.
(24) VEX_UNSTARTABLE
A volume could not be started by the volume start
operation, because the configuration of the volume and
its plexes prevented the operation.
(25) VEX_STARTED
A specified volume was already started.
(26) VEX_UNSTARTED
A specified volume was not started. For example, this
code is returned by the volume stop operation if the
Page 18 (printed 1/21/92)
volintro(1M) Volume Manager Utilities volintro(1M)
operation is given a volume that is not started.
(27) VEX_DETACHED
A volume or plex involved in an operation is in the
DETACHED state, thus preventing a successful operation.
(28) VEX_DISABLED
A volume or plex involved in an operation is in the
DISABLED state, thus preventing a successful operation.
(29) VEX_ENABLED
A volume or plex involved in an operation is in the
ENABLED state, thus preventing a successful operation.
(30) VEX_UNKNOWN
An unknown error was encountered. This code may be
used, for example, when the volume daemon returns an
unrecognized error number.
(31) VEX_OPEN
An operation failed because a volume or plex device was
open or mounted, or because a subdisk was associated
with an open or mounted volume or plex.
Exit codes greater than 32 are reserved for use by usage-
types. Codes greater than 64 can be reserved for use by
specific utilities.
SEE ALSO
voladm(1M), vold(1M), voledit(1M), volinfo(1M), voliod(1M),
volmake(1M), volmend(1M), volplex(1M), volprint(1M),
volsd(1M), volstat(1M), voltrace(1M) and volume(1M).
For information about other aspects of the Volume Manager
see volintro(3X), vol(7) volconfig(7), voliod(7), and
volevent(7).
Page 19 (printed 1/21/92)