vol_pattern - Logical Storage Manager (LSM) disk group search specifica-
The vol_pattern search expression language can be used in volprint and
voledit, and with some Logical Storage Manager support library functions,
to locate Logical Storage Manager configuration records with particular
characteristics. Searches are limited to operation on one disk group at a
time. In the current release, search expressions are limited to volume,
plex, and subdisk recods. Search expressions cannot be applied to disk
group, disk media, or disk access records.
Search patterns provide an expression-based language for specifying record
attributes. In simple cases, patterns can be specified that match records
whose fields have specific values. In more complex cases, records can be
matched based on attributes of associated records.
Search patterns are expressions that do not have side effects (for example,
variables cannot be set or changed). Expressions evaluate either to true or
false. If evaluation of an expression within the context of a configuration
record yields a value of true, then the expression matches the record; oth-
erwise the expression does not match the record.
The search pattern language does not have operators that cause changes to
be made, and does not have a concept of local variables that can be set and
used within or between expressions.
Types of Expressions
Expressions in the pattern language are similar to expressions in awk(1).
Expressions can have the following types for constants, variables, and
A Boolean variable or expression is either true or false. Numbers and
strings can be used as truth values if the context requires a Boolean
value. For a number, zero implies false and nonzero implies true. For a
string, an empty string implies false and a nonempty string implies
A string is a literal string in quotes or a character array field from
a configuration record. Strings can be implicitly promoted to Boolean,
but are never promoted to other types. For example, a string-valued
field in a record that contains only digits cannot be compared with a
number. String literals are described later.
A number is an integer quantity. The maximum size for a number is the
largest size that may be used for values in configuration records. In
the reference porting base for the Logical Storage Manager, these
numbers are 32 bit signed numbers.
Numbers can be specified in decimal, octal, or hexadecimal with a suf-
fix to indicate the unit of the number when it indicates an object
length or offset. Hexadecimal numbers begin with 0x, octal numbers
begin with 0; otherwise numbers are in decimal. When used as a length,
numbers with no suffix are taken as sectors.
Defined suffix characters are: b for 512-byte blocks, s for sectors
(typically 512 bytes), k for kilobytes, m for megabytes, and g for
gigabytes. Suffix characters also can be specified in upper case.
Length numbers are actually defined in terms of sectors. As a result,
on a system with 512 byte sectors, 1k is the same as 2. Thus, the
tests for a record with 2 associated records, rather than 1024 associ-
An enumeration field is a number that represents one of the values for
a field that has symbolic names. The vol_pattern expression grammar
handles enumeration values exactly like numbers. Enumerations are usu-
ally only useful for comparing compatible enumeration field and
enumeration constants. For example, the enumeration field pl_layout
enumeration field is a number whose possible values are represented by
the symbols CONCAT and STRIPE.
A regular expression is a value, much like a regular expression in awk
or ed, that can be used to specify a pattern for matching strings. Reg-
ular expressions can only be used in the context of the Boolean ~ and
sequence numbers and record IDs
Each time a transaction is issued against a disk group configuration, a
64-bit configuration sequence number is increased. When a configuration
records is created or changed in a transaction, the record is stamped
with the configuration sequence number associated with that transac-
When a record is created, it is given a 64-bit record ID. These record
IDs are never reused within a disk group configuration.
Configuration sequence numbers and record IDs can be specified as con-
stants of the form number.number, where both numbers are specified in
Two higher-level types are also included, which can represent multiple
values of the same base type. These higher-level types are:
set A set is a multi-valued variable (an array). Sets are normally used
within the right-hand expression for the any and in operators. Refer-
ence to a set expression yields all of the currently valid members of
the set, of which there may be none.
A list is a set of expressions and sets within parenthesis that are
separated by commas. List expressions can only be used for the right-
hand expression of the in operator.
A pattern is an expression with the following components and operators, in
increasing order of precedence. Groups of operators described together have
the same precedence.
expr1 ? expr2 : expr3
This is a conditional expression. Expression expr1 is evaluated as a
Boolean value. If it has a truth value of true, then the value for the
conditional expression is the value of expr2, otherwise the value for
the conditional expression is the value of expr3.
expr1 || expr2
The logical or operator. Expressions expr1 and expr2 are evaluated as
Boolean expressions. If either expr1 or expr2 have a truth value of
true, the expression is true; otherwise, the value of the expression is
expr1 &&&& expr2
The logical and operator. Expressions expr1 and expr2 are evaluated as
Boolean expressions. If both expr1 and expr2 have a truth value of
true, the expression is true; otherwise, the value of the expression is
The expression expr is evaluated as a Boolean expression for all combi-
nations of elements for all sets within expr that represent sets. If
any of these combinations yields a truth value of true, then the value
of the any expression is true; otherwise, the value is false.
For example, pl_sd is a set defining the names of subdisk records that
are associated with a plex. The following expression searches for plex
records that have an associated subdisk on disk disk01:
expr in list
Expression expr is evaluated, and the resulting value is compared to
all of the values in list. If any of the values in list match expr,
then the value of the in expression is true; otherwise, the value is
false. The list can either be a list of expressions within parentheses
that are separated by commas, or it can be a single expression. If any
of the expressions in list represent sets, then the comparison is made
against all combinations of values in that set.
Type promotions are not performed on the expressions in list, or on
expr. Types for all these expression*Os must match exactly.
For example, the following expression searches for plexes that have
either a regular subdisk or a subdisk on disk disk01:
disk01 in (pl_sd.sd_disk,pl_log_sd.sd_disk)
expr ~ /regexp/
expr !~ /regexp/
The binary ~ and !~ operators are used to match string values against a
regular expression. The value of expr must be a string. For the ~
operator, if the value of expr matches the regular expression regexp,
then the value for the match expression is true; otherwise the value is
false. For the !~ operator, if expr matches regexp the result is false;
otherwise the result is true.
The / character in the regular expression must be escaped with \ if it
does not occur within a character range.
For example, to search for subdisks that are defined on a partition of
any device, use the following expressions:
sd_path ~ /^\/dev\/[^/]*e/
expr1 = expr2
expr1 != expr2
These expressions compare string, number, sequence number, record ID,
or Boolean values. If either expr1 or expr2 is a Boolean value, then
the other is promoted to a Boolean as well. For the = operator, if the
two values are equal then the result is true; otherwise, the result is
false. For the != operator, if the two values are equal, then the
result is false; otherwise, the result is true.
For consistency with awk(1) and many other languages, == is allowed as
an alias for the = operator.
expr1 << expr2
expr1 >> expr2
expr1 <<= expr2
expr1 >>= expr2
These expressions compare the magnitudes of numbers or sequence
numbers. They cannot be applied to any other types of expressions. The
result is a Boolean.
expr1 + expr2
expr1 - expr2
These expressions add or subtract two numbers, yielding another number.
expr1 / expr2
expr1 % expr2
These expressions multiply, divide, or take the modulo of two numbers,
yielding another number.
The unary + operator applied to any expression yields the value of that
expression. The unary - operator negates the value of a number-valued
The expression expr is evaluated as a Boolean expression. If its value
is true, then the value for the ! expression is false; otherwise, the
value for the ! expression is true.
expr . field-name
The expression expr is evaluated as a string expression. Its value is
used as the name of a record in the disk group configuration. If the
record exists, and if that record contains a field named field-name,
then the value of this expression is the value in that field within the
referenced record. If the record does not exist, or if the record does
not contain a field named field-name, then the behavior is context-
If this occurs within the context of an any or in operator, then the
next combination of values for the right-hand side of the any or in
operator is evaluated. If this occurs within the context of an &&&& or ||
operator, then the left or right-hand expression of that operator
yields false, whichever side the . operator occurs on. The innermost
any, in, &&&&, or || operator determines the context. If no such context
exists, then the result of the entire search pattern is that the record
being tested does not match the pattern.
The effect of this short-circuiting behavior is that an expression
which is found not to make sense because a record does not exist, or
does not contain a specific field, will cause that expression to be
false. The effect is similar to implicit asserts, which are described
later in this section under field name.
Parentheses can be used to override precedence rules.
A string, number, sequence number, or record ID literal, as defined in
the section Types of Expressions.
An assert is a special type of variable name that is true within the
context of a specific type of record. Outside of that context, an
assert causes the expression that it is in to be false. The scope of an
assert is the right or left-hand side of the smallest expression within
a || or &&&& operator. If an assert does not occur within a || or &&&&
operator, then the search pattern does not match the record being
evaluated. The names that specify asserts are vol, plex and sd which
specify volume, plex and subdisk records, respectively.
There is a set of symbolic constants that can be specified in search
patterns. For example, true and false are the two truth values. Also,
if a field within a record has a specific set of symbolic values, then
these symbolic values are available as numeric constants. See the sec-
tion titled Constants.
There is a small set of global variables that can be referenced in
search patterns. Such variables can be used within any context. See the
section titled Global Variables.
Referencing the name of a field in a configuration record yields the
value of that field within the configuration record being evaluated.
Not all field names are defined for all record types. If a field name
is referenced that is not valid in the context of the record type, then
the smallest expression on either side of a &&&& or || operator becomes
false. This is an implicit assert. For example, the following expres-
sion matches only volume records because the v_kstate field is only
defined for volume records:
Some fields in a record only make sense if another field contains a
specific value. For example, the pl_st_width field in plex records is
not defined unless the value of the pl_layout field is PL_STRIPE. These
cases are treated as implicit asserts.
The names of constants that are recognized within search patterns are:
true, yes, on
Constants representing Boolean true.
false, no, off
Constants representing Boolean false.
ROUND, PREFER, SELECT
The enumeration constants that represent values for the v_read_pol
field in volume records. The v_current_read_pol field can be set to
ROUND or PREFER. These constants can also be specified with a prefix of
V_ to match the enumeration values in the include file sys/vol.h.
DISABLED, DETACHED, ENABLED
The enumeration constants that represent values for the v_kstate field
in volume and plex records. These constants can also be specified with
a prefix of V_ or PL_.
NO_OP, FAIL_OP, DET_PL, FAIL_DET_PL, DET_VOL FAIL_DET_VOL,
GEN_DET, GEN_DET_SPARSE, GEN_FAIL, GEN_DET2
The enumeration constants that represent values for the v_r_all,
v_r_some, v_w_all, and v_w_some fields in volume records. These con-
stants can also be specified with a prefix of V_.
LOGUNDEF, LOGNONE, LOGDRL
The enumeration constants that represent values for the v_log_type
field in volume records. These enumeration constants can also be speci-
fied with a prefix of V_PFLAG_ to match the enumeration values in the
include file sys/vol.h.
The enumeration constants that represent values for the pl_layout field
in plex records. These constants can also be specified with a prefix of
RO, WO, RW
The enumeration constants that represent values for the pl_iomode field
in plex records. These enumeration constants can also be specified with
a prefix of PL_TFLAG_ to match the values in the include file
The value for a device number field indicating that the device number
The global variables that can be used within search patterns are:
config_tid or tid
The configuration sequence number of the disk group configuration.
util_num or nutil
The number of fields in a tutil or putil arrays in a volume, plex, or
subdisk structure. This is always 3, but it is treated as a global
Some fields can be found in all types of configuration records. These
fields can be referenced without a v_, pl_, or sd_ suffix, and do not
generate implicit asserts. These fields can be used either to name fields
in the record being evaluated, or as a field name reference for the .
A generic field name can be specified with a prefix of v_, pl_, or sd_ to
indicate that implicit asserts should be used and that the field requires a
context of a volume, plex, or subdisk record, respectively. Currently, use
of a prefix for a generic field name is ignored for the right-hand side of
a . operator.
The recognized generic field names are:
A set of strings representing all of the temporary utility fields.
tutil0 or t0
A string representing the first temporary utility field.
tutil1 or t1
A string representing the second temporary utility field.
tutil2 or t2
A string representing the third temporary utility field.
A set of strings representing all of the permanent utility fields.
putil0 or p0
A string containing the first permanent utility field.
putil1 or p1
A string containing the second permanent utility field.
putil2 or p2
A string containing the third permanent utility field.
name or n
A string containing the record name.
comment or c
A string containing the comment field.
len or l
A number representing the length of the volume, plex or subdisk.
A Boolean value indicating whether the volume, plex, or subdisk is
open. A subdisk is considered open of the volume or plex device for the
subdisk is open. A plex is considered open only if the plex device is
open. A volume is considered open if the volume or one of its plex
devices is open.
rid The record ID of the record being evaluated.
update_tid or update
The disk group configuration sequence number corresponding to the tran-
saction that created or that last modified the record.
A Boolean value indicating whether the record is locked in the current
transaction of the caller. This variable is not useful when used with
volprint or voledit. It is useful for C programs only.
Special fields exist that do not obey the prefix convention, but which
apply to more than one type of record. These are:
This is the name of a field to which a record is associated. In the
context of a plex or subdisk record, assoc yields the name of the
volume or plex to which the record is associated. If the record is not
associated, assoc yields an empty string. Use of assoc is not appropri-
ate in the context of a volume record. This causes an implicit assert
when applied to a volume.
This is the set of associated record names. In the context of a volume
or plex record, this yields the names of the associated plexes and sub-
disks, of which there may be none. This is not appropriate in the con-
text of a subdisk record. This causes an implicit assert when applied
to a subdisk.
This is the number of records in the aslist set. This causes an impli-
cit assert when applied to a subdisk.
Volume Record Fields
The fields that can be specified for volume records are:
A Boolean value indicating whether the record is locked within the
current transaction of the caller.
A Boolean value indicating whether the volume is locked against I/O
activity within the current transaction of the caller.
An enumeration field for the kernel-enabled state for the volume. This
can have one of the following values: DISABLED, DETACHED, or ENABLED.
v_r_all, v_r_some, v_w_all, v_w_some
These are numbers that represent the exception policies for the volume.
Each of these fields can have one of the following exception policy
values: NO_OP, FAIL_OP, DET_PL, FAIL_DET_PL, DET_VOL, FAIL_DET_VOL,
GEN_DET, GEN_DET_SPARSE, GEN_FAIL, or GEN_DET2.
A number representing a sequence number for the last error that
occurred on the volume.
The sequence number of the last transaction that detached the volume
due to a failure of some kind. This is also set when all copies of the
dirty region log for the volume are detached by I/O failures.
A string containing the usage type of the volume.
A string containing the file system type for the volume, as set by the
A string representing the usage-type-dependent state for the volume.
A Boolean value indicating whether the writeback-on-read-error policy
is turned on for the volume. This policy is set by default and can be
turned off or back on using voledit. See voledit(8) for more informa-
A Boolean value indicating whether volume writes are copied to a
private buffer in the kernel before being written to disk. See
voledit(8) for more information.
A Boolean value indicating whether the value of v_writecopy was speci-
fied explicitly by the administrator using volmake or voledit. If
v_specify_writecopy is false then the value for v_writecopy will be
derived from the configuration of the volume: v_writecopy will be
turned on if dirty region logging is in operation on the volume, and
will be turned off otherwise.
v_pl_num or v_nplex
A number representing the number of plexes associated with the volume.
v_pl_name or v_plex or v_plexes
The set of plex names that are associated with the volume.
An enumeration representing the read policy for the volume. This can
be one of the values ROUND, PREFER, or SELECT. The value SELECT indi-
cates that read policy will be adjusted to match the configuration of
the volume: if there is one associated striped plex, it will be pre-
ferred; otherwise the policy will be round-robin.
v_current_read_pol or v_creadpol
An enumeration representing the current read policy that is in effect
for the volume. This is the same as v_read_pol unless v_read_pol is
SELECT, in which case v_current_read_pol matches the chosen policy.
A string containing the preferred plex for the volume. This is only
defined if the value for v_current_read_pol is PREFER. Otherwise, use
of this variable causes an implicit assert.
The record ID of the preferred plex.
A number representing the minor number of the volume block and charac-
ter devices. This is the persistent device number for the volume. If
two volumes on the system have the same value for v_minor, then one of
the volumes will be given a different device number, which will be
reflected in v_bdev and v_cdev.
v_bdev and v_cdev
The block and character device numbers for the volume.
A Boolean value indicating whether the volume can use one of the
reserved minor numbers (minor numbers zero through four). The root and
swap usage types set this flag to allow them to grab minor numbers 0
and 1 for the root and swap volumes.
A number representing the user ID for the volume. There is currently no
way to represent a user name in a search pattern.
A number representing the group ID for the volume. There is currently
no way to represent a group name in a search pattern.
A number representing the file permission modes for the volume. There
is currently no way to represent a symbolic mode in a search pattern.
A number representing the length of logs associated with the volume, if
An enumeration representing the logging type for the volume. This can
have one of the following values: LOGUNDEF (no specific type speci-
fied), LOGNONE (no logging), or LOGDRL (dirty region logging).
A Boolean value that is true if logging is enabled for the volume. Log-
ging is enabled if the volume is enabled, and it has at least one asso-
ciated, enabled plex with an enabled, associated log subdisk.
Two numbers that together represent the most significant and least sig-
nificant long values for the current log serial number for a volume.
The log serial number, represented as a combined binary integer, is
incremented every time a new log is written for a volume that has log-
A Boolean value indicating that all dirty-region-log copies for the
value were detached due to I/O failures.
A string value that is used by usage types to represent options to the
volume start utility. See the usage-type-specific volume(8) reference
pages for more information.
A Boolean value indicating whether the volume was in use at the time of
a system failure. This will not be set if the volume was not written
prior to the crash. This flag indicates that plex synchronization
recovery is required for the volume. v_active is normally cleared dur-
ing system startup when the volume is started.
A Boolean value indicating that read-writeback plex synchronization
recovery has been started for the volume. This is normally set when a
mirrored volume is started when the v_active flag was set.
A Boolean value indicating whether the read-writeback recovery mode is
still enabled in the kernel. This flag is turned on when v_rwback is
turned on, but is cleared by the kernel when recovery for the volume is
A number indicating the offset within the volume to where recovery has
completed. A read operation on a volume performs a plex synchronization
recovery if the read is after this point in the volume. A read that
occurs at the current read-writeback offset advances the offset to the
end of the read. When the offset reaches the end of the volume,
recovery is complete and v_krwback is turned off.
A number indicating the largest sector size, in bytes, of any disk
associated with the volume.
Plex Record Fields
The fields that can be specified for plex records are:
A Boolean value that is true if the plex is compact. A plex is compact
if its entire length is mapped by subdisks, leaving no holes. Note that
the length of a plex is computed as the length to the end of the last
block in the plex address space that is mapped by a subdisk.
The offset to the first unmapped block in the plex. If the plex is com-
pact, this will match the plex length. If the plex is not mapped, this
will be the offset of the first hole in the plex.
An enumeration representing the I/O mode of the plex. This can have one
of the following values: RO (read-only), WO (write-only), or RW (read-
A Boolean value that is true if dirty region logging is enabled for the
A Boolean value that is true if if one of the subdisks in the plex is
defined on a volatile disk. Volatile disks are disks whose contents are
not guaranteed to be preserved across a system reboot. Volatile disks
can be created using the nopriv disk type (see voldisk(8)).
An enumeration for the kernel enabled state for the plex. This can
have one of the values DISABLED, DETACHED or ENABLED.
A number representing a sequence number for the last error that
occurred on the plex.
A number representing the minor number of the plex device. This will
be -1 if the plex is dissociated.
A number representing the device number of the plex device (a character
device). This will be NODEV if the plex is dissociated.
A Boolean value that is true if the plex is accounted for in volume
error handling. If this is set, then I/O errors on the plex are ignored
if they result from normal volume I/O.
pl_v_name or pl_volume
The name of the associated volume. If the plex is not associated, this
is an empty string.
pl_sd_num or pl_nsd
A number representing the count of subdisks that are associated with
pl_sd_name, pl_sd, pl_subdisk, or pl_subdisks
A set containing the names of subdisks that are associated with the
A string representing the usage-type-dependent state for the plex.
An enumeration representing the subdisk layout policy for the plex.
This can be one of the values CONCAT or STRIPE to represent concatena-
tion or striping, respectively.
A number representing the stripe width for the plex. This is only
defined if the value for the pl_layout field in the plex is STRIPE.
Otherwise, use of this variable causes an implicit assert.
A string representing the name of a subdisk associated with the plex as
a log subdisk. This string is empty if no log subdisk is associated
with the plex.
A Boolean indicating whether any subdisk in the plex is defined on a
removed disk. See vdg(8) for information on removed disks.
pl_nodarec or pl_failed
A Boolean indicating whether any subdisk in the plex is defined on a
failed disk. A failed disk is one where the underlying physical disk
could not be found, or was detached by an I/O failure.
pl_stale or pl_recover
A Boolean indicating whether a disk replacement or a temporary failure
caused the plex to become disabled and out-of-date with respect to the
volume contents. Such plexes require recovery either from other plexes
in the volume or from a backup of the volume.
pl_kdetach or pl_iofail
A Boolean indicating that the plex was detached by the kernel due to an
I/O failure. The stale and kdetach flags are normally both cleared dur-
ing a system reboot as part of starting the volume.
pl_vol_rid or pl_v_rid
The record ID of the volume to which the plex is associated. This will
be 0.0 if the plex is not associated.
The record ID of the log subdisk for the plex. This will be 0.0 if the
plex has no log subdisk.
The configuration sequence number of the disk group that was in effect
when the plex was last detached or disabled due to an I/O failure or a
Subdisk Record Fields
The fields that can be specified for subdisk records are:
sd_dm_name or sd_disk
The name of the disk media record on which the subdisk is defined.
sd_da_name or sd_device
The disk access record underlying the disk media record of the subdisk.
This will be empty if the disk is currently failed or removed.
The device number of the device that the subdisk resides on. This
number is a combination of the major and minor number for the device.
This will be NODEV if the underlying disk is removed or failed.
A string containing the path to the device that the subdisk resides on.
sd_pl_name or sd_plex
The name of the associated plex. If the subdisk is not associated, this
is an empty string.
sd_dm_offset or sd_offset
A number representing the offset of the subdisk within the public
region of the disk that the subdisk resides on.
A number representing the offset of the subdisk within the disk parti-
tion containing the public region for the disk. This can differ from
sd_dm_offset if the public region of the disk does not begin at the
beginning of its partition.
A number representing the offset of the subdisk within the address
space of the plex to which it is associated.
A Boolean value that is true if the subdisk is defined on a volatile
disk. The contents of a volatile disk are not guaranteed to be
preserved across a reboot. Volatile disks can be created using the
nopriv disk type (see voldisk(8)).
sd_is_log or sd_log
A Boolean value indicating that this is a log subdisk for a plex.
sd_plex_rid or sd_pl_rid
The record ID of the plex to which the subdisk is associated.
sd_dm_rid or sd_disk_rid
The record ID of the disk media record on which the subdisk is defined.
1. The following example matches any plex or volume that does not have
any associated subdisks or plexes. Because pl_nsd only applies to
plexes, while v_nplex only applies to volumes, there is no ambiguity
concerning which types of records can be matched by the expression.
pl_nsd = 0 || v_nplex = 0
2. The following example matches all plexes and subdisks that have a com-
ment field beginning with the string "Henry ". For example, this
could be a convention describing ownership.
(plex || sd) &&&& comment ~ /^Henry/
3. The following example matches all volumes for which the preferred plex
v_pref_name.pl_layout = STRIPE
Because v_pref_name is only defined for volumes that have v_read_pol
set to PREFER, the preceding expression is equivalent to:
vol &&&& v_read_pol = PREFER &&&& v_pref_name.pl_layout = STRIPE
4. The following expression matches any volume that contains a plex with
a subdisk longer than 100 megabytes:
any v_plex.pl_subdisk.sd_len >> 100M
If an expression contains a set but does not use the any or in opera-
tor, then an any operator is assumed to surround the expression. Thus,
the preceding example can also be specified as:
v_plex.pl_subdisk.sd_len >> 100M
5. The following example matches any record that was changed in the most
recent set of changes to the disk group:
update_tid = config_tid
Alternatively, to get all records that have been changed since a past
disk group configuration (with a configuration transaction ID of
update_tid >> 0.23482
awk(1), voledit(8), volintro(8), volmake(8), volprint(8)