volsd(1M) Volume Manager Utilities volsd(1M)
NAME
volsd - Performs Volume Manager operations on subdisks
SYNOPSIS
volsd [ -U usetype ] [ -o useopt ] [ -V ] [ -v vol ] [ -l offset ]
assoc plex sd ...
volsd [ -U usetype ] [ -o useopt ] [ -V ] [ -v vol ] aslog plex sd
volsd [ -U usetype ] [ -o useopt ] [ -V ] [ -v vol ] [ -p plex ]
dis sd ...
volsd [ -U usetype ] [ -o useopt ] [ -V ] [ -s size ] [ -v vol ]
[ -p plex ] split sd newsd newsd2
volsd [ -U usetype ] [ -o useopt ] [ -V ] [ -v vol ] [ -p plex ]
join sd1 sd2 ... newsd
volsd [ -U usetype ] [ -o useopt ] [ -V ] [ -v vol ] [ -p plex ]
mv oldsd newsd
volsd [ -U usetype ] [ -o useopt ] [ -V ] [ -s size ] [ -v vol ] [ -p
plex ] [ -l offset ]
DESCRIPTION
The volsd utility performs Volume Manager operations on
subdisks and on plex-and-subdisk combinations. The first
operand is a keyword that determines the specific operation
to perform. The remaining operands specify the
configuration objects to which the operation is to be
applied.
These are the recognized operation keywords:
assoc
Associate each named subdisk operand with the specified
plex. If plex is associated with a volume, then the
operation is performed by a usage-type utility
appropriate for the volume. Otherwise, the operation
is performed by the utility for the gen volume-usage-
type.
aslog
Associate the specified subdisk with the specified
plex. Associate the subdisk as a log area for the
plex. If plex is associated with a volume, then the
operation is performed by a usage-type utility
appropriate for the volume. Otherwise, the operation
is performed by the utility for the gen volume-usage-
type.
dis Dissociate each specified subdisk from the plex that it
is associated with. If that plex is associated with a
volume, then the operation is performed by a usage-type
utility appropriate for that volume. Otherwise the
operation is performed by the utility for the gen
volume-usage-type. If more than one usage-type is
represented by the sd operands, then more than one
Page 1 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
usage-type utility is invoked.
split
Split the subdisk sd into two subdisks that reside on
the same section of the same device. The first of the
two resultant subdisks have a length of size, and the
second takes up the remainder of the space used by the
original sd subdisk object. If both newsd and newsd2
are specified, then the resultant subdisks are newsd
and newsd2. If a newsd2 operand was not specified,
then the resultant subdisks are sd and newsd.
If subdisk sd is associated with a plex that is
associated with a volume, the operation is performed by
a usage-type utility appropriate for the volume.
Otherwise, the operation is performed by the utility
for the gen volume-usage-type.
join Join the subdisks named with the sd operands to form a
new subdisk, newsd. The sd operands must specify
subdisks that represent contiguous sections of the same
device. At the end of the operation, the sd
configuration objects are removed. The newsd operand
can have the same name as one of the sd operands.
If the first sd operand is a subdisk that is associated
with a plex that is associated with a volume, then a
usage-type utility appropriate for that volume is used.
Otherwise the operation is performed by the utility for
the gen volume-usage-type.
mv Move the contents of oldsd onto newsd. Also
dissociates oldsd from the plex it is associated with,
and associate newsd with that plex. The action is
carried out by a usage-type utility appropriate for the
volume to which the plex is associated. The utility
fails if oldsd is not associated with a plex that is
associated with a volume. Also, newsd cannot be
associated already.
NOTE
The volsd command may take as much time to complete as a dd
command.
OPTIONS
The following options are recognized:
-U usetype
Force the operation to be performed by the usage-type
utility for this usage-type.
-o useopt
Page 2 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
Give usage-type-specific options to the usage-type-
specific form of the utility.
-V Write a list of utilities that would be called from
volsd, along with the arguments that would be passed.
The utilities are not actually called, and no changes
are made to the volume configuration database.
-s size
Specify the size for the subdisk split operation. This
option is required for the split operation and is
ignored when used with other operations. A split 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.
-l offset
Specify the offset of a subdisk within a plex address
space. The prefix and suffix rules for -s size are
also applied to offset. This option is used only by
the assoc operation and is ignored when used with other
operations.
-v vol
Require that a specified plex be associated with this
volume or that a subdisk be associated with a plex that
is associated with this volume or that a plex be
associated with this volume. This option applies to
the plex operand for the assoc operation, to the sd
operands for the dis, split, and join operations, and
to the oldsd operand for the mv operation.
-p plex
Require that a subdisk be associated with this plex.
This option applies to the sd operands for the dis,
split, and join operations, and to the oldsd operand
for the mv operation. A required plex is ignored for
the assoc operation.
USAGE-TYPE INTERFACE
The usage-type-specific volplex utilities perform the
actions that were requested by the user. Usage-type
utilities are called with the same options and keyword given
to the volsd switchout utility. The list of additional
operands passed to the usage-type utilities varies depending
upon the operation. In all cases described below, if a
usage-type is specified using the -U option letter, then the
utility for that usage-type is called directly, as long as
the operands conform to the operation synopsis.
Page 3 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
volsd assoc and volsd aslog
If the plex operand names an associated plex, then the
plex and sd operands are passed to the volsd utility
for the usage-type of the volume. If the plex operand
names an unassociated plex, then the plex and sd
operands are passed to the volsd utility for the gen
usage-type.
It is the responsibility of the usage-type-specific
utility to verify that all of the sd operands name
dissociated subdisks.
volsd dis
All of the sd operands must name associated subdisks.
The sd arguments are sorted into groups by usage-type.
For subdisks that are associated with associated
plexes, the usage-type of the volume is used. For
subdisks that are associated with dissociated plexes,
the gen usage-type is used. The volsd utility for each
represented usage-type is called once, with the sd
arguments appropriate for the usage-type.
volsd split
If the sd operand names a subdisk that is associated
with an associated plex, then the sd and newsd operands
are passed to the volsd utility for the usage-type of
the volume. If the sd operand names an unassociated
subdisk, or a subdisk associated with an unassociated
plex, then the sd and newsd operands are passed to the
volsd utility for the gen usage-type.
It is the responsibility of the usage-type-specific
utility to verify that newsd does not name an existing
record.
volsd join
If the first sd operand names a subdisk that is
associated with an associated plex, then the sd and
newsd operands are passed, in the order specified, to
the volsd utility for the usage-type of the volume. If
the first sd operand names an dissociated subdisk, or a
subdisk associated with an dissociated plex, then the
sd and newsd operands are passed to the volsd utility
for the gen usage-type.
It is the responsibility of the usage-type-specific
utility to check the appropriateness of the successive
sd operands and the newsd operand.
volsd mv
The oldsd operand must name a subdisk that is
associated with an associated plex. The volsd utility
Page 4 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
for the usage-type of the volume is called with the
oldsd and newsd operands.
It is the responsibility of the usage-type-specific
utility to verify that newsd is not associated.
The action, object, and arg operands are all passed to
the usage-type-specific utility, in the order
specified.
SYNOPSIS FOR FSGEN AND GEN USAGE-TYPES
volsd [ -U usetype ] [ -o useopt ] [ -v vol ] [ -l offset ]
assoc plex sd ...
volsd [ -U usetype ] [ -o useopt ] [ -v vol ] aslog plex sd
volsd [ -U usetype ] [ -o useopt ] [ -v vol ] [ -p plex ] dis sd ...
volsd [ -U usetype ] [ -o useopt ] [ -s size ] [ -v vol ] [ -p plex ]
split sd nsd [ nsd2 ]
volsd [ -U usetype ] [ -o useopt ] [ -v vol ] [ -p plex ]
join sd1 sd2 ... nsd
volsd [ -U usetype ] [ -o useopt ] [ -v vol ] [ -p plex ]
mv oldsd newsd
FSGEN AND GEN DESCRIPTION
The volsd utility for the fsgen and gen volume usage-types
performs operations on subdisks and on plex-and-subdisk
combinations. The first operand is a keyword that
determines the specific operation to perform. The remaining
operands specify the configuration objects to which the
operation is to be applied.
These are the recognized operation keywords:
assoc
Associate each named subdisk operand with the specified
plex. If the -l offset option is specified, then the
first subdisk is associated at the specified byte
offset within the plex. If the -l offset option is not
specified, then the first subdisk is associated at the
end of the plex. Subsequent subdisks are associated at
an offset directly following the preceding subdisk.
If plex is enabled and is associated with an enabled
volume that has other enabled, read-mode plexes, then
the volume is copied onto the subdisks using a
temporary plex before the subdisks are associated with
plex. This copy is performed using the ATOMICCOPY
volume ioctl. Such an operation requires that the
destination plex be in read-write mode. Also, the plex
utility state must be ACTIVE or EMPTY.
A unique temporary plex name is chosen by volsd. This
name is normally removed before the user sees it, but
Page 5 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
may need to be removed if the volsd operation is
interrupted before completion, and the cleanup
operation fails.
An attempt to associate a subdisk fails if the putil0
field for the subdisk is not empty. This makes it
possible to prevent use of a disk region by creating a
subdisk with a nonempty string stored in the subdisk's
putil0 field.
If an assoc operation is interrupted by a signal, then
an attempt is made to restore all affected records to
their original state, or to a state that is roughly
equivalent to their original state. If this attempt is
interrupted, such as through another signal, then the
user may need to perform some cleanup. A set of
commands to perform this cleanup is written to the
standard error before volsd exits.
If the destination plex is not enabled, or if it is the
only enabled read-mode plex associated with the volume,
then the subdisk is simply associated without an
intermediate copy operation. Subdisks can be
associated with a nonenabled plex only if the utility
state of the plex is EMPTY, STALE, or OFFLINE, or if
the plex is CLEAN and no other plexes associated with
the volume are CLEAN or ACTIVE.
The following applies only to the fsgen volume usage-
type: Subdisks cannot be associated from striped,
associated plexes. To change subdisk associations in a
striped plex associated with an fsgen volume, use the
volplex utility to dissociate the plex, make the
desired changes, and then use volplex to reattach the
plex. The fsgen usage-type cannot be used to associate
subdisks to a dissociated plex.
The following applies only to the gen volume usage-
type: If the destination plex is striped, then a
subdisk can be associated only if the plex is
dissociated. All subdisks associated with a striped
plex must have the same length and must have
association offsets that are a multiple of that common
subdisk length. Also a striped plex cannot be enabled
or set to the DETACHED kernel state if the plex has any
regions that are not backed by a subdisk.
aslog
Associate a subdisk to a plex as a log subdisks. A
plex cannot have more than one log subdisk. In
addition, the -l offset option is not relevant, because
log subdisks are not associated into the plex address.
Page 6 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
If the logging type of the volume is BLKNO, then the
logging subdisk must be at least 1 sector in length.
If the logging type of the volume is UNDEF, then the
logging type for the volume is changed to BLKNO.
Logging of volume changes is enabled when two or more
attached plexes have associated log subdisks.
If plex is enabled and is associated with an enabled
volume, then the subdisk is associated with a temporary
plex before it is associated with the plex. While
associated with the temporary plex, the log is updated
by calling the VOLLOGWRITE volume ioctl. For this
operation to take place, the utility state must be
ACTIVE or EMPTY.
A unique temporary plex name is chosen by volsd
operation. This name is normally removed before the
user sees it, but may need to be removed if the aslog
operation is interrupted before completion, and the
cleanup operation fails.
An attempt to associate a subdisk fails if the putil0
field for the subdisk is not empty. This makes it
possible to prevent use of a disk region by creating a
subdisk with a nonempty string stored in the subdisk's
putil0 field.
If an aslog operation is interrupted by a signal, then
an attempt is made to restore all affected records to
their original state, or to a state that is roughly
equivalent to their original state. If this attempt is
interrupted, such as through another signal, then the
user may need to perform some cleanup. A set of
commands to perform this cleanup is written to the
standard error before volsd exits.
If the destination plex is not enabled, or if it is the
only enabled read-mode plex associated with the volume,
then the subdisk is simply associated without an
intermediate log update operation. Subdisks can be
associated with a nonenabled plex only if the utility
state of the plex is EMPTY, STALE, or OFFLINE, or if
the plex is CLEAN and no other plexes associated with
the volume are CLEAN or ACTIVE.
The fsgen usage-type cannot be used to associate
subdisks to an dissociated plex.
dis Dissociate each specified subdisk from the plex to
which it is associated. The gen usage-type can be used
to dissociate subdisks from a dissociated plex. The
fsgen usage-type cannot be used to dissociate a subdisk
Page 7 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
from a nonassociated plex that is not associated with
any usage-type specific volume. The dis operation can
be used to dissociate logging subdisks; this applies to
both fsgen and gen.
If dissociating a subdisk would cause the last
complete, enabled, read-write plex associated with a
nondisabled volume to become sparse, then -o force must
be used to force the operation. If such a dissociation
would cause the number of sparse plexes to become
greater than 1, then the operation is not allowed at
all. For a disabled volume, a similar check is made
with respect to complete ACTIVE and CLEAN plexes.
Subdisks associated with the gen volume usage-type
cannot be dissociated from an associated striped plex.
Subdisks associated with the fsgen volume usage-type
that are not log subdisks cannot be dissociated from
striped, associated plexes. To change subdisk
associations in a striped plex associated with an fsgen
volume, use the volplex utility to dissociate the plex,
make the desired changes, and then use volplex to
reattach the plex.
split
Split the subdisk sd into two subdisks. If an nsd2
operand is specified, then the two subdisks created are
nsd and nsd2; otherwise, they are sd and nsd.
The first of the two resulting subdisks is identical
with sd except that it has a length of size, where size
is specified with the -s option letter. This is a
required option for the split operation. The second
subdisk created by the split operation is identical to
sd with the following exceptions:
1. The subdisk length is size sectors shorter in
length than the original sd record.
2. The device offset is size sectors higher than sd.
3. The plex association offset is size sectors higher
than sd.
The value of size cannot be zero and cannot equal or
exceed the original length of subdisk sd.
The plex to which sd is associated cannot have a layout
of PLSTRIPE, and logging subdisks cannot be split.
Also, the fsgen usage-type cannot be used to split a
dissociated subdisk or a subdisk that is associated
Page 8 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
with an dissociated plexes that is not associated with
any usage-type specific volume.
This operation fails if the putil0 field of the subdisk
is set to a non-empty string.
join Join the subdisks named with the sd operands to form a
new subdisk, nsd. The sd operands must specify
subdisks that represent contiguous sections of the same
device and that have contiguous plex offset addresses
in the same plex. This operation removes the sd
configuration records. The record of the new subdisk,
nsd, is identical to the first source subdisk record,
except that the length is the sum of the lengths for
all of the source subdisk records.
The plex to which the sd records are associated cannot
have a layout of PLSTRIPE, and logging subdisks cannot
be joined. Also, the fsgen usage-type cannot be used
only to join dissociated subdisks or subdisks that are
associated with dissociated plexes.
This operation fails if the putil0 field for any of the
subdisks is set to a non-empty string.
mv Copy the contents of oldsd onto newsd . Also
dissociates oldsd from the plex it is associated with,
and associates newsd with that plex at the same offset.
The mv operation can be performed only if oldsd is
associated with an associated plex, and newsd is not
associated. Neither the plex nor the volume to which
oldsd is associated can be disabled. The I/O mode for
the plex must be read-write.
A unique temporary plex name is chosen by volsd. This
name is not normally seen by the user, but may need to
be removed if the volsd operation is interrupted before
completion, and the cleanup operation fails.
The operation is performed by associating the
destination subdisk with the temporary plex, which is
then associated with the volume. The appropriate
subregion of the volume is then copied onto the
temporary plex using the ATOMICCOPY volume ioctl.
After the copy is complete, the old subdisk is
dissociated and removed, the new plex is associated
with the destination plex, and the temporary plex is
dissociated from the volume and removed.
This operation cannot be performed on a subdisk that is
associated with a plex whose layout is PLSTRIPE.
Page 9 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
If the size of the destination subdisk differs from
that of the source subdisk, then the force option must
be specified with the -o useopt string. The operation
still fails if the destination subdisk is larger than
the source subdisk and if the address range of the
destination would conflict with another subdisk that is
associated with the plex. The destination subdisk
cannot be larger than the source subdisk if the kernel
state of the volume or plex is DETACHED.
The operation fails if the destination subdisk is
smaller than the source subdisk and the operation would
cause the number of complete, enabled, read-mode plexes
to drop to zero, while leaving more than one
noncomplete, enabled, read-mode plex.
If such a move operation is interrupted by a signal,
then an attempt is made to restore all affected records
to their original state. If this attempt is
interrupted, such as through another signal, then the
user may need to perform some cleanup. A set of
commands to perform this cleanup is written to the
standard error before volsd exits.
FSGEN AND GEN OPTIONS
The following options are recognized:
-U usetype
For fsgen:
A usage-type name passed in from the switchout volsd
utility. If this option is specified then the value
for usetype must be fsgen.
For gen:
The gen usage-type volsd utility can be used by another
usage-type that has similar characteristics as long as
the name of the other usage-type is specified with this
option.
-o useopt
A list of options separated by comas and white space.
These options can be either a name, or a name and a
value separated by an equal sign. The recognized
usage-type options are
force
Force an operation that is not normally performed
as part of the operational model of Volume
Manager, and that may have adverse effects on
data.
iosize=size
Page 10 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
Specify the number of sectors to copy in each call
to the ATOMICCOPY volume ioctl. This can affect
the assoc and mv operations.
The default I/O size is 32 kilobytes. The I/O
size value is silently truncated to 128 kilobytes,
which is the size defined for VOLMAXSPECIALIO 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 assoc or
mv operation. 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 an
explicit number of milliseconds can be given, or a
system default is used.
-s size
Specify the size for the subdisk split operation. This
option is required for the split operation and is
ignored when used with other operations. A split 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.
The split size must be an integer multiple of the
system sector size.
Page 11 (printed 1/21/92)
volsd(1M) Volume Manager Utilities volsd(1M)
-l offset
Specify the byte offset of a subdisk within a plex
address space. The prefix and suffix rules for -s size
are also applied to offset. This option is used only
by the assoc operation and is ignored when used with
other operations.
The association offset must be an integer multiple of
the system sector size.
-v vol
Require that a specified plex be associated with this
volume or that a subdisk be associated with a plex that
is associated with this volume or that a plex be
associated with this volume. This option applies to
the plex operand for the assoc and aslog operations, to
the sd operands for the dis, split, and join
operations, and to the oldsd operand for the mv
operation.
-p plex
Require that a subdisk be associated with this plex.
This option applies to the sd operands for the dis,
split, and join operations, and to the oldsd operand
for the mv operation. A required plex is ignored for
the assoc operation.
FILES
/usr/lib/VxVM/type/usetype/volsd
Usage-type-specific utility for performing subdisk
operations.
/usr/lib/VxVM/type/gen/volsd
Usage-type-specific utility for the gen volume
usage-type.
EXIT CODES
The volsd 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), volsd(1M), volsscan(3X), vol(7), and
ioctl(2).
Page 12 (printed 1/21/92)