ovsdb/ovsdb-idlc.1

   1 .\" -*- nroff -*-
   2 .de IQ
   3 .  br
   4 .  ns
   5 .  IP "\\$1"
   6 ..
   7 .TH ovsdb\-idlc 1 "November 2009" "Open vSwitch" "Open vSwitch Manual"
   8 .ds PN ovsdb\-idlc
   9 .
  10 .SH NAME
  11 ovsdb\-idlc \- Open vSwitch IDL (Interface Definition Language) compiler
  12 .
  13 .SH SYNOPSIS
  14 \fBovsdb\-idlc \fBannotate\fI schema annotations\fR
  15 .br
  16 \fBovsdb\-idlc \fBc\-idl\-header\fI idl\fR
  17 .br
  18 \fBovsdb\-idlc \fBc\-idl\-source\fI idl\fR
  19 .br
  20 \fBovsdb\-idlc \-\-help\fR
  21 .br
  22 \fBovsdb\-idlc \-\-version\fR
  23 .
  24 .SH DESCRIPTION
  25 The \fBovsdb\-idlc\fR program is a command-line tool for translating
  26 Open vSwitch database interface definition language (IDL) schemas into
  27 other formats.  It is used while building Open vSwitch, not at
  28 installation or configuration time.  Thus, it is not normally
  29 installed as part of Open vSwitch.
  30 .
  31 .PP
  32 The \fIidl\fR files used as input for most \fBovsdb\-idlc\fR commands
  33 have the same format as the OVSDB schemas, specified in the OVSDB
  34 specification, with a few additions:
  35 .
  36 .IP """\fBidlPrefix\fR"" member of <database-schema>"
  37 This member, which is required, specifies a string that is prefixed to
  38 top-level names in C bindings.  It should probably end in an
  39 underscore.
  40 .
  41 .IP """\fBidlHeader\fR"" member of <database-schema>"
  42 This member, which is required, specifies the name of the IDL header.
  43 It will be output on an \fB#include\fR line in the source file
  44 generated by the C bindings.  It should include the bracketing
  45 \fB""\fR or \fB<>\fR.
  46 .
  47 .IP """\fBcDecls\fR"" member of <database-schema>"
  48 .IQ """\fBhDecls\fR"" member of <database-schema>"
  49 These optional members may specify arbitrary code to include in the
  50 generated \fB.c\fR or \fB.h\fR file, respectively, in each case just
  51 after the \fB#include\fR directives in those files.
  52 .
  53 .IP """\fBextensions\fR"" member of <table-schema>"
  54 .IQ """\fBextensions\fR"" member of <column-schema>"
  55 This member is optional.  If specified, it is an object whose contents
  56 describes extensions to the OVSDB schema language, for the purpose of
  57 specifying interpretation by the IDL.
  58 .
  59 .IP """\fBsynthetic\fR"" member of <column-schema> ""\fBextensions\fR"" object"
  60 If this optional member is set to \fBtrue\fR, then it indicates that
  61 the column is not expected to be found in the actual database.
  62 Instead, code supplied by the IDL's client fills in the desired
  63 structure members based on the value of one or more other database
  64 columns.  This can be used to cache the result of a calculation, for
  65 example.
  66 .
  67 .IP """\fBparse\fR"" member of <column-schema> ""\fBextensions\fR"" object"
  68 This member should be present if and only if the column is synthetic.
  69 It should be a string that contains C code to set the value of the
  70 column's member in an object named \fBrow\fR, e.g. "\fBrow->column =
  71 1;\fR" if the column's name is \fBcolumn\fR and has integer type.  The
  72 code may rely on the columns named in \fBdependencies\fR to be
  73 initialized.  The function can get called for rows that do not satisfy
  74 the constraints in the schema, e.g. that a pointer to another is
  75 nonnull, so it must not rely on those constraints.
  76 .
  77 .IP """\fBunparse\fR"" member of <column-schema> ""\fBextensions\fR"" object"
  78 This member is honored only if the column is synthetic.  It should be
  79 a string that contains C code to free the data in the column's member
  80 in an object named \fBrow\fR, e.g. "\fBfree(row->column);\fR" if the
  81 column's name is \fBcolumn\fR and points to data that was allocated by
  82 the \fBparse\fR function and needs to be freed.
  83 .
  84 .IP """\fBdependencies\fR"" member of <column-schema> ""\fBextensions\fR"" object"
  85 This member should be a list of the names of columns whose values are
  86 used by the code in \fBparse\fR and \fBunparse\fR.  The IDL ensures
  87 that dependencies are parsed before the columns that depends on them,
  88 and vice versa for unparsing.
  89 .SS "Commands"
  90 .IP "\fBannotate\fI schema annotations\fR"
  91 Reads \fIschema\fR, which should be a file in JSON format (ordinarily
  92 an OVSDB schema file), then reads and executes the Python syntax
  93 fragment in \fIannotations\fR.  The Python syntax fragment is passed
  94 the JSON object as a local variable named \fBs\fR.  It may modify this
  95 data in any way.  After the Python code returns, the object as
  96 modified is re-serialized as JSON on standard output.
  97 .
  98 .IP "\fBc\-idl\-header\fI idl\fR"
  99 Reads \fIidl\fR and prints on standard output a C header file that
 100 defines a structure for each table defined by the schema.  If a column
 101 name in \fIidl\fR is a C or C++ keyword, it will be appended with an
 102 underscore.
 103 .
 104 .IP "\fBc\-idl\-source\fI idl\fR"
 105 Reads \fIidl\fR and prints on standard output a C source file that
 106 implements C bindings for the database defined by the schema.  If a column
 107 name in \fIidl\fR is a C or C++ keyword, it will be appended with an
 108 underscore.
 109 .
 110 .SS "Options"
 111 .so lib/common.man
 112 .
 113 .SH "BUGS"
 114 \fBovsdb\-idlc\fR is more lenient about the format of OVSDB schemas
 115 than other OVSDB tools.  It may successfully parse schemas that, e.g.,
 116 \fBovsdb\-tool\fR rejects.
 117 .
 118 .SH "SEE ALSO"
 119 The OVSDB specification.