vol_pattern(4)vol_pattern(4)NAMEvol_pattern - Logical Storage Manager (LSM) search specifications
DESCRIPTION
The vol_pattern search expression language can be used in volprint and
voledit, and with some Logical Storage Manager support library func‐
tions, 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 con‐
text of a configuration record yields a value of true, then the expres‐
sion 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
Expressions in the pattern language are similar to expressions in
awk(1). Expressions can have the following types for constants, vari‐
ables, 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 dig‐
its 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 sec‐
tors.
Defined suffix characters are: b for 512-byte blocks, s for sec‐
tors (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 associ‐
ated 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. Enumer‐
ations are usually useful only for comparing compatible enumera‐
tion field and enumeration constants. For example, the enumera‐
tion field pl_layout is a number whose possible values are rep‐
resented 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
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. Expres‐
sions 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 combina‐
tions yields a truth value of true, then the value of the any expres‐
sion 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 expres‐
sion 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 ~ opera‐
tor, 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 parti‐
tion 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 com‐
pare 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, yield‐
ing 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 ! expres‐
sion 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 con‐
text 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 expres‐
sion 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 expres‐
sion 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 val‐
ues 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. Referenc‐
ing the name of a field in a configuration record yields the
value of that field within the configuration record being evalu‐
ated.
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 con‐
tains 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
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 con‐
stants 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 pre‐
fix 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
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 sub‐
disk structure. This is always 3, but it is treated as a global vari‐
able anyway.
Generic Fields
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
right-hand 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 rep‐
resenting the third permanent utility field. A string representing the
record name. A string representing the comment field. A number repre‐
senting 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 vari‐
able 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 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 implicit 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 trans‐
action of the caller. A Boolean value indicating whether the volume is
locked against I/O activity within the current transaction of the call‐
er. 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 excep‐
tion 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 represent‐
ing 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-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‐
tion. 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 rep‐
resenting the read policy for the volume. This can be one of the values
ROUND, PREFER, or SELECT. The value SELECT indicates that the read pol‐
icy 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_cur‐
rent_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 repre‐
senting 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 vol‐
ume. 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 represent‐
ing 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 sub‐
disk. 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 inte‐
ger, 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 com‐
plete. 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 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 guaran‐
teed to be preserved across a system reboot. Volatile disks can be cre‐
ated 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 dissoci‐
ated. 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 associ‐
ated 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 con‐
catenation 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 associ‐
ated 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 tempo‐
rary 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 dur‐
ing 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
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.
EXAMPLES
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) && com‐
ment ~ /^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_sub‐
disk.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
SEE ALSOawk(1), voldg(8), voledit(8), volintro(8), volmake(8), volprint(8)vol_pattern(4)
