vol_pattern - Logical Storage Manager (LSM) search specifications
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. Search expressions are limited to volume, plex,
and subdisk records. 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; otherwise 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 [Toc] [Back]
Expressions in the pattern language are similar to expressions
in awk(1). Expressions can have the following types
for constants, variables, and subexpressions: 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 true. 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 suffix 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 following
expression tests for a record with 2 associated
records, rather than 1024 associated records: nassoc=1k
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 usually useful only for comparing
compatible enumeration field and enumeration constants.
For example, the enumeration field pl_layout
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. Regular expressions
can be used only in the context of the Boolean ~
and !~ operators. Each time a transaction is
issued against a disk group configuration, a 64-bit
configuration sequence number is increased. When a
configuration record is created or changed in a
transaction, the record is stamped with the configuration
sequence number associated with that transaction.
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 constants of the form number.number,
where both numbers are specified in decimal.
Two higher-level types are also included, which can
represent multiple values of the same base type.
These higher-level types are: A set is a multi-valued
variable (an array). Sets are normally used
within the right-hand expression for the any and in
operators. Reference 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 be used only for the
right-hand expression of the in operator.
Expression Grammar [Toc] [Back]
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.
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. 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 false. 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 false. The expression expr is evaluated
as a Boolean expression for all combinations 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: any
pl_sd.sd_disk=disk01 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
expressions 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) 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/
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.
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. These expressions add or subtract two
numbers, yielding another number. 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 expression expr. 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. 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-dependent.
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 that 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
section 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 expression matches only
volume records because the v_kstate field is
defined only for volume records:
v_kstate!=V_ENABLED
Some fields in a record make sense only 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.
Constants [Toc] [Back]
The names of constants that are recognized within search
patterns are: Constants representing Boolean true. Constants
representing Boolean false. 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. 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_. 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 constants can
also be specified with a prefix of V_. The enumeration
constants that represent values for the v_log_type field
in volume records. These enumeration constants can also be
specified 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 PL_. 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 sys/vol.h. The value for a device number field indicating
that the device number is undefined.
Global Variables [Toc] [Back]
The global variables that can be used within search patterns
are: The configuration sequence number of the disk
group configuration. The number of fields in a tutil or
putil array in a volume, plex, or subdisk structure. This
is always 3, but it is treated as a global variable anyway.
Generic Fields [Toc] [Back]
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
operator.
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 righthand
side of a operator.
The recognized generic field names are: A set of strings
representing all of the temporary utility fields. A
string representing the first temporary utility field. A
string representing the second temporary utility field. A
string representing the third temporary utility field. A
set of strings representing all of the permanent utility
fields. A string representing the first permanent utility
field. A string representing the second permanent utility
field. A string representing the third permanent utility
field. A string representing the record name. A string
representing the comment field. 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 if 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. The record
ID of the record being evaluated. The disk group configuration
sequence number corresponding to the transaction
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 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 appropriate
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 subdisks, of which there may be none. This is
not appropriate in the context 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
implicit assert when applied to a subdisk.
Volume Record Fields [Toc] [Back]
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. 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 representing the usage type of
the volume. A string representing the file system type
for the volume, as set by the administrator. A string
representing the usage-type-dependent state for the volume.
A Boolean value indicating whether the writeback-onread-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 information. 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 specified
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. A number representing the number of plexes
associated with the volume. 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 indicates
that the read policy will be adjusted to match the
configuration of the volume: if there is one associated
striped plex, it will be preferred; otherwise the policy
will be round-robin. 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 representing the preferred plex for the volume.
This is defined only 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 character 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. 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, respectively. 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
any. An enumeration representing the logging type for the
volume. This can have one of the following values: LOGUNDEF
(no specific type specified), LOGNONE (no logging), or
LOGDRL (dirty region logging). A Boolean value that is
true if logging is enabled for the volume. Logging is
enabled if the volume is enabled, and it has at least one
associated, enabled plex with an enabled, associated log
subdisk. Two numbers that together represent the most
significant and least significant 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 logging enabled. 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 during 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 complete. 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 [Toc] [Back]
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 compact, this will match the plex length. If the plex
is not compact, 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-write). A
Boolean value that is true if dirty region logging is
enabled for the plex. A Boolean value that is true 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.
The name of the associated volume. If the plex is not
associated, this is an empty string. A number representing
the count of subdisks that are associated with the
plex. A set containing the names of subdisks that are
associated with the plex. 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
concatenation or striping, respectively. A number representing
the stripe width for the plex. This is defined
only 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 voldg(8) for information on
removed disks. 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. 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. 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 during a system
reboot as part of starting the volume. 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 disk failure.
Subdisk Record Fields [Toc] [Back]
The fields that can be specified for subdisk records are:
The name of the disk media record on which the subdisk is
defined. 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 representing the path to the device that
the subdisk resides on. The name of the associated plex.
If the subdisk is not associated, this is an empty string.
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 partition 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)). A Boolean value indicating that this is a log
subdisk for a plex. The record ID of the plex to which
the subdisk is associated. The record ID of the disk
media record on which the subdisk is defined.
The following example matches any plex or volume that does
not have any associated subdisks or plexes. Because pl_nsd
applies only to plexes, while v_nplex applies only to volumes,
there is no ambiguity concerning which types of
records can be matched by the expression. pl_nsd = 0 ||
v_nplex = 0 The following example matches all plexes and
subdisks that have a comment field beginning with the
string "Henry ". For example, this could be a convention
describing ownership. (plex || sd) && comment ~ /^Henry/
The following example matches all volumes for which the
preferred plex is striped: v_pref_name.pl_layout = STRIPE
Because v_pref_name is defined only 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 The following
example 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 operator, 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 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 0.23482), use:
update_tid > 0.23482
awk(1), voldg(8), voledit(8), volintro(8), volmake(8),
volprint(8)
vol_pattern(4)
[ Back ] |
