[ovs-dev] [PATCH 5/7] db-ctl-base: Librarize database command manual.

Ben Pfaff blp at nicira.com
Tue Jun 23 00:09:29 UTC 2015


I like the idea.

(Currently skimming through this series before I review in detail.)

On Thu, Jun 11, 2015 at 07:34:14PM -0700, Alex Wang wrote:
> not sure if doing this totally makes sense, would like to hear comments,~
> 
> On Thu, Jun 11, 2015 at 7:37 PM, Alex Wang <alexw at nicira.com> wrote:
> 
> > This commit extracts the database command manual and puts it into
> > db-ctl-base.man.
> >
> > Signed-off-by: Alex Wang <alexw at nicira.com>
> > ---
> >  lib/automake.mk          |    1 +
> >  lib/db-ctl-base.man      |  267
> > ++++++++++++++++++++++++++++++++++++++++++++++
> >  manpages.mk              |    2 +
> >  utilities/ovs-vsctl.8.in |  259
> > +-------------------------------------------
> >  4 files changed, 271 insertions(+), 258 deletions(-)
> >  create mode 100644 lib/db-ctl-base.man
> >
> > diff --git a/lib/automake.mk b/lib/automake.mk
> > index cb1a689..a385585 100644
> > --- a/lib/automake.mk
> > +++ b/lib/automake.mk
> > @@ -414,6 +414,7 @@ MAN_FRAGMENTS += \
> >         lib/coverage-unixctl.man \
> >         lib/daemon.man \
> >         lib/daemon-syn.man \
> > +       lib/db-ctl-base.man \
> >         lib/dpctl.man \
> >         lib/memory-unixctl.man \
> >         lib/ofp-version.man \
> > diff --git a/lib/db-ctl-base.man b/lib/db-ctl-base.man
> > new file mode 100644
> > index 0000000..7b30501
> > --- /dev/null
> > +++ b/lib/db-ctl-base.man
> > @@ -0,0 +1,267 @@
> > +.ST "Database Values"
> > +.PP
> > +Each column in the database accepts a fixed type of data.  The
> > +currently defined basic types, and their representations, are:
> > +.IP "integer"
> > +A decimal integer in the range \-2**63 to 2**63\-1, inclusive.
> > +.IP "real"
> > +A floating-point number.
> > +.IP "Boolean"
> > +True or false, written \fBtrue\fR or \fBfalse\fR, respectively.
> > +.IP "string"
> > +An arbitrary Unicode string, except that null bytes are not allowed.
> > +Quotes are optional for most strings that begin with an English letter
> > +or underscore and consist only of letters, underscores, hyphens, and
> > +periods.  However, \fBtrue\fR and \fBfalse\fR and strings that match
> > +the syntax of UUIDs (see below) must be enclosed in double quotes to
> > +distinguish them from other basic types.  When double quotes are used,
> > +the syntax is that of strings in JSON, e.g. backslashes may be used to
> > +escape special characters.  The empty string must be represented as a
> > +pair of double quotes (\fB""\fR).
> > +.IP "UUID"
> > +Either a universally unique identifier in the style of RFC 4122,
> > +e.g. \fBf81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\fR, or an \fB@\fIname\fR
> > +defined by a \fBget\fR or \fBcreate\fR command within the same \fB\*(PN\fR
> > +invocation.
> > +.PP
> > +Multiple values in a single column may be separated by spaces or a
> > +single comma.  When multiple values are present, duplicates are not
> > +allowed, and order is not important.  Conversely, some database
> > +columns can have an empty set of values, represented as \fB[]\fR, and
> > +square brackets may optionally enclose other non-empty sets or single
> > +values as well.
> > +.PP
> > +A few database columns are ``maps'' of key-value pairs, where the key
> > +and the value are each some fixed database type.  These are specified
> > +in the form \fIkey\fB=\fIvalue\fR, where \fIkey\fR and \fIvalue\fR
> > +follow the syntax for the column's key type and value type,
> > +respectively.  When multiple pairs are present (separated by spaces or
> > +a comma), duplicate keys are not allowed, and again the order is not
> > +important.  Duplicate values are allowed.  An empty map is represented
> > +as \fB{}\fR.  Curly braces may optionally enclose non-empty maps as
> > +well (but use quotes to prevent the shell from expanding
> > +\fBother-config={0=x,1=y}\fR into \fBother-config=0=x
> > +other-config=1=y\fR, which may not have the desired effect).
> > +.
> > +.ST "Database Command Syntax"
> > +.
> > +.IP "[\fB\-\-if\-exists\fR]
> > [\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable
> > \fR[\fIrecord\fR]..."
> > +Lists the data in each specified \fIrecord\fR.  If no
> > +records are specified, lists all the records in \fItable\fR.
> > +.IP
> > +If \fB\-\-columns\fR is specified, only the requested columns are
> > +listed, in the specified order.  Otherwise, all columns are listed, in
> > +alphabetical order by column name.
> > +.IP
> > +Without \fB\-\-if-exists\fR, it is an error if any specified
> > +\fIrecord\fR does not exist.  With \fB\-\-if-exists\fR, the command
> > +ignores any \fIrecord\fR that does not exist, without producing any
> > +output.
> > +.
> > +.IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBfind \fItable
> > \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..."
> > +Lists the data in each record in \fItable\fR whose \fIcolumn\fR equals
> > +\fIvalue\fR or, if \fIkey\fR is specified, whose \fIcolumn\fR contains
> > +a \fIkey\fR with the specified \fIvalue\fR.  The following operators
> > +may be used where \fB=\fR is written in the syntax summary:
> > +.RS
> > +.IP "\fB= != < > <= >=\fR"
> > +Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] equals, does not
> > +equal, is less than, is greater than, is less than or equal to, or is
> > +greater than or equal to \fIvalue\fR, respectively.
> > +.IP
> > +Consider \fIcolumn\fR[\fB:\fIkey\fR] and \fIvalue\fR as sets of
> > +elements.  Identical sets are considered equal.  Otherwise, if the
> > +sets have different numbers of elements, then the set with more
> > +elements is considered to be larger.  Otherwise, consider a element
> > +from each set pairwise, in increasing order within each set.  The
> > +first pair that differs determines the result.  (For a column that
> > +contains key-value pairs, first all the keys are compared, and values
> > +are considered only if the two sets contain identical keys.)
> > +.IP "\fB{=} {!=}\fR"
> > +Test for set equality or inequality, respectively.
> > +.IP "\fB{<=}\fR"
> > +Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a subset of
> > +\fIvalue\fR.  For example, \fBflood-vlans{<=}1,2\fR selects records in
> > +which the \fBflood-vlans\fR column is the empty set or contains 1 or 2
> > +or both.
> > +.IP "\fB{<}\fR"
> > +Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a proper
> > +subset of \fIvalue\fR.  For example, \fBflood-vlans{<}1,2\fR selects
> > +records in which the \fBflood-vlans\fR column is the empty set or
> > +contains 1 or 2 but not both.
> > +.IP "\fB{>=} {>}\fR"
> > +Same as \fB{<=}\fR and \fB{<}\fR, respectively, except that the
> > +relationship is reversed.  For example, \fBflood-vlans{>=}1,2\fR
> > +selects records in which the \fBflood-vlans\fR column contains both 1
> > +and 2.
> > +.RE
> > +.IP
> > +For arithmetic operators (\fB= != < > <= >=\fR), when \fIkey\fR is
> > +specified but a particular record's \fIcolumn\fR does not contain
> > +\fIkey\fR, the record is always omitted from the results.  Thus, the
> > +condition \fBother-config:mtu!=1500\fR matches records that have a
> > +\fBmtu\fR key whose value is not 1500, but not those that lack an
> > +\fBmtu\fR key.
> > +.IP
> > +For the set operators, when \fIkey\fR is specified but a particular
> > +record's \fIcolumn\fR does not contain \fIkey\fR, the comparison is
> > +done against an empty set.  Thus, the condition
> > +\fBother-config:mtu{!=}1500\fR matches records that have a \fBmtu\fR
> > +key whose value is not 1500 and those that lack an \fBmtu\fR key.
> > +.IP
> > +Don't forget to escape \fB<\fR or \fB>\fR from interpretation by the
> > +shell.
> > +.IP
> > +If \fB\-\-columns\fR is specified, only the requested columns are
> > +listed, in the specified order.  Otherwise all columns are listed, in
> > +alphabetical order by column name.
> > +.IP
> > +The UUIDs shown for rows created in the same \fB\*(PN\fR
> > +invocation will be wrong.
> > +.
> > +.IP "[\fB\-\-if\-exists\fR] [\fB\-\-id=@\fIname\fR] \fBget \fItable
> > record \fR[\fIcolumn\fR[\fB:\fIkey\fR]]..."
> > +Prints the value of each specified \fIcolumn\fR in the given
> > +\fIrecord\fR in \fItable\fR.  For map columns, a \fIkey\fR may
> > +optionally be specified, in which case the value associated with
> > +\fIkey\fR in the column is printed, instead of the entire map.
> > +.IP
> > +Without \fB\-\-if\-exists\fR, it is an error if \fIrecord\fR does not
> > +exist or \fIkey\fR is specified, if \fIkey\fR does not exist in
> > +\fIrecord\fR.  With \fB\-\-if\-exists\fR, a missing \fIrecord\fR
> > +yields no output and a missing \fIkey\fR prints a blank line.
> > +.IP
> > +If \fB@\fIname\fR is specified, then the UUID for \fIrecord\fR may be
> > +referred to by that name later in the same \fB\*(PN\fR
> > +invocation in contexts where a UUID is expected.
> > +.IP
> > +Both \fB\-\-id\fR and the \fIcolumn\fR arguments are optional, but
> > +usually at least one or the other should be specified.  If both are
> > +omitted, then \fBget\fR has no effect except to verify that
> > +\fIrecord\fR exists in \fItable\fR.
> > +.IP
> > +\fB\-\-id\fR and \fB\-\-if\-exists\fR cannot be used together.
> > +.
> > +.IP "[\fB\-\-if\-exists\fR] \fBset \fItable record
> > column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
> > +Sets the value of each specified \fIcolumn\fR in the given
> > +\fIrecord\fR in \fItable\fR to \fIvalue\fR.  For map columns, a
> > +\fIkey\fR may optionally be specified, in which case the value
> > +associated with \fIkey\fR in that column is changed (or added, if none
> > +exists), instead of the entire map.
> > +.IP
> > +Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
> > +exist.  With \fB\-\-if-exists\fR, this command does nothing if
> > +\fIrecord\fR does not exist.
> > +.
> > +.IP "[\fB\-\-if\-exists\fR] \fBadd \fItable record column
> > \fR[\fIkey\fB=\fR]\fIvalue\fR..."
> > +Adds the specified value or key-value pair to \fIcolumn\fR in
> > +\fIrecord\fR in \fItable\fR.  If \fIcolumn\fR is a map, then \fIkey\fR
> > +is required, otherwise it is prohibited.  If \fIkey\fR already exists
> > +in a map column, then the current \fIvalue\fR is not replaced (use the
> > +\fBset\fR command to replace an existing value).
> > +.IP
> > +Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
> > +exist.  With \fB\-\-if-exists\fR, this command does nothing if
> > +\fIrecord\fR does not exist.
> > +.
> > +.IP "[\fB\-\-if\-exists\fR] \fBremove \fItable record column
> > \fR\fIvalue\fR..."
> > +.IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column
> > \fR\fIkey\fR..."
> > +.IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column
> > \fR\fIkey\fB=\fR\fIvalue\fR..."
> > +Removes the specified values or key-value pairs from \fIcolumn\fR in
> > +\fIrecord\fR in \fItable\fR.  The first form applies to columns that
> > +are not maps: each specified \fIvalue\fR is removed from the column.
> > +The second and third forms apply to map columns: if only a \fIkey\fR
> > +is specified, then any key-value pair with the given \fIkey\fR is
> > +removed, regardless of its value; if a \fIvalue\fR is given then a
> > +pair is removed only if both key and value match.
> > +.IP
> > +It is not an error if the column does not contain the specified key or
> > +value or pair.
> > +.IP
> > +Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
> > +exist.  With \fB\-\-if-exists\fR, this command does nothing if
> > +\fIrecord\fR does not exist.
> > +.
> > +.IP "[\fB\-\-if\-exists\fR] \fBclear\fR \fItable record column\fR..."
> > +Sets each \fIcolumn\fR in \fIrecord\fR in \fItable\fR to the empty set
> > +or empty map, as appropriate.  This command applies only to columns
> > +that are allowed to be empty.
> > +.IP
> > +Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
> > +exist.  With \fB\-\-if-exists\fR, this command does nothing if
> > +\fIrecord\fR does not exist.
> > +.
> > +.IP "[\fB\-\-id=@\fIname\fR] \fBcreate\fR \fItable
> > column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
> > +Creates a new record in \fItable\fR and sets the initial values of
> > +each \fIcolumn\fR.  Columns not explicitly set will receive their
> > +default values.  Outputs the UUID of the new row.
> > +.IP
> > +If \fB@\fIname\fR is specified, then the UUID for the new row may be
> > +referred to by that name elsewhere in the same \fB\*(PN\fR
> > +invocation in contexts where a UUID is expected.  Such references may
> > +precede or follow the \fBcreate\fR command.
> > +.
> > +.RS
> > +.IP "Caution (ovs-vsctl as exmaple)"
> > +Records in the Open vSwitch database are significant only when they
> > +can be reached directly or indirectly from the \fBOpen_vSwitch\fR
> > +table.  Except for records in the \fBQoS\fR or \fBQueue\fR tables,
> > +records that are not reachable from the \fBOpen_vSwitch\fR table are
> > +automatically deleted from the database.  This deletion happens
> > +immediately, without waiting for additional \fBovs\-vsctl\fR commands
> > +or other database activity.  Thus, a \fBcreate\fR command must
> > +generally be accompanied by additional commands \fIwithin the same
> > +\fBovs\-vsctl\fI invocation\fR to add a chain of references to the
> > +newly created record from the top-level \fBOpen_vSwitch\fR record.
> > +The \fBEXAMPLES\fR section gives some examples that show how to do
> > +this.
> > +.RE
> > +.
> > +.IP "\fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..."
> > +Deletes each specified \fIrecord\fR from \fItable\fR.  Unless
> > +\fB\-\-if\-exists\fR is specified, each \fIrecord\fRs must exist.
> > +.IP "\fB\-\-all destroy \fItable\fR"
> > +Deletes all records from the \fItable\fR.
> > +.
> > +.RS
> > +.IP "Caution (ovs-vsctl as exmaple)"
> > +The \fBdestroy\fR command is only useful for records in the \fBQoS\fR
> > +or \fBQueue\fR tables.  Records in other tables are automatically
> > +deleted from the database when they become unreachable from the
> > +\fBOpen_vSwitch\fR table.  This means that deleting the last reference
> > +to a record is sufficient for deleting the record itself.  For records
> > +in these tables, \fBdestroy\fR is silently ignored.  See the
> > +\fBEXAMPLES\fR section below for more information.
> > +.RE
> > +.
> > +.IP "\fBwait\-until \fItable record
> > \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..."
> > +Waits until \fItable\fR contains a record named \fIrecord\fR whose
> > +\fIcolumn\fR equals \fIvalue\fR or, if \fIkey\fR is specified, whose
> > +\fIcolumn\fR contains a \fIkey\fR with the specified \fIvalue\fR.  Any
> > +of the operators \fB!=\fR, \fB<\fR, \fB>\fR, \fB<=\fR, or \fB>=\fR may
> > +be substituted for \fB=\fR to test for inequality, less than, greater
> > +than, less than or equal to, or greater than or equal to,
> > +respectively.  (Don't forget to escape \fB<\fR or \fB>\fR from
> > +interpretation by the shell.)
> > +.IP
> > +If no \fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR arguments are given,
> > +this command waits only until \fIrecord\fR exists.  If more than one
> > +such argument is given, the command waits until all of them are
> > +satisfied.
> > +.
> > +.RS
> > +.IP "Caution (ovs-vsctl as exmaple)"
> > +Usually \fBwait\-until\fR should be placed at the beginning of a set
> > +of \fBovs\-vsctl\fR commands.  For example, \fBwait\-until bridge br0
> > +\-\- get bridge br0 datapath_id\fR waits until a bridge named
> > +\fBbr0\fR is created, then prints its \fBdatapath_id\fR column,
> > +whereas \fBget bridge br0 datapath_id \-\- wait\-until bridge br0\fR
> > +will abort if no bridge named \fBbr0\fR exists when \fBovs\-vsctl\fR
> > +initially connects to the database.
> > +.RE
> > +.IP
> > +Consider specifying \fB\-\-timeout=0\fR along with
> > +\fB\-\-wait\-until\fR, to prevent \fB\*(PN\fR from terminating
> > +after waiting only at most 5 seconds.
> > +.IP "\fBcomment \fR[\fIarg\fR]..."
> > +This command has no effect on behavior, but any database log record
> > +created by the command will include the command and its arguments.
> > diff --git a/manpages.mk b/manpages.mk
> > index 4a76cf1..4cc3bf2 100644
> > --- a/manpages.mk
> > +++ b/manpages.mk
> > @@ -213,6 +213,7 @@ utilities/ovs-vlan-bugs.man:
> >  utilities/ovs-vsctl.8: \
> >         utilities/ovs-vsctl.8.in \
> >         lib/common.man \
> > +       lib/db-ctl-base.man \
> >         lib/ssl-bootstrap.man \
> >         lib/ssl-peer-ca-cert.man \
> >         lib/ssl.man \
> > @@ -226,6 +227,7 @@ utilities/ovs-vsctl.8: \
> >         ovsdb/remote-passive.man
> >  utilities/ovs-vsctl.8.in:
> >  lib/common.man:
> > +lib/db-ctl-base.man:
> >  lib/ssl-bootstrap.man:
> >  lib/ssl-peer-ca-cert.man:
> >  lib/ssl.man:
> > diff --git a/utilities/ovs-vsctl.8.in b/utilities/ovs-vsctl.8.in
> > index 785857d..972fc26 100644
> > --- a/utilities/ovs-vsctl.8.in
> > +++ b/utilities/ovs-vsctl.8.in
> > @@ -565,264 +565,7 @@ and \fB\-\-\fR and \fB_\fR are treated
> > interchangeably.  Unique
> >  abbreviations are acceptable, e.g. \fBnet\fR or \fBn\fR is sufficient
> >  to identify the \fBNetFlow\fR table.
> >  .
> > -.ST "Database Values"
> > -.PP
> > -Each column in the database accepts a fixed type of data.  The
> > -currently defined basic types, and their representations, are:
> > -.IP "integer"
> > -A decimal integer in the range \-2**63 to 2**63\-1, inclusive.
> > -.IP "real"
> > -A floating-point number.
> > -.IP "Boolean"
> > -True or false, written \fBtrue\fR or \fBfalse\fR, respectively.
> > -.IP "string"
> > -An arbitrary Unicode string, except that null bytes are not allowed.
> > -Quotes are optional for most strings that begin with an English letter
> > -or underscore and consist only of letters, underscores, hyphens, and
> > -periods.  However, \fBtrue\fR and \fBfalse\fR and strings that match
> > -the syntax of UUIDs (see below) must be enclosed in double quotes to
> > -distinguish them from other basic types.  When double quotes are used,
> > -the syntax is that of strings in JSON, e.g. backslashes may be used to
> > -escape special characters.  The empty string must be represented as a
> > -pair of double quotes (\fB""\fR).
> > -.IP "UUID"
> > -Either a universally unique identifier in the style of RFC 4122,
> > -e.g. \fBf81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\fR, or an \fB@\fIname\fR
> > -defined by a \fBget\fR or \fBcreate\fR command within the same
> > \fBovs\-vsctl\fR
> > -invocation.
> > -.PP
> > -Multiple values in a single column may be separated by spaces or a
> > -single comma.  When multiple values are present, duplicates are not
> > -allowed, and order is not important.  Conversely, some database
> > -columns can have an empty set of values, represented as \fB[]\fR, and
> > -square brackets may optionally enclose other non-empty sets or single
> > -values as well.
> > -.PP
> > -A few database columns are ``maps'' of key-value pairs, where the key
> > -and the value are each some fixed database type.  These are specified
> > -in the form \fIkey\fB=\fIvalue\fR, where \fIkey\fR and \fIvalue\fR
> > -follow the syntax for the column's key type and value type,
> > -respectively.  When multiple pairs are present (separated by spaces or
> > -a comma), duplicate keys are not allowed, and again the order is not
> > -important.  Duplicate values are allowed.  An empty map is represented
> > -as \fB{}\fR.  Curly braces may optionally enclose non-empty maps as
> > -well (but use quotes to prevent the shell from expanding
> > -\fBother-config={0=x,1=y}\fR into \fBother-config=0=x
> > -other-config=1=y\fR, which may not have the desired effect).
> > -.
> > -.ST "Database Command Syntax"
> > -.
> > -.IP "[\fB\-\-if\-exists\fR]
> > [\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBlist \fItable
> > \fR[\fIrecord\fR]..."
> > -Lists the data in each specified \fIrecord\fR.  If no
> > -records are specified, lists all the records in \fItable\fR.
> > -.IP
> > -If \fB\-\-columns\fR is specified, only the requested columns are
> > -listed, in the specified order.  Otherwise, all columns are listed, in
> > -alphabetical order by column name.
> > -.IP
> > -Without \fB\-\-if-exists\fR, it is an error if any specified
> > -\fIrecord\fR does not exist.  With \fB\-\-if-exists\fR, the command
> > -ignores any \fIrecord\fR that does not exist, without producing any
> > -output.
> > -.
> > -.IP "[\fB\-\-columns=\fIcolumn\fR[\fB,\fIcolumn\fR]...] \fBfind \fItable
> > \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..."
> > -Lists the data in each record in \fItable\fR whose \fIcolumn\fR equals
> > -\fIvalue\fR or, if \fIkey\fR is specified, whose \fIcolumn\fR contains
> > -a \fIkey\fR with the specified \fIvalue\fR.  The following operators
> > -may be used where \fB=\fR is written in the syntax summary:
> > -.RS
> > -.IP "\fB= != < > <= >=\fR"
> > -Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] equals, does not
> > -equal, is less than, is greater than, is less than or equal to, or is
> > -greater than or equal to \fIvalue\fR, respectively.
> > -.IP
> > -Consider \fIcolumn\fR[\fB:\fIkey\fR] and \fIvalue\fR as sets of
> > -elements.  Identical sets are considered equal.  Otherwise, if the
> > -sets have different numbers of elements, then the set with more
> > -elements is considered to be larger.  Otherwise, consider a element
> > -from each set pairwise, in increasing order within each set.  The
> > -first pair that differs determines the result.  (For a column that
> > -contains key-value pairs, first all the keys are compared, and values
> > -are considered only if the two sets contain identical keys.)
> > -.IP "\fB{=} {!=}\fR"
> > -Test for set equality or inequality, respectively.
> > -.IP "\fB{<=}\fR"
> > -Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a subset of
> > -\fIvalue\fR.  For example, \fBflood-vlans{<=}1,2\fR selects records in
> > -which the \fBflood-vlans\fR column is the empty set or contains 1 or 2
> > -or both.
> > -.IP "\fB{<}\fR"
> > -Selects records in which \fIcolumn\fR[\fB:\fIkey\fR] is a proper
> > -subset of \fIvalue\fR.  For example, \fBflood-vlans{<}1,2\fR selects
> > -records in which the \fBflood-vlans\fR column is the empty set or
> > -contains 1 or 2 but not both.
> > -.IP "\fB{>=} {>}\fR"
> > -Same as \fB{<=}\fR and \fB{<}\fR, respectively, except that the
> > -relationship is reversed.  For example, \fBflood-vlans{>=}1,2\fR
> > -selects records in which the \fBflood-vlans\fR column contains both 1
> > -and 2.
> > -.RE
> > -.IP
> > -For arithmetic operators (\fB= != < > <= >=\fR), when \fIkey\fR is
> > -specified but a particular record's \fIcolumn\fR does not contain
> > -\fIkey\fR, the record is always omitted from the results.  Thus, the
> > -condition \fBother-config:mtu!=1500\fR matches records that have a
> > -\fBmtu\fR key whose value is not 1500, but not those that lack an
> > -\fBmtu\fR key.
> > -.IP
> > -For the set operators, when \fIkey\fR is specified but a particular
> > -record's \fIcolumn\fR does not contain \fIkey\fR, the comparison is
> > -done against an empty set.  Thus, the condition
> > -\fBother-config:mtu{!=}1500\fR matches records that have a \fBmtu\fR
> > -key whose value is not 1500 and those that lack an \fBmtu\fR key.
> > -.IP
> > -Don't forget to escape \fB<\fR or \fB>\fR from interpretation by the
> > -shell.
> > -.IP
> > -If \fB\-\-columns\fR is specified, only the requested columns are
> > -listed, in the specified order.  Otherwise all columns are listed, in
> > -alphabetical order by column name.
> > -.IP
> > -The UUIDs shown for rows created in the same \fBovs\-vsctl\fR
> > -invocation will be wrong.
> > -.
> > -.IP "[\fB\-\-if\-exists\fR] [\fB\-\-id=@\fIname\fR] \fBget \fItable
> > record \fR[\fIcolumn\fR[\fB:\fIkey\fR]]..."
> > -Prints the value of each specified \fIcolumn\fR in the given
> > -\fIrecord\fR in \fItable\fR.  For map columns, a \fIkey\fR may
> > -optionally be specified, in which case the value associated with
> > -\fIkey\fR in the column is printed, instead of the entire map.
> > -.IP
> > -Without \fB\-\-if\-exists\fR, it is an error if \fIrecord\fR does not
> > -exist or \fIkey\fR is specified, if \fIkey\fR does not exist in
> > -\fIrecord\fR.  With \fB\-\-if\-exists\fR, a missing \fIrecord\fR
> > -yields no output and a missing \fIkey\fR prints a blank line.
> > -.IP
> > -If \fB@\fIname\fR is specified, then the UUID for \fIrecord\fR may be
> > -referred to by that name later in the same \fBovs\-vsctl\fR
> > -invocation in contexts where a UUID is expected.
> > -.IP
> > -Both \fB\-\-id\fR and the \fIcolumn\fR arguments are optional, but
> > -usually at least one or the other should be specified.  If both are
> > -omitted, then \fBget\fR has no effect except to verify that
> > -\fIrecord\fR exists in \fItable\fR.
> > -.IP
> > -\fB\-\-id\fR and \fB\-\-if\-exists\fR cannot be used together.
> > -.
> > -.IP "[\fB\-\-if\-exists\fR] \fBset \fItable record
> > column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
> > -Sets the value of each specified \fIcolumn\fR in the given
> > -\fIrecord\fR in \fItable\fR to \fIvalue\fR.  For map columns, a
> > -\fIkey\fR may optionally be specified, in which case the value
> > -associated with \fIkey\fR in that column is changed (or added, if none
> > -exists), instead of the entire map.
> > -.IP
> > -Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
> > -exist.  With \fB\-\-if-exists\fR, this command does nothing if
> > -\fIrecord\fR does not exist.
> > -.
> > -.IP "[\fB\-\-if\-exists\fR] \fBadd \fItable record column
> > \fR[\fIkey\fB=\fR]\fIvalue\fR..."
> > -Adds the specified value or key-value pair to \fIcolumn\fR in
> > -\fIrecord\fR in \fItable\fR.  If \fIcolumn\fR is a map, then \fIkey\fR
> > -is required, otherwise it is prohibited.  If \fIkey\fR already exists
> > -in a map column, then the current \fIvalue\fR is not replaced (use the
> > -\fBset\fR command to replace an existing value).
> > -.IP
> > -Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
> > -exist.  With \fB\-\-if-exists\fR, this command does nothing if
> > -\fIrecord\fR does not exist.
> > -.
> > -.IP "[\fB\-\-if\-exists\fR] \fBremove \fItable record column
> > \fR\fIvalue\fR..."
> > -.IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column
> > \fR\fIkey\fR..."
> > -.IQ "[\fB\-\-if\-exists\fR] \fBremove \fItable record column
> > \fR\fIkey\fB=\fR\fIvalue\fR..."
> > -Removes the specified values or key-value pairs from \fIcolumn\fR in
> > -\fIrecord\fR in \fItable\fR.  The first form applies to columns that
> > -are not maps: each specified \fIvalue\fR is removed from the column.
> > -The second and third forms apply to map columns: if only a \fIkey\fR
> > -is specified, then any key-value pair with the given \fIkey\fR is
> > -removed, regardless of its value; if a \fIvalue\fR is given then a
> > -pair is removed only if both key and value match.
> > -.IP
> > -It is not an error if the column does not contain the specified key or
> > -value or pair.
> > -.IP
> > -Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
> > -exist.  With \fB\-\-if-exists\fR, this command does nothing if
> > -\fIrecord\fR does not exist.
> > -.
> > -.IP "[\fB\-\-if\-exists\fR] \fBclear\fR \fItable record column\fR..."
> > -Sets each \fIcolumn\fR in \fIrecord\fR in \fItable\fR to the empty set
> > -or empty map, as appropriate.  This command applies only to columns
> > -that are allowed to be empty.
> > -.IP
> > -Without \fB\-\-if-exists\fR, it is an error if \fIrecord\fR does not
> > -exist.  With \fB\-\-if-exists\fR, this command does nothing if
> > -\fIrecord\fR does not exist.
> > -.
> > -.IP "[\fB\-\-id=@\fIname\fR] \fBcreate\fR \fItable
> > column\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR..."
> > -Creates a new record in \fItable\fR and sets the initial values of
> > -each \fIcolumn\fR.  Columns not explicitly set will receive their
> > -default values.  Outputs the UUID of the new row.
> > -.IP
> > -If \fB@\fIname\fR is specified, then the UUID for the new row may be
> > -referred to by that name elsewhere in the same \fBovs\-vsctl\fR
> > -invocation in contexts where a UUID is expected.  Such references may
> > -precede or follow the \fBcreate\fR command.
> > -.IP
> > -Records in the Open vSwitch database are significant only when they
> > -can be reached directly or indirectly from the \fBOpen_vSwitch\fR
> > -table.  Except for records in the \fBQoS\fR or \fBQueue\fR tables,
> > -records that are not reachable from the \fBOpen_vSwitch\fR table are
> > -automatically deleted from the database.  This deletion happens
> > -immediately, without waiting for additional \fBovs\-vsctl\fR commands
> > -or other database activity.  Thus, a \fBcreate\fR command must
> > -generally be accompanied by additional commands \fIwithin the same
> > -\fBovs\-vsctl\fI invocation\fR to add a chain of references to the
> > -newly created record from the top-level \fBOpen_vSwitch\fR record.
> > -The \fBEXAMPLES\fR section gives some examples that show how to do
> > -this.
> > -.
> > -.IP "\fR[\fB\-\-if\-exists\fR] \fBdestroy \fItable record\fR..."
> > -Deletes each specified \fIrecord\fR from \fItable\fR.  Unless
> > -\fB\-\-if\-exists\fR is specified, each \fIrecord\fRs must exist.
> > -.IP "\fB\-\-all destroy \fItable\fR"
> > -Deletes all records from the \fItable\fR.
> > -.IP
> > -The \fBdestroy\fR command is only useful for records in the \fBQoS\fR
> > -or \fBQueue\fR tables.  Records in other tables are automatically
> > -deleted from the database when they become unreachable from the
> > -\fBOpen_vSwitch\fR table.  This means that deleting the last reference
> > -to a record is sufficient for deleting the record itself.  For records
> > -in these tables, \fBdestroy\fR is silently ignored.  See the
> > -\fBEXAMPLES\fR section below for more information.
> > -.
> > -.IP "\fBwait\-until \fItable record
> > \fR[\fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR]..."
> > -Waits until \fItable\fR contains a record named \fIrecord\fR whose
> > -\fIcolumn\fR equals \fIvalue\fR or, if \fIkey\fR is specified, whose
> > -\fIcolumn\fR contains a \fIkey\fR with the specified \fIvalue\fR.  Any
> > -of the operators \fB!=\fR, \fB<\fR, \fB>\fR, \fB<=\fR, or \fB>=\fR may
> > -be substituted for \fB=\fR to test for inequality, less than, greater
> > -than, less than or equal to, or greater than or equal to,
> > -respectively.  (Don't forget to escape \fB<\fR or \fB>\fR from
> > -interpretation by the shell.)
> > -.IP
> > -If no \fIcolumn\fR[\fB:\fIkey\fR]\fB=\fIvalue\fR arguments are given,
> > -this command waits only until \fIrecord\fR exists.  If more than one
> > -such argument is given, the command waits until all of them are
> > -satisfied.
> > -.IP
> > -Usually \fBwait\-until\fR should be placed at the beginning of a set
> > -of \fBovs\-vsctl\fR commands.  For example, \fBwait\-until bridge br0
> > -\-\- get bridge br0 datapath_id\fR waits until a bridge named
> > -\fBbr0\fR is created, then prints its \fBdatapath_id\fR column,
> > -whereas \fBget bridge br0 datapath_id \-\- wait\-until bridge br0\fR
> > -will abort if no bridge named \fBbr0\fR exists when \fBovs\-vsctl\fR
> > -initially connects to the database.
> > -.IP
> > -Consider specifying \fB\-\-timeout=0\fR along with
> > -\fB\-\-wait\-until\fR, to prevent \fBovs\-vsctl\fR from terminating
> > -after waiting only at most 5 seconds.
> > -.IP "\fBcomment \fR[\fIarg\fR]..."
> > -This command has no effect on behavior, but any database log record
> > -created by the command will include the command and its arguments.
> > +.so lib/db-ctl-base.man
> >  .SH "EXAMPLES"
> >  Create a new bridge named br0 and add port eth0 to it:
> >  .IP
> > --
> > 1.7.9.5
> >
> >
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> http://openvswitch.org/mailman/listinfo/dev



More information about the dev mailing list