[ovs-dev] [PATCH 5/7] db-ctl-base: Librarize database command manual.
Alex Wang
alexw at nicira.com
Fri Jun 12 02:37:00 UTC 2015
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
More information about the dev
mailing list