report: select: add man pages for report selection feature

man/lvdisplay.8.in

@@ -40,6 +40,8 @@ lvdisplay \(em display attributes of a logical volume
 .RI [ + | \- ] Key1 [ , [ + | \- ] Key2 ...]]
 .RB [ \-P | \-\-partial ]
 .RB [ \-\-segments ]
+.RB [ \-S | \-\-select
+.IR Selection ]
 .RB [ \-\-separator
 .IR Separator ]
 .RB [ \-\-unbuffered ]

man/lvm.8.in

@@ -207,6 +207,13 @@ changed with this option. To insert a replacement Physical Volume
 of the same or large size use \fBpvcreate \-u\fP to set the uuid to
 match the original followed by \fBvgcfgrestore\fP(8).
 .TP
+.BR \-S ", " \-\-select " " \fISelection
+For reporting commands, display only rows that match selection criteria.
+All rows are displayed with the additional "selected" column (\fB-o selected\fP)
+showing 1 if the row matches the Selection and 0 otherwise.
+See \fBSELECTION CRITERIA\fP section of this man page for more
+information about the way the selection criteria are constructed.
+.TP
 .BR \-M ", " \-\-metadatatype " " \fIType
 Specifies which type of on-disk metadata to use, such as \fIlvm1\fP
 or \fIlvm2\fP, which can be abbreviated to \fI1\fP or \fI2\fP respectively.
@@ -419,6 +426,68 @@ volume types are an example of this.  Other logical volume types may
 require more than one command to create.  The cache (\fBlvmcache\fP(7))
 and thin provisioning (\fBlvmthin\fP(7)) types are examples of this.
 
+.SH SELECTION CRITERIA
+.LP
+The selection criteria are a set of \fBstatements\fP combined by \fBlogical
+and grouping operators\fP. The \fBstatement\fP consists of \fBcolumn\fP
+name for which a set of valid \fBvalues\fP is defined using
+\fBcomparison operators\fP. For complete list of column names (fields)
+that can be used in selection, see the output of \fB<lvm reporting command> -S help\fP.
+.LP
+\fBComparison operators\fP (cmp_op):
+.IP
+\fB=~\fP \(em Matching regular expression.
+.IP
+\fB!~\fP \(em Not matching regular expression.
+.IP
+\fB=\fP  \(em Equal to.
+.IP
+\fB!=\fP \(em Not equal to.
+.IP
+\fB>=\fP \(em Greater than or equal to.
+.IP
+\fB>\fP  \(em Greater than
+.IP
+\fB<=\fP \(em Less than or equal to.
+.IP
+\fB<\fP  \(em Less than.
+.LP
+\fBBinary logical operators\fP (cmp_log):
+.IP
+\fB&&\fP \(em All fields must match
+.IP
+\fB,\fP  \(em All fields must match
+.IP
+\fB||\fP \(em At least one field must match
+.IP
+\fB#\fP  \(em At least one field must match
+.LP
+\fBUnary logical operators\fP:
+.IP
+\fB!\fP  \(em Logical negation
+.LP
+\fBGrouping operators\fP:
+.IP
+\fB(\fP  \(em Left parenthesis
+.IP
+\fB)\fP  \(em Right parenthesis
+.IP
+\fB[\fP  \(em List start
+.IP
+\fB]\fP  \(em List end
+.LP
+\fBInformal grammar specification\fP:
+.IP
+.BR STATEMENT " = " column " cmp_op " VALUE " | " STATEMENT " log_op " STATEMENT " | " (STATEMENT) " | " !(STATEMENT)
+.IP
+.BR VALUE " = " [VALUE " log_op " VALUE]
+.br
+For list-based types: string list. The log_op must always be of one type within the whole list value.
+.IP
+.BR VALUE " = " value
+.br
+For scalar types: number (integer), size (floating point number with size unit suffix), percent (floating point number with or without % suffix), string.
+
 .SH DIAGNOSTICS
 All tools return a status code of zero on success or non-zero on failure.
 .SH FILES

man/lvs.8.in

@@ -20,6 +20,8 @@ lvs \(em report information about logical volumes
 .RI [ + | \- ] Key1 [,[ + | \- ] Key2 [,...]]]
 .RB [ \-P | \-\-partial ]
 .RB [ \-\-rows ]
+.RB [ \-S | \-\-select
+.IR Selection ]
 .RB [ \-\-separator
 .IR Separator ]
 .RB [ \-\-segments ]
@@ -195,6 +197,18 @@ selection. Precede any column with '\fI\-\fP' for a reverse sort on that column.
 .B \-\-rows
 Output columns as rows.
 .TP
+.BR  \-S ", " \-\-select " " \fISelection
+Display only rows that match selection criteria. All rows are displayed with
+the additional "selected" column (\fB-o selected\fP) showing 1 if the row
+matches the Selection and 0 otherwise. The selection criteria are defined
+by specifying column names and their valid values (that can include reserved
+values) while making use of supported comparison operators. See \fBlvm\fP(8)
+and \fB\-S\fP, \fB\-\-select\fP description for more detailed information
+about constructing the selection criteria. As a quick help and to see full
+list of columns names that can be used in selection including the list of
+reserved values and the set of supported selection operators, check the
+output of \fBlvs -S help\fP command.
+.TP
 .B \-\-segments
 Use default columns that emphasize segment information.
 .TP

man/pvdisplay.8.in

@@ -39,6 +39,8 @@ pvdisplay \- display attributes of a physical volume
 .RB [ \-O | \-\-sort
 .RI [ + | \- ] Key1 [ , [ + | \- ] Key2 ...
 .RI ]]
+.RB [ \-S | \-\-select
+.IR Selection ]
 .RB [ \-\-separator
 .IR Separator ]
 .RB [ \-\-unbuffered ]

man/pvs.8.in

@@ -21,6 +21,8 @@ pvs \(em report information about physical volumes
 .RB [ \-P | \-\-partial ]
 .RB [ \-\-rows ]
 .RB [ \-\-segments ]
+.RB [ \-S | \-\-select
+.IR Selection ]
 .RB [ \-\-separator
 .IR Separator ]
 .RB [ \-\-unbuffered ]
@@ -79,6 +81,18 @@ Produces one line of output for each contiguous allocation of space on each
 Physical Volume, showing the start (pvseg_start) and length (pvseg_size) in
 units of physical extents.
 .TP
+.BR  \-S ", " \-\-select " " \fISelection
+Display only rows that match selection criteria. All rows are displayed with
+the additional "selected" column (\fB-o selected\fP) showing 1 if the row
+matches the Selection and 0 otherwise. The selection criteria are defined
+by specifying column names and their valid values (that can include reserved
+values) while making use of supported comparison operators. See \fBlvm\fP(8)
+and \fB\-S\fP, \fB\-\-select\fP description for more detailed information
+about constructing the selection criteria. As a quick help and to see full
+list of columns names that can be used in selection including the list of
+reserved values and the set of supported selection operators, check the
+output of \fBpvs -S help\fP command.
+.TP
 .BR \-O ", " \-\-sort
 Comma-separated ordered list of columns to sort by.  Replaces the default
 selection. Precede any column with '\fI\-\fP' for a reverse sort on that

man/vgdisplay.8.in

@@ -39,6 +39,8 @@ vgdisplay \(em display attributes of volume groups
 .RB [ \-O | \-\-sort
 .RI [ + | \- ] Key1 [ , [ + | \- ] Key2 ...]]
 .RB [ \-P | \-\-partial ]
+.RB [ \-S | \-\-select
+.IR Selection ]
 .RB [ \-\-separator
 .IR Separator ]
 .RB [ \-\-unbuffered ]

man/vgs.8.in

@@ -20,6 +20,8 @@ vgs \(em report information about volume groups
 .RI [ + | \- ] Key1 [ , [ + | \- ] Key2 ...]]
 .RB [ \-P | \-\-partial ]
 .RB [ \-\-rows ]
+.RB [ \-S | \-\-select
+.IR Selection ]
 .RB [ \-\-separator
 .IR Separator ]
 .RB [ \-\-unbuffered ]
@@ -96,6 +98,18 @@ column.
 .B \-\-rows
 Output columns as rows.
 .TP
+.BR  \-S ", " \-\-select " " \fISelection
+Display only rows that match selection criteria. All rows are displayed with
+the additional "selected" column (\fB-o selected\fP) showing 1 if the row
+matches the Selection and 0 otherwise. The selection criteria are defined
+by specifying column names and their valid values (that can include reserved
+values) while making use of supported comparison operators. See \fBlvm\fP(8)
+and \fB\-S\fP, \fB\-\-select\fP description for more detailed information
+about constructing the selection criteria. As a quick help and to see full
+list of columns names that can be used in selection including the list of
+reserved values and the set of supported selection operators, check the
+output of \fBvgs -S help\fP command.
+.TP
 .B \-\-separator \fISeparator
 String to use to separate each column.  Useful if grepping the output.
 .TP