bk commit - mysqldoc@docsrva tree (stefan:1.3248)

[stefan]

Below is the list of changes that have just been committed into a local
mysqldoc repository of stefan. When stefan does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html

ChangeSet
  1.3248 05/08/11 21:16:59 stefan@stripped +4 -0
  mysql-apis.xml:
    Sync with refman
    Moved libmysqld section to the very top
    (and up one level so that it becomes 24.1)

  refman-5.1/mysql-apis.xml
    1.10 05/08/11 21:16:12 stefan@stripped +613 -0
    Sync with refman

  refman-5.0/mysql-apis.xml
    1.10 05/08/11 21:16:09 stefan@stripped +613 -0
    Sync with refman

  refman-4.1/mysql-apis.xml
    1.27 05/08/11 21:16:06 stefan@stripped +613 -613
    Sync with refman

  refman/mysql-apis.xml
    1.31 05/08/11 21:15:28 stefan@stripped +613 -613
    Moved libmysqld section to the very top
    (and up one level so that it becomes 24.1)

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User:	stefan
# Host:	apollon.site
# Root:	/home/stefan/bk/mysqldoc

--- 1.9/refman-5.1/mysql-apis.xml	2005-08-11 20:15:20 +02:00
+++ 1.10/refman-5.1/mysql-apis.xml	2005-08-11 21:16:12 +02:00
@@ -49,6 +49,619 @@
     basis for most of the other APIs.
   </para>
 
+    <section id="libmysqld">
+
+      <title id='title-libmysqld'>&title-libmysqld;</title>
+
+      <indexterm type="concept">
+        <primary>libmysqld</primary>
+      </indexterm>
+
+      <indexterm type="concept">
+        <primary>embedded MySQL server library</primary>
+      </indexterm>
+
+      <section id="libmysqld-overview">
+
+        <title id='title-libmysqld-overview'>&title-libmysqld-overview;</title>
+
+        <para>
+          The embedded MySQL server library makes it possible to run a
+          full-featured MySQL server inside a client application. The
+          main benefits are increased speed and more simple management
+          for embedded applications.
+        </para>
+
+        <para>
+          The embedded server library is based on the client/server
+          version of MySQL, which is written in C/C++. Consequently, the
+          embedded server also is written in C/C++. There is no embedded
+          server available in other languages.
+        </para>
+
+        <para>
+          The API is identical for the embedded MySQL version and the
+          client/server version. To change an old threaded application
+          to use the embedded library, you normally only have to add
+          calls to the following functions:
+        </para>
+
+        <informaltable>
+          <tgroup cols="2">
+            <colspec colwidth="25*"/>
+            <colspec colwidth="70*"/>
+            <tbody>
+              <row>
+                <entry><emphasis role="bold">Function</emphasis></entry>
+                <entry><emphasis role="bold">When to Call</emphasis></entry>
+              </row>
+              <row>
+                <entry><literal>mysql_server_init()</literal></entry>
+                <entry>Should be called before any other MySQL function is called, preferably
+                  early in the <literal>main()</literal> function.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_server_end()</literal></entry>
+                <entry>Should be called before your program exits.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_thread_init()</literal></entry>
+                <entry>Should be called in each thread you create that accesses MySQL.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_thread_end()</literal></entry>
+                <entry>Should be called before calling <literal>pthread_exit()</literal></entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+
+        <para>
+          Then you must link your code with
+          <filename>libmysqld.a</filename> instead of
+          <filename>libmysqlclient.a</filename>.
+        </para>
+
+        <para>
+          The
+          <literal>mysql_server_<replaceable>xxx</replaceable>()</literal>
+          functions are also included in
+          <filename>libmysqlclient.a</filename> to allow you to change
+          between the embedded and the client/server version by just
+          linking your application with the right library. See
+          <xref linkend="mysql-server-init"/>.
+        </para>
+
+        <para>
+          One difference between the embedded server and the standalone
+          server is that for the embedded server, authentication for
+          connections is disabled by default. To use authentication for
+          the embedded server, specify the
+          <option>--with-embedded-privilege-control</option> option when
+          you invoke <command>configure</command> to configure your
+          MySQL distribution. This option is available as of MySQL
+          4.1.3.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-compiling">
+
+        <title id='title-libmysqld-compiling'>&title-libmysqld-compiling;</title>
+
+        <para>
+          To get a <literal>libmysqld</literal> library you should
+          configure MySQL with the
+          <option>--with-embedded-server</option> option. See
+          <xref linkend="configure-options"/>.
+        </para>
+
+        <para>
+          When you link your program with <literal>libmysqld</literal>,
+          you must also include the system-specific
+          <literal>pthread</literal> libraries and some libraries that
+          the MySQL server uses. You can get the full list of libraries
+          by executing <command>mysql_config --libmysqld-libs</command>.
+        </para>
+
+        <para>
+          The correct flags for compiling and linking a threaded program
+          must be used, even if you do not directly call any thread
+          functions in your code.
+        </para>
+
+        <para>
+          To compile a C program to include the necessary files to embed
+          the MySQL server library into a compiled version of a program,
+          use the GNU C compiler (<literal>gcc</literal>). The compiler
+          will need to know where to find various files and need
+          instructions on how to compile the program. Below is an
+          example of how a program could be compiled from the
+          command-line:
+
+<programlisting>
+gcc mysql_test.c -o mysql_test -lz \
+`/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
+</programlisting>
+        </para>
+
+        <para>
+          Immediately following the <literal>gcc</literal> command is
+          the name of the uncompiled C program file. After it, the
+          <option>-o</option> option is given to indicate that the file
+          name that follows is the name that the compiler is to give to
+          the output file, the compiled program. The next line of code
+          tells the compiler to obtain the location of the include files
+          and libraries and other settings for the system on which it's
+          compiled. Because of a problem with
+          <command>mysql_config</command>, the option
+          <option>-lz</option> (for compression) is added here. The
+          <command>mysql_config</command> piece is contained in
+          backticks, not single quotes.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-restrictions">
+
+        <title id='title-libmysqld-restrictions'>&title-libmysqld-restrictions;</title>
+
+        <para>
+          The embedded server has the following limitations:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              No support for <literal>ISAM</literal> tables. (This is
+              mainly done to make the library smaller)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No user-defined functions (UDFs).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No stack trace on core dump.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No internal RAID support. (This is not normally needed as
+              most current operating systems support big files).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You cannot set this up as a master or a slave (no
+              replication).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Very large result sets may be unusable on low memory
+              systems.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You cannot connect to an embedded server from an outside
+              process with sockets or TCP/IP. However, you can connect
+              to an intermediate application, which in turn can connect
+              to an embedded server on the behalf of a remote client or
+              outside process.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          Some of these limitations can be changed by editing the
+          <filename>mysql_embed.h</filename> include file and
+          recompiling MySQL.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-options">
+
+        <title id='title-libmysqld-options'>&title-libmysqld-options;</title>
+
+        <indexterm type="concept">
+          <primary>defaults</primary>
+          <secondary>embedded</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>options</primary>
+          <secondary>embedded server</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>options</primary>
+          <secondary>libmysqld</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>libmysqld</primary>
+          <secondary>options</secondary>
+        </indexterm>
+
+        <para>
+          Any options that may be given with the
+          <command>mysqld</command> server daemon, may be used with an
+          embedded server library. Server options may be given in an
+          array as an argument to the
+          <literal>mysql_server_init()</literal>, which initializes the
+          server. They also may be given in an option file like
+          <filename>my.cnf</filename>. To specify an option file for a C
+          program, use the <option>--defaults-file</option> option as
+          one of the elements of the second argument of the
+          <literal>mysql_server_init()</literal> function. See
+          <xref linkend="mysql-server-init"/> for more information on
+          the <literal>mysql_server_init()</literal> function.
+        </para>
+
+        <para>
+          Using option files can make it easier to switch between a
+          client/server application and one where MySQL is embedded. Put
+          common options under the <literal>[server]</literal> group.
+          These are read by both MySQL versions. Client/server-specific
+          options should go under the <literal>[mysqld]</literal>
+          section. Put options specific to the embedded MySQL server
+          library in the <literal>[embedded]</literal> section. Options
+          specific to applications go under section labeled
+          <literal>[ApplicationName_SERVER]</literal>. See
+          <xref linkend="option-files"/>.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-todo">
+
+        <title id='title-libmysqld-todo'>&title-libmysqld-todo;</title>
+
+        <indexterm type="concept">
+          <primary>TODO</primary>
+          <secondary>embedded server</secondary>
+        </indexterm>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              We are going to provide options to leave out some parts of
+              MySQL to make the library smaller.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              There is still a lot of speed optimization to do.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Errors are written to <literal>stderr</literal>. We will
+              add an option to specify a filename for these.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              We have to change InnoDB not to be so verbose when using
+              the embedded version. If your database does not contain
+              InnoDB tables, to suppress related messages you can add
+              the <option>--skip-innodb</option> option to the options
+              file under the group <literal>[libmysqd_server]</literal>,
+              or when initializing the server with
+              <command>mysql_server_init()</command>.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+      </section>
+
+      <section id="libmysqld-example">
+
+        <title id='title-libmysqld-example'>&title-libmysqld-example;</title>
+
+        <para>
+          These two example programs should work without any changes on
+          a Linux or FreeBSD system. For other operating systems, minor
+          changes are needed, mostly with file paths. These examples are
+          designed to give enough details for you to understand the
+          problem, without the clutter that is a necessary part of a
+          real application. The first example is very straightforward.
+          The second example is a little more advanced with some error
+          checking. The first is followed by a command-line entry for
+          compiling the program. The second is followed by a GNUmake
+          file that may be used for compiling instead.
+        </para>
+
+        <para>
+          <emphasis role="bold">Example 1</emphasis>
+        </para>
+
+        <para>
+          <filename>test1_libmysqld.c</filename>
+        </para>
+
+        <para>
+<programlisting>
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;stdarg.h&gt;
+#include "mysql.h"
+
+MYSQL *mysql;
+MYSQL_RES *results;
+MYSQL_ROW record;
+
+static char *server_options[] = { "mysql_test", "--defaults-file=my.cnf" };
+int num_elements = sizeof(server_options)/ sizeof(char *);
+
+static char *server_groups[] = { "libmysqld_server", "libmysqld_client" };
+
+int main(void)
+{
+   mysql_server_init(num_elements, server_options, server_groups);
+   mysql = mysql_init(NULL);
+   mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, "libmysqld_client");
+   mysql_options(mysql, MYSQL_OPT_USE_EMBEDDED_CONNECTION, NULL);
+
+   mysql_real_connect(mysql, NULL,NULL,NULL, "database1", 0,NULL,0);
+
+   mysql_query(mysql, "SELECT column1, column2 FROM table1");
+
+   results = mysql_store_result(mysql);
+
+   while((record = mysql_fetch_row(results))) {
+      printf("%s - %s \n", record[0], record[1]);
+   }
+
+   mysql_free_result(results);
+   mysql_close(mysql);
+   mysql_server_end();
+
+   return 0;
+}
+</programlisting>
+        </para>
+
+        <para>
+          Here is the command line for compiling the above program:
+        </para>
+
+<programlisting>
+gcc test1_libmysqld.c -o test1_libmysqld -lz \
+ `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
+</programlisting>
+
+        <para>
+          <emphasis role="bold">Example 2</emphasis>
+        </para>
+
+        <para>
+          To try out the example, create an
+          <filename>test2_libmysqld</filename> directory at the same
+          level as the mysql-4.0 source directory. Save the
+          <filename>test2_libmysqld.c</filename> source and the
+          <filename>GNUmakefile</filename> in the directory, and run GNU
+          <filename>make</filename> from inside the
+          <filename>test2_libmysqld</filename> directory.
+        </para>
+
+        <para>
+          <filename>test2_libmysqld.c</filename>
+        </para>
+
+        <para>
+<programlisting>
+/*
+ * A simple example client, using the embedded MySQL server library
+*/
+
+#include &lt;mysql.h&gt;
+#include &lt;stdarg.h&gt;
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+
+MYSQL *db_connect(const char *dbname);
+void db_disconnect(MYSQL *db);
+void db_do_query(MYSQL *db, const char *query);
+
+const char *server_groups[] = {
+  "test2_libmysqld_SERVER", "embedded", "server", NULL
+};
+
+int
+main(int argc, char **argv)
+{
+  MYSQL *one, *two;
+
+  /* mysql_server_init() must be called before any other mysql
+   * functions.
+   *
+   * You can use mysql_server_init(0, NULL, NULL), and it
+   * initializes the server using groups = {
+   *   "server", "embedded", NULL
+   *  }.
+   *
+   * In your $HOME/.my.cnf file, you probably want to put:
+
+[test2_libmysqld_SERVER]
+language = /path/to/source/of/mysql/sql/share/english
+
+   * You could, of course, modify argc and argv before passing
+   * them to this function.  Or you could create new ones in any
+   * way you like.  But all of the arguments in argv (except for
+   * argv[0], which is the program name) should be valid options
+   * for the MySQL server.
+   *
+   * If you link this client against the normal mysqlclient
+   * library, this function is just a stub that does nothing.
+   */
+  mysql_server_init(argc, argv, (char **)server_groups);
+
+  one = db_connect("test");
+  two = db_connect(NULL);
+
+  db_do_query(one, "SHOW TABLE STATUS");
+  db_do_query(two, "SHOW DATABASES");
+
+  mysql_close(two);
+  mysql_close(one);
+
+  /* This must be called after all other mysql functions */
+  mysql_server_end();
+
+  exit(EXIT_SUCCESS);
+}
+
+static void
+die(MYSQL *db, char *fmt, ...)
+{
+  va_list ap;
+  va_start(ap, fmt);
+  vfprintf(stderr, fmt, ap);
+  va_end(ap);
+  (void)putc('\n', stderr);
+  if (db)
+    db_disconnect(db);
+  exit(EXIT_FAILURE);
+}
+
+MYSQL *
+db_connect(const char *dbname)
+{
+  MYSQL *db = mysql_init(NULL);
+  if (!db)
+    die(db, "mysql_init failed: no memory");
+  /*
+   * Notice that the client and server use separate group names.
+   * This is critical, because the server does not accept the
+   * client's options, and vice versa.
+   */
+  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test2_libmysqld_CLIENT");
+  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
+    die(db, "mysql_real_connect failed: %s", mysql_error(db));
+
+  return db;
+}
+
+void
+db_disconnect(MYSQL *db)
+{
+  mysql_close(db);
+}
+
+void
+db_do_query(MYSQL *db, const char *query)
+{
+  if (mysql_query(db, query) != 0)
+    goto err;
+
+  if (mysql_field_count(db) &gt; 0)
+  {
+    MYSQL_RES   *res;
+    MYSQL_ROW    row, end_row;
+    int num_fields;
+
+    if (!(res = mysql_store_result(db)))
+      goto err;
+    num_fields = mysql_num_fields(res);
+    while ((row = mysql_fetch_row(res)))
+    {
+      (void)fputs("&gt;&gt; ", stdout);
+      for (end_row = row + num_fields; row &lt; end_row; ++row)
+        (void)printf("%s\t", row ? (char*)*row : "NULL");
+      (void)fputc('\n', stdout);
+    }
+    (void)fputc('\n', stdout);
+    mysql_free_result(res);
+  }
+  else
+    (void)printf("Affected rows: %lld\n", mysql_affected_rows(db));
+
+  return;
+
+err:
+  die(db, "db_do_query failed: %s [%s]", mysql_error(db), query);
+}
+</programlisting>
+        </para>
+
+        <para>
+          <filename>GNUmakefile</filename>
+
+<programlisting>
+# This assumes the MySQL software is installed in /usr/local/mysql
+inc      := /usr/local/mysql/include/mysql
+lib      := /usr/local/mysql/lib
+
+# If you have not installed the MySQL software yet, try this instead
+#inc      := $(HOME)/mysql-4.0/include
+#lib      := $(HOME)/mysql-4.0/libmysqld
+
+CC       := gcc
+CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
+CFLAGS   := -g -W -Wall
+LDFLAGS  := -static
+# You can change -lmysqld to -lmysqlclient to use the
+# client/server library
+LDLIBS    = -L$(lib) -lmysqld -lz -lm -lcrypt
+
+ifneq (,$(shell grep FreeBSD /COPYRIGHT 2&gt;/dev/null))
+# FreeBSD
+LDFLAGS += -pthread
+else
+# Assume Linux
+LDLIBS += -lpthread
+endif
+
+# This works for simple one-file test programs
+sources := $(wildcard *.c)
+objects := $(patsubst %c,%o,$(sources))
+targets := $(basename $(sources))
+
+all: $(targets)
+
+clean:
+        rm -f $(targets) $(objects) *.core
+</programlisting>
+        </para>
+
+      </section>
+
+      <section id="libmysqld-licensing">
+
+        <title id='title-libmysqld-licensing'>&title-libmysqld-licensing;</title>
+
+        <para>
+          We encourage everyone to promote free software by releasing
+          code under the GPL or a compatible license. For those who are
+          not able to do this, another option is to purchase a
+          commercial license for the MySQL code from MySQL AB. For
+          details, please see
+          <ulink url="http://www.mysql.com/company/legal/licensing/"/>.
+        </para>
+
+      </section>
+
+    </section>
+
   <section id="programming-utilities">
 
     <title id='title-programming-utilities'>&title-programming-utilities;</title>

--- 1.26/refman-4.1/mysql-apis.xml	2005-08-11 20:15:20 +02:00
+++ 1.27/refman-4.1/mysql-apis.xml	2005-08-11 21:16:06 +02:00
@@ -49,6 +49,619 @@
     basis for most of the other APIs.
   </para>
 
+    <section id="libmysqld">
+
+      <title id='title-libmysqld'>&title-libmysqld;</title>
+
+      <indexterm type="concept">
+        <primary>libmysqld</primary>
+      </indexterm>
+
+      <indexterm type="concept">
+        <primary>embedded MySQL server library</primary>
+      </indexterm>
+
+      <section id="libmysqld-overview">
+
+        <title id='title-libmysqld-overview'>&title-libmysqld-overview;</title>
+
+        <para>
+          The embedded MySQL server library makes it possible to run a
+          full-featured MySQL server inside a client application. The
+          main benefits are increased speed and more simple management
+          for embedded applications.
+        </para>
+
+        <para>
+          The embedded server library is based on the client/server
+          version of MySQL, which is written in C/C++. Consequently, the
+          embedded server also is written in C/C++. There is no embedded
+          server available in other languages.
+        </para>
+
+        <para>
+          The API is identical for the embedded MySQL version and the
+          client/server version. To change an old threaded application
+          to use the embedded library, you normally only have to add
+          calls to the following functions:
+        </para>
+
+        <informaltable>
+          <tgroup cols="2">
+            <colspec colwidth="25*"/>
+            <colspec colwidth="70*"/>
+            <tbody>
+              <row>
+                <entry><emphasis role="bold">Function</emphasis></entry>
+                <entry><emphasis role="bold">When to Call</emphasis></entry>
+              </row>
+              <row>
+                <entry><literal>mysql_server_init()</literal></entry>
+                <entry>Should be called before any other MySQL function is called, preferably
+                  early in the <literal>main()</literal> function.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_server_end()</literal></entry>
+                <entry>Should be called before your program exits.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_thread_init()</literal></entry>
+                <entry>Should be called in each thread you create that accesses MySQL.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_thread_end()</literal></entry>
+                <entry>Should be called before calling <literal>pthread_exit()</literal></entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+
+        <para>
+          Then you must link your code with
+          <filename>libmysqld.a</filename> instead of
+          <filename>libmysqlclient.a</filename>.
+        </para>
+
+        <para>
+          The
+          <literal>mysql_server_<replaceable>xxx</replaceable>()</literal>
+          functions are also included in
+          <filename>libmysqlclient.a</filename> to allow you to change
+          between the embedded and the client/server version by just
+          linking your application with the right library. See
+          <xref linkend="mysql-server-init"/>.
+        </para>
+
+        <para>
+          One difference between the embedded server and the standalone
+          server is that for the embedded server, authentication for
+          connections is disabled by default. To use authentication for
+          the embedded server, specify the
+          <option>--with-embedded-privilege-control</option> option when
+          you invoke <command>configure</command> to configure your
+          MySQL distribution. This option is available as of MySQL
+          4.1.3.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-compiling">
+
+        <title id='title-libmysqld-compiling'>&title-libmysqld-compiling;</title>
+
+        <para>
+          To get a <literal>libmysqld</literal> library you should
+          configure MySQL with the
+          <option>--with-embedded-server</option> option. See
+          <xref linkend="configure-options"/>.
+        </para>
+
+        <para>
+          When you link your program with <literal>libmysqld</literal>,
+          you must also include the system-specific
+          <literal>pthread</literal> libraries and some libraries that
+          the MySQL server uses. You can get the full list of libraries
+          by executing <command>mysql_config --libmysqld-libs</command>.
+        </para>
+
+        <para>
+          The correct flags for compiling and linking a threaded program
+          must be used, even if you do not directly call any thread
+          functions in your code.
+        </para>
+
+        <para>
+          To compile a C program to include the necessary files to embed
+          the MySQL server library into a compiled version of a program,
+          use the GNU C compiler (<literal>gcc</literal>). The compiler
+          will need to know where to find various files and need
+          instructions on how to compile the program. Below is an
+          example of how a program could be compiled from the
+          command-line:
+
+<programlisting>
+gcc mysql_test.c -o mysql_test -lz \
+`/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
+</programlisting>
+        </para>
+
+        <para>
+          Immediately following the <literal>gcc</literal> command is
+          the name of the uncompiled C program file. After it, the
+          <option>-o</option> option is given to indicate that the file
+          name that follows is the name that the compiler is to give to
+          the output file, the compiled program. The next line of code
+          tells the compiler to obtain the location of the include files
+          and libraries and other settings for the system on which it's
+          compiled. Because of a problem with
+          <command>mysql_config</command>, the option
+          <option>-lz</option> (for compression) is added here. The
+          <command>mysql_config</command> piece is contained in
+          backticks, not single quotes.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-restrictions">
+
+        <title id='title-libmysqld-restrictions'>&title-libmysqld-restrictions;</title>
+
+        <para>
+          The embedded server has the following limitations:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              No support for <literal>ISAM</literal> tables. (This is
+              mainly done to make the library smaller)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No user-defined functions (UDFs).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No stack trace on core dump.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No internal RAID support. (This is not normally needed as
+              most current operating systems support big files).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You cannot set this up as a master or a slave (no
+              replication).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Very large result sets may be unusable on low memory
+              systems.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You cannot connect to an embedded server from an outside
+              process with sockets or TCP/IP. However, you can connect
+              to an intermediate application, which in turn can connect
+              to an embedded server on the behalf of a remote client or
+              outside process.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          Some of these limitations can be changed by editing the
+          <filename>mysql_embed.h</filename> include file and
+          recompiling MySQL.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-options">
+
+        <title id='title-libmysqld-options'>&title-libmysqld-options;</title>
+
+        <indexterm type="concept">
+          <primary>defaults</primary>
+          <secondary>embedded</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>options</primary>
+          <secondary>embedded server</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>options</primary>
+          <secondary>libmysqld</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>libmysqld</primary>
+          <secondary>options</secondary>
+        </indexterm>
+
+        <para>
+          Any options that may be given with the
+          <command>mysqld</command> server daemon, may be used with an
+          embedded server library. Server options may be given in an
+          array as an argument to the
+          <literal>mysql_server_init()</literal>, which initializes the
+          server. They also may be given in an option file like
+          <filename>my.cnf</filename>. To specify an option file for a C
+          program, use the <option>--defaults-file</option> option as
+          one of the elements of the second argument of the
+          <literal>mysql_server_init()</literal> function. See
+          <xref linkend="mysql-server-init"/> for more information on
+          the <literal>mysql_server_init()</literal> function.
+        </para>
+
+        <para>
+          Using option files can make it easier to switch between a
+          client/server application and one where MySQL is embedded. Put
+          common options under the <literal>[server]</literal> group.
+          These are read by both MySQL versions. Client/server-specific
+          options should go under the <literal>[mysqld]</literal>
+          section. Put options specific to the embedded MySQL server
+          library in the <literal>[embedded]</literal> section. Options
+          specific to applications go under section labeled
+          <literal>[ApplicationName_SERVER]</literal>. See
+          <xref linkend="option-files"/>.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-todo">
+
+        <title id='title-libmysqld-todo'>&title-libmysqld-todo;</title>
+
+        <indexterm type="concept">
+          <primary>TODO</primary>
+          <secondary>embedded server</secondary>
+        </indexterm>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              We are going to provide options to leave out some parts of
+              MySQL to make the library smaller.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              There is still a lot of speed optimization to do.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Errors are written to <literal>stderr</literal>. We will
+              add an option to specify a filename for these.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              We have to change InnoDB not to be so verbose when using
+              the embedded version. If your database does not contain
+              InnoDB tables, to suppress related messages you can add
+              the <option>--skip-innodb</option> option to the options
+              file under the group <literal>[libmysqd_server]</literal>,
+              or when initializing the server with
+              <command>mysql_server_init()</command>.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+      </section>
+
+      <section id="libmysqld-example">
+
+        <title id='title-libmysqld-example'>&title-libmysqld-example;</title>
+
+        <para>
+          These two example programs should work without any changes on
+          a Linux or FreeBSD system. For other operating systems, minor
+          changes are needed, mostly with file paths. These examples are
+          designed to give enough details for you to understand the
+          problem, without the clutter that is a necessary part of a
+          real application. The first example is very straightforward.
+          The second example is a little more advanced with some error
+          checking. The first is followed by a command-line entry for
+          compiling the program. The second is followed by a GNUmake
+          file that may be used for compiling instead.
+        </para>
+
+        <para>
+          <emphasis role="bold">Example 1</emphasis>
+        </para>
+
+        <para>
+          <filename>test1_libmysqld.c</filename>
+        </para>
+
+        <para>
+<programlisting>
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;stdarg.h&gt;
+#include "mysql.h"
+
+MYSQL *mysql;
+MYSQL_RES *results;
+MYSQL_ROW record;
+
+static char *server_options[] = { "mysql_test", "--defaults-file=my.cnf" };
+int num_elements = sizeof(server_options)/ sizeof(char *);
+
+static char *server_groups[] = { "libmysqld_server", "libmysqld_client" };
+
+int main(void)
+{
+   mysql_server_init(num_elements, server_options, server_groups);
+   mysql = mysql_init(NULL);
+   mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, "libmysqld_client");
+   mysql_options(mysql, MYSQL_OPT_USE_EMBEDDED_CONNECTION, NULL);
+
+   mysql_real_connect(mysql, NULL,NULL,NULL, "database1", 0,NULL,0);
+
+   mysql_query(mysql, "SELECT column1, column2 FROM table1");
+
+   results = mysql_store_result(mysql);
+
+   while((record = mysql_fetch_row(results))) {
+      printf("%s - %s \n", record[0], record[1]);
+   }
+
+   mysql_free_result(results);
+   mysql_close(mysql);
+   mysql_server_end();
+
+   return 0;
+}
+</programlisting>
+        </para>
+
+        <para>
+          Here is the command line for compiling the above program:
+        </para>
+
+<programlisting>
+gcc test1_libmysqld.c -o test1_libmysqld -lz \
+ `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
+</programlisting>
+
+        <para>
+          <emphasis role="bold">Example 2</emphasis>
+        </para>
+
+        <para>
+          To try out the example, create an
+          <filename>test2_libmysqld</filename> directory at the same
+          level as the mysql-4.0 source directory. Save the
+          <filename>test2_libmysqld.c</filename> source and the
+          <filename>GNUmakefile</filename> in the directory, and run GNU
+          <filename>make</filename> from inside the
+          <filename>test2_libmysqld</filename> directory.
+        </para>
+
+        <para>
+          <filename>test2_libmysqld.c</filename>
+        </para>
+
+        <para>
+<programlisting>
+/*
+ * A simple example client, using the embedded MySQL server library
+*/
+
+#include &lt;mysql.h&gt;
+#include &lt;stdarg.h&gt;
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+
+MYSQL *db_connect(const char *dbname);
+void db_disconnect(MYSQL *db);
+void db_do_query(MYSQL *db, const char *query);
+
+const char *server_groups[] = {
+  "test2_libmysqld_SERVER", "embedded", "server", NULL
+};
+
+int
+main(int argc, char **argv)
+{
+  MYSQL *one, *two;
+
+  /* mysql_server_init() must be called before any other mysql
+   * functions.
+   *
+   * You can use mysql_server_init(0, NULL, NULL), and it
+   * initializes the server using groups = {
+   *   "server", "embedded", NULL
+   *  }.
+   *
+   * In your $HOME/.my.cnf file, you probably want to put:
+
+[test2_libmysqld_SERVER]
+language = /path/to/source/of/mysql/sql/share/english
+
+   * You could, of course, modify argc and argv before passing
+   * them to this function.  Or you could create new ones in any
+   * way you like.  But all of the arguments in argv (except for
+   * argv[0], which is the program name) should be valid options
+   * for the MySQL server.
+   *
+   * If you link this client against the normal mysqlclient
+   * library, this function is just a stub that does nothing.
+   */
+  mysql_server_init(argc, argv, (char **)server_groups);
+
+  one = db_connect("test");
+  two = db_connect(NULL);
+
+  db_do_query(one, "SHOW TABLE STATUS");
+  db_do_query(two, "SHOW DATABASES");
+
+  mysql_close(two);
+  mysql_close(one);
+
+  /* This must be called after all other mysql functions */
+  mysql_server_end();
+
+  exit(EXIT_SUCCESS);
+}
+
+static void
+die(MYSQL *db, char *fmt, ...)
+{
+  va_list ap;
+  va_start(ap, fmt);
+  vfprintf(stderr, fmt, ap);
+  va_end(ap);
+  (void)putc('\n', stderr);
+  if (db)
+    db_disconnect(db);
+  exit(EXIT_FAILURE);
+}
+
+MYSQL *
+db_connect(const char *dbname)
+{
+  MYSQL *db = mysql_init(NULL);
+  if (!db)
+    die(db, "mysql_init failed: no memory");
+  /*
+   * Notice that the client and server use separate group names.
+   * This is critical, because the server does not accept the
+   * client's options, and vice versa.
+   */
+  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test2_libmysqld_CLIENT");
+  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
+    die(db, "mysql_real_connect failed: %s", mysql_error(db));
+
+  return db;
+}
+
+void
+db_disconnect(MYSQL *db)
+{
+  mysql_close(db);
+}
+
+void
+db_do_query(MYSQL *db, const char *query)
+{
+  if (mysql_query(db, query) != 0)
+    goto err;
+
+  if (mysql_field_count(db) &gt; 0)
+  {
+    MYSQL_RES   *res;
+    MYSQL_ROW    row, end_row;
+    int num_fields;
+
+    if (!(res = mysql_store_result(db)))
+      goto err;
+    num_fields = mysql_num_fields(res);
+    while ((row = mysql_fetch_row(res)))
+    {
+      (void)fputs("&gt;&gt; ", stdout);
+      for (end_row = row + num_fields; row &lt; end_row; ++row)
+        (void)printf("%s\t", row ? (char*)*row : "NULL");
+      (void)fputc('\n', stdout);
+    }
+    (void)fputc('\n', stdout);
+    mysql_free_result(res);
+  }
+  else
+    (void)printf("Affected rows: %lld\n", mysql_affected_rows(db));
+
+  return;
+
+err:
+  die(db, "db_do_query failed: %s [%s]", mysql_error(db), query);
+}
+</programlisting>
+        </para>
+
+        <para>
+          <filename>GNUmakefile</filename>
+
+<programlisting>
+# This assumes the MySQL software is installed in /usr/local/mysql
+inc      := /usr/local/mysql/include/mysql
+lib      := /usr/local/mysql/lib
+
+# If you have not installed the MySQL software yet, try this instead
+#inc      := $(HOME)/mysql-4.0/include
+#lib      := $(HOME)/mysql-4.0/libmysqld
+
+CC       := gcc
+CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
+CFLAGS   := -g -W -Wall
+LDFLAGS  := -static
+# You can change -lmysqld to -lmysqlclient to use the
+# client/server library
+LDLIBS    = -L$(lib) -lmysqld -lz -lm -lcrypt
+
+ifneq (,$(shell grep FreeBSD /COPYRIGHT 2&gt;/dev/null))
+# FreeBSD
+LDFLAGS += -pthread
+else
+# Assume Linux
+LDLIBS += -lpthread
+endif
+
+# This works for simple one-file test programs
+sources := $(wildcard *.c)
+objects := $(patsubst %c,%o,$(sources))
+targets := $(basename $(sources))
+
+all: $(targets)
+
+clean:
+        rm -f $(targets) $(objects) *.core
+</programlisting>
+        </para>
+
+      </section>
+
+      <section id="libmysqld-licensing">
+
+        <title id='title-libmysqld-licensing'>&title-libmysqld-licensing;</title>
+
+        <para>
+          We encourage everyone to promote free software by releasing
+          code under the GPL or a compatible license. For those who are
+          not able to do this, another option is to purchase a
+          commercial license for the MySQL code from MySQL AB. For
+          details, please see
+          <ulink url="http://www.mysql.com/company/legal/licensing/"/>.
+        </para>
+
+      </section>
+
+    </section>
+
   <section id="programming-utilities">
 
     <title id='title-programming-utilities'>&title-programming-utilities;</title>
@@ -12215,619 +12828,6 @@
         most cases this is because you haven't included the thread
         libraries on the link/compile line.
       </para>
-
-    </section>
-
-    <section id="libmysqld">
-
-      <title id='title-libmysqld'>&title-libmysqld;</title>
-
-      <indexterm type="concept">
-        <primary>libmysqld</primary>
-      </indexterm>
-
-      <indexterm type="concept">
-        <primary>embedded MySQL server library</primary>
-      </indexterm>
-
-      <section id="libmysqld-overview">
-
-        <title id='title-libmysqld-overview'>&title-libmysqld-overview;</title>
-
-        <para>
-          The embedded MySQL server library makes it possible to run a
-          full-featured MySQL server inside a client application. The
-          main benefits are increased speed and more simple management
-          for embedded applications.
-        </para>
-
-        <para>
-          The embedded server library is based on the client/server
-          version of MySQL, which is written in C/C++. Consequently, the
-          embedded server also is written in C/C++. There is no embedded
-          server available in other languages.
-        </para>
-
-        <para>
-          The API is identical for the embedded MySQL version and the
-          client/server version. To change an old threaded application
-          to use the embedded library, you normally only have to add
-          calls to the following functions:
-        </para>
-
-        <informaltable>
-          <tgroup cols="2">
-            <colspec colwidth="25*"/>
-            <colspec colwidth="70*"/>
-            <tbody>
-              <row>
-                <entry><emphasis role="bold">Function</emphasis></entry>
-                <entry><emphasis role="bold">When to Call</emphasis></entry>
-              </row>
-              <row>
-                <entry><literal>mysql_server_init()</literal></entry>
-                <entry>Should be called before any other MySQL function is called, preferably
-                  early in the <literal>main()</literal> function.</entry>
-              </row>
-              <row>
-                <entry><literal>mysql_server_end()</literal></entry>
-                <entry>Should be called before your program exits.</entry>
-              </row>
-              <row>
-                <entry><literal>mysql_thread_init()</literal></entry>
-                <entry>Should be called in each thread you create that accesses MySQL.</entry>
-              </row>
-              <row>
-                <entry><literal>mysql_thread_end()</literal></entry>
-                <entry>Should be called before calling <literal>pthread_exit()</literal></entry>
-              </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-
-        <para>
-          Then you must link your code with
-          <filename>libmysqld.a</filename> instead of
-          <filename>libmysqlclient.a</filename>.
-        </para>
-
-        <para>
-          The
-          <literal>mysql_server_<replaceable>xxx</replaceable>()</literal>
-          functions are also included in
-          <filename>libmysqlclient.a</filename> to allow you to change
-          between the embedded and the client/server version by just
-          linking your application with the right library. See
-          <xref linkend="mysql-server-init"/>.
-        </para>
-
-        <para>
-          One difference between the embedded server and the standalone
-          server is that for the embedded server, authentication for
-          connections is disabled by default. To use authentication for
-          the embedded server, specify the
-          <option>--with-embedded-privilege-control</option> option when
-          you invoke <command>configure</command> to configure your
-          MySQL distribution. This option is available as of MySQL
-          4.1.3.
-        </para>
-
-      </section>
-
-      <section id="libmysqld-compiling">
-
-        <title id='title-libmysqld-compiling'>&title-libmysqld-compiling;</title>
-
-        <para>
-          To get a <literal>libmysqld</literal> library you should
-          configure MySQL with the
-          <option>--with-embedded-server</option> option. See
-          <xref linkend="configure-options"/>.
-        </para>
-
-        <para>
-          When you link your program with <literal>libmysqld</literal>,
-          you must also include the system-specific
-          <literal>pthread</literal> libraries and some libraries that
-          the MySQL server uses. You can get the full list of libraries
-          by executing <command>mysql_config --libmysqld-libs</command>.
-        </para>
-
-        <para>
-          The correct flags for compiling and linking a threaded program
-          must be used, even if you do not directly call any thread
-          functions in your code.
-        </para>
-
-        <para>
-          To compile a C program to include the necessary files to embed
-          the MySQL server library into a compiled version of a program,
-          use the GNU C compiler (<literal>gcc</literal>). The compiler
-          will need to know where to find various files and need
-          instructions on how to compile the program. Below is an
-          example of how a program could be compiled from the
-          command-line:
-
-<programlisting>
-gcc mysql_test.c -o mysql_test -lz \
-`/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
-</programlisting>
-        </para>
-
-        <para>
-          Immediately following the <literal>gcc</literal> command is
-          the name of the uncompiled C program file. After it, the
-          <option>-o</option> option is given to indicate that the file
-          name that follows is the name that the compiler is to give to
-          the output file, the compiled program. The next line of code
-          tells the compiler to obtain the location of the include files
-          and libraries and other settings for the system on which it's
-          compiled. Because of a problem with
-          <command>mysql_config</command>, the option
-          <option>-lz</option> (for compression) is added here. The
-          <command>mysql_config</command> piece is contained in
-          backticks, not single quotes.
-        </para>
-
-      </section>
-
-      <section id="libmysqld-restrictions">
-
-        <title id='title-libmysqld-restrictions'>&title-libmysqld-restrictions;</title>
-
-        <para>
-          The embedded server has the following limitations:
-        </para>
-
-        <itemizedlist>
-
-          <listitem>
-            <para>
-              No support for <literal>ISAM</literal> tables. (This is
-              mainly done to make the library smaller)
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              No user-defined functions (UDFs).
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              No stack trace on core dump.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              No internal RAID support. (This is not normally needed as
-              most current operating systems support big files).
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              You cannot set this up as a master or a slave (no
-              replication).
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              Very large result sets may be unusable on low memory
-              systems.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              You cannot connect to an embedded server from an outside
-              process with sockets or TCP/IP. However, you can connect
-              to an intermediate application, which in turn can connect
-              to an embedded server on the behalf of a remote client or
-              outside process.
-            </para>
-          </listitem>
-
-        </itemizedlist>
-
-        <para>
-          Some of these limitations can be changed by editing the
-          <filename>mysql_embed.h</filename> include file and
-          recompiling MySQL.
-        </para>
-
-      </section>
-
-      <section id="libmysqld-options">
-
-        <title id='title-libmysqld-options'>&title-libmysqld-options;</title>
-
-        <indexterm type="concept">
-          <primary>defaults</primary>
-          <secondary>embedded</secondary>
-        </indexterm>
-
-        <indexterm type="concept">
-          <primary>options</primary>
-          <secondary>embedded server</secondary>
-        </indexterm>
-
-        <indexterm type="concept">
-          <primary>options</primary>
-          <secondary>libmysqld</secondary>
-        </indexterm>
-
-        <indexterm type="concept">
-          <primary>libmysqld</primary>
-          <secondary>options</secondary>
-        </indexterm>
-
-        <para>
-          Any options that may be given with the
-          <command>mysqld</command> server daemon, may be used with an
-          embedded server library. Server options may be given in an
-          array as an argument to the
-          <literal>mysql_server_init()</literal>, which initializes the
-          server. They also may be given in an option file like
-          <filename>my.cnf</filename>. To specify an option file for a C
-          program, use the <option>--defaults-file</option> option as
-          one of the elements of the second argument of the
-          <literal>mysql_server_init()</literal> function. See
-          <xref linkend="mysql-server-init"/> for more information on
-          the <literal>mysql_server_init()</literal> function.
-        </para>
-
-        <para>
-          Using option files can make it easier to switch between a
-          client/server application and one where MySQL is embedded. Put
-          common options under the <literal>[server]</literal> group.
-          These are read by both MySQL versions. Client/server-specific
-          options should go under the <literal>[mysqld]</literal>
-          section. Put options specific to the embedded MySQL server
-          library in the <literal>[embedded]</literal> section. Options
-          specific to applications go under section labeled
-          <literal>[ApplicationName_SERVER]</literal>. See
-          <xref linkend="option-files"/>.
-        </para>
-
-      </section>
-
-      <section id="libmysqld-todo">
-
-        <title id='title-libmysqld-todo'>&title-libmysqld-todo;</title>
-
-        <indexterm type="concept">
-          <primary>TODO</primary>
-          <secondary>embedded server</secondary>
-        </indexterm>
-
-        <itemizedlist>
-
-          <listitem>
-            <para>
-              We are going to provide options to leave out some parts of
-              MySQL to make the library smaller.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              There is still a lot of speed optimization to do.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              Errors are written to <literal>stderr</literal>. We will
-              add an option to specify a filename for these.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              We have to change InnoDB not to be so verbose when using
-              the embedded version. If your database does not contain
-              InnoDB tables, to suppress related messages you can add
-              the <option>--skip-innodb</option> option to the options
-              file under the group <literal>[libmysqd_server]</literal>,
-              or when initializing the server with
-              <command>mysql_server_init()</command>.
-            </para>
-          </listitem>
-
-        </itemizedlist>
-
-      </section>
-
-      <section id="libmysqld-example">
-
-        <title id='title-libmysqld-example'>&title-libmysqld-example;</title>
-
-        <para>
-          These two example programs should work without any changes on
-          a Linux or FreeBSD system. For other operating systems, minor
-          changes are needed, mostly with file paths. These examples are
-          designed to give enough details for you to understand the
-          problem, without the clutter that is a necessary part of a
-          real application. The first example is very straightforward.
-          The second example is a little more advanced with some error
-          checking. The first is followed by a command-line entry for
-          compiling the program. The second is followed by a GNUmake
-          file that may be used for compiling instead.
-        </para>
-
-        <para>
-          <emphasis role="bold">Example 1</emphasis>
-        </para>
-
-        <para>
-          <filename>test1_libmysqld.c</filename>
-        </para>
-
-        <para>
-<programlisting>
-#include &lt;stdio.h&gt;
-#include &lt;stdlib.h&gt;
-#include &lt;stdarg.h&gt;
-#include "mysql.h"
-
-MYSQL *mysql;
-MYSQL_RES *results;
-MYSQL_ROW record;
-
-static char *server_options[] = { "mysql_test", "--defaults-file=my.cnf" };
-int num_elements = sizeof(server_options)/ sizeof(char *);
-
-static char *server_groups[] = { "libmysqld_server", "libmysqld_client" };
-
-int main(void)
-{
-   mysql_server_init(num_elements, server_options, server_groups);
-   mysql = mysql_init(NULL);
-   mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, "libmysqld_client");
-   mysql_options(mysql, MYSQL_OPT_USE_EMBEDDED_CONNECTION, NULL);
-
-   mysql_real_connect(mysql, NULL,NULL,NULL, "database1", 0,NULL,0);
-
-   mysql_query(mysql, "SELECT column1, column2 FROM table1");
-
-   results = mysql_store_result(mysql);
-
-   while((record = mysql_fetch_row(results))) {
-      printf("%s - %s \n", record[0], record[1]);
-   }
-
-   mysql_free_result(results);
-   mysql_close(mysql);
-   mysql_server_end();
-
-   return 0;
-}
-</programlisting>
-        </para>
-
-        <para>
-          Here is the command line for compiling the above program:
-        </para>
-
-<programlisting>
-gcc test1_libmysqld.c -o test1_libmysqld -lz \
- `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
-</programlisting>
-
-        <para>
-          <emphasis role="bold">Example 2</emphasis>
-        </para>
-
-        <para>
-          To try out the example, create an
-          <filename>test2_libmysqld</filename> directory at the same
-          level as the mysql-4.0 source directory. Save the
-          <filename>test2_libmysqld.c</filename> source and the
-          <filename>GNUmakefile</filename> in the directory, and run GNU
-          <filename>make</filename> from inside the
-          <filename>test2_libmysqld</filename> directory.
-        </para>
-
-        <para>
-          <filename>test2_libmysqld.c</filename>
-        </para>
-
-        <para>
-<programlisting>
-/*
- * A simple example client, using the embedded MySQL server library
-*/
-
-#include &lt;mysql.h&gt;
-#include &lt;stdarg.h&gt;
-#include &lt;stdio.h&gt;
-#include &lt;stdlib.h&gt;
-
-MYSQL *db_connect(const char *dbname);
-void db_disconnect(MYSQL *db);
-void db_do_query(MYSQL *db, const char *query);
-
-const char *server_groups[] = {
-  "test2_libmysqld_SERVER", "embedded", "server", NULL
-};
-
-int
-main(int argc, char **argv)
-{
-  MYSQL *one, *two;
-
-  /* mysql_server_init() must be called before any other mysql
-   * functions.
-   *
-   * You can use mysql_server_init(0, NULL, NULL), and it
-   * initializes the server using groups = {
-   *   "server", "embedded", NULL
-   *  }.
-   *
-   * In your $HOME/.my.cnf file, you probably want to put:
-
-[test2_libmysqld_SERVER]
-language = /path/to/source/of/mysql/sql/share/english
-
-   * You could, of course, modify argc and argv before passing
-   * them to this function.  Or you could create new ones in any
-   * way you like.  But all of the arguments in argv (except for
-   * argv[0], which is the program name) should be valid options
-   * for the MySQL server.
-   *
-   * If you link this client against the normal mysqlclient
-   * library, this function is just a stub that does nothing.
-   */
-  mysql_server_init(argc, argv, (char **)server_groups);
-
-  one = db_connect("test");
-  two = db_connect(NULL);
-
-  db_do_query(one, "SHOW TABLE STATUS");
-  db_do_query(two, "SHOW DATABASES");
-
-  mysql_close(two);
-  mysql_close(one);
-
-  /* This must be called after all other mysql functions */
-  mysql_server_end();
-
-  exit(EXIT_SUCCESS);
-}
-
-static void
-die(MYSQL *db, char *fmt, ...)
-{
-  va_list ap;
-  va_start(ap, fmt);
-  vfprintf(stderr, fmt, ap);
-  va_end(ap);
-  (void)putc('\n', stderr);
-  if (db)
-    db_disconnect(db);
-  exit(EXIT_FAILURE);
-}
-
-MYSQL *
-db_connect(const char *dbname)
-{
-  MYSQL *db = mysql_init(NULL);
-  if (!db)
-    die(db, "mysql_init failed: no memory");
-  /*
-   * Notice that the client and server use separate group names.
-   * This is critical, because the server does not accept the
-   * client's options, and vice versa.
-   */
-  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test2_libmysqld_CLIENT");
-  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
-    die(db, "mysql_real_connect failed: %s", mysql_error(db));
-
-  return db;
-}
-
-void
-db_disconnect(MYSQL *db)
-{
-  mysql_close(db);
-}
-
-void
-db_do_query(MYSQL *db, const char *query)
-{
-  if (mysql_query(db, query) != 0)
-    goto err;
-
-  if (mysql_field_count(db) &gt; 0)
-  {
-    MYSQL_RES   *res;
-    MYSQL_ROW    row, end_row;
-    int num_fields;
-
-    if (!(res = mysql_store_result(db)))
-      goto err;
-    num_fields = mysql_num_fields(res);
-    while ((row = mysql_fetch_row(res)))
-    {
-      (void)fputs("&gt;&gt; ", stdout);
-      for (end_row = row + num_fields; row &lt; end_row; ++row)
-        (void)printf("%s\t", row ? (char*)*row : "NULL");
-      (void)fputc('\n', stdout);
-    }
-    (void)fputc('\n', stdout);
-    mysql_free_result(res);
-  }
-  else
-    (void)printf("Affected rows: %lld\n", mysql_affected_rows(db));
-
-  return;
-
-err:
-  die(db, "db_do_query failed: %s [%s]", mysql_error(db), query);
-}
-</programlisting>
-        </para>
-
-        <para>
-          <filename>GNUmakefile</filename>
-
-<programlisting>
-# This assumes the MySQL software is installed in /usr/local/mysql
-inc      := /usr/local/mysql/include/mysql
-lib      := /usr/local/mysql/lib
-
-# If you have not installed the MySQL software yet, try this instead
-#inc      := $(HOME)/mysql-4.0/include
-#lib      := $(HOME)/mysql-4.0/libmysqld
-
-CC       := gcc
-CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
-CFLAGS   := -g -W -Wall
-LDFLAGS  := -static
-# You can change -lmysqld to -lmysqlclient to use the
-# client/server library
-LDLIBS    = -L$(lib) -lmysqld -lz -lm -lcrypt
-
-ifneq (,$(shell grep FreeBSD /COPYRIGHT 2&gt;/dev/null))
-# FreeBSD
-LDFLAGS += -pthread
-else
-# Assume Linux
-LDLIBS += -lpthread
-endif
-
-# This works for simple one-file test programs
-sources := $(wildcard *.c)
-objects := $(patsubst %c,%o,$(sources))
-targets := $(basename $(sources))
-
-all: $(targets)
-
-clean:
-        rm -f $(targets) $(objects) *.core
-</programlisting>
-        </para>
-
-      </section>
-
-      <section id="libmysqld-licensing">
-
-        <title id='title-libmysqld-licensing'>&title-libmysqld-licensing;</title>
-
-        <para>
-          We encourage everyone to promote free software by releasing
-          code under the GPL or a compatible license. For those who are
-          not able to do this, another option is to purchase a
-          commercial license for the MySQL code from MySQL AB. For
-          details, please see
-          <ulink url="http://www.mysql.com/company/legal/licensing/"/>.
-        </para>
-
-      </section>
 
     </section>
 

--- 1.30/refman/mysql-apis.xml	2005-08-11 20:15:20 +02:00
+++ 1.31/refman/mysql-apis.xml	2005-08-11 21:15:28 +02:00
@@ -49,6 +49,619 @@
     basis for most of the other APIs.
   </para>
 
+    <section id="libmysqld">
+
+      <title id='title-libmysqld'>&title-libmysqld;</title>
+
+      <indexterm type="concept">
+        <primary>libmysqld</primary>
+      </indexterm>
+
+      <indexterm type="concept">
+        <primary>embedded MySQL server library</primary>
+      </indexterm>
+
+      <section id="libmysqld-overview">
+
+        <title id='title-libmysqld-overview'>&title-libmysqld-overview;</title>
+
+        <para>
+          The embedded MySQL server library makes it possible to run a
+          full-featured MySQL server inside a client application. The
+          main benefits are increased speed and more simple management
+          for embedded applications.
+        </para>
+
+        <para>
+          The embedded server library is based on the client/server
+          version of MySQL, which is written in C/C++. Consequently, the
+          embedded server also is written in C/C++. There is no embedded
+          server available in other languages.
+        </para>
+
+        <para>
+          The API is identical for the embedded MySQL version and the
+          client/server version. To change an old threaded application
+          to use the embedded library, you normally only have to add
+          calls to the following functions:
+        </para>
+
+        <informaltable>
+          <tgroup cols="2">
+            <colspec colwidth="25*"/>
+            <colspec colwidth="70*"/>
+            <tbody>
+              <row>
+                <entry><emphasis role="bold">Function</emphasis></entry>
+                <entry><emphasis role="bold">When to Call</emphasis></entry>
+              </row>
+              <row>
+                <entry><literal>mysql_server_init()</literal></entry>
+                <entry>Should be called before any other MySQL function is called, preferably
+                  early in the <literal>main()</literal> function.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_server_end()</literal></entry>
+                <entry>Should be called before your program exits.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_thread_init()</literal></entry>
+                <entry>Should be called in each thread you create that accesses MySQL.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_thread_end()</literal></entry>
+                <entry>Should be called before calling <literal>pthread_exit()</literal></entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+
+        <para>
+          Then you must link your code with
+          <filename>libmysqld.a</filename> instead of
+          <filename>libmysqlclient.a</filename>.
+        </para>
+
+        <para>
+          The
+          <literal>mysql_server_<replaceable>xxx</replaceable>()</literal>
+          functions are also included in
+          <filename>libmysqlclient.a</filename> to allow you to change
+          between the embedded and the client/server version by just
+          linking your application with the right library. See
+          <xref linkend="mysql-server-init"/>.
+        </para>
+
+        <para>
+          One difference between the embedded server and the standalone
+          server is that for the embedded server, authentication for
+          connections is disabled by default. To use authentication for
+          the embedded server, specify the
+          <option>--with-embedded-privilege-control</option> option when
+          you invoke <command>configure</command> to configure your
+          MySQL distribution. This option is available as of MySQL
+          4.1.3.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-compiling">
+
+        <title id='title-libmysqld-compiling'>&title-libmysqld-compiling;</title>
+
+        <para>
+          To get a <literal>libmysqld</literal> library you should
+          configure MySQL with the
+          <option>--with-embedded-server</option> option. See
+          <xref linkend="configure-options"/>.
+        </para>
+
+        <para>
+          When you link your program with <literal>libmysqld</literal>,
+          you must also include the system-specific
+          <literal>pthread</literal> libraries and some libraries that
+          the MySQL server uses. You can get the full list of libraries
+          by executing <command>mysql_config --libmysqld-libs</command>.
+        </para>
+
+        <para>
+          The correct flags for compiling and linking a threaded program
+          must be used, even if you do not directly call any thread
+          functions in your code.
+        </para>
+
+        <para>
+          To compile a C program to include the necessary files to embed
+          the MySQL server library into a compiled version of a program,
+          use the GNU C compiler (<literal>gcc</literal>). The compiler
+          will need to know where to find various files and need
+          instructions on how to compile the program. Below is an
+          example of how a program could be compiled from the
+          command-line:
+
+<programlisting>
+gcc mysql_test.c -o mysql_test -lz \
+`/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
+</programlisting>
+        </para>
+
+        <para>
+          Immediately following the <literal>gcc</literal> command is
+          the name of the uncompiled C program file. After it, the
+          <option>-o</option> option is given to indicate that the file
+          name that follows is the name that the compiler is to give to
+          the output file, the compiled program. The next line of code
+          tells the compiler to obtain the location of the include files
+          and libraries and other settings for the system on which it's
+          compiled. Because of a problem with
+          <command>mysql_config</command>, the option
+          <option>-lz</option> (for compression) is added here. The
+          <command>mysql_config</command> piece is contained in
+          backticks, not single quotes.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-restrictions">
+
+        <title id='title-libmysqld-restrictions'>&title-libmysqld-restrictions;</title>
+
+        <para>
+          The embedded server has the following limitations:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              No support for <literal>ISAM</literal> tables. (This is
+              mainly done to make the library smaller)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No user-defined functions (UDFs).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No stack trace on core dump.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No internal RAID support. (This is not normally needed as
+              most current operating systems support big files).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You cannot set this up as a master or a slave (no
+              replication).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Very large result sets may be unusable on low memory
+              systems.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You cannot connect to an embedded server from an outside
+              process with sockets or TCP/IP. However, you can connect
+              to an intermediate application, which in turn can connect
+              to an embedded server on the behalf of a remote client or
+              outside process.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          Some of these limitations can be changed by editing the
+          <filename>mysql_embed.h</filename> include file and
+          recompiling MySQL.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-options">
+
+        <title id='title-libmysqld-options'>&title-libmysqld-options;</title>
+
+        <indexterm type="concept">
+          <primary>defaults</primary>
+          <secondary>embedded</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>options</primary>
+          <secondary>embedded server</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>options</primary>
+          <secondary>libmysqld</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>libmysqld</primary>
+          <secondary>options</secondary>
+        </indexterm>
+
+        <para>
+          Any options that may be given with the
+          <command>mysqld</command> server daemon, may be used with an
+          embedded server library. Server options may be given in an
+          array as an argument to the
+          <literal>mysql_server_init()</literal>, which initializes the
+          server. They also may be given in an option file like
+          <filename>my.cnf</filename>. To specify an option file for a C
+          program, use the <option>--defaults-file</option> option as
+          one of the elements of the second argument of the
+          <literal>mysql_server_init()</literal> function. See
+          <xref linkend="mysql-server-init"/> for more information on
+          the <literal>mysql_server_init()</literal> function.
+        </para>
+
+        <para>
+          Using option files can make it easier to switch between a
+          client/server application and one where MySQL is embedded. Put
+          common options under the <literal>[server]</literal> group.
+          These are read by both MySQL versions. Client/server-specific
+          options should go under the <literal>[mysqld]</literal>
+          section. Put options specific to the embedded MySQL server
+          library in the <literal>[embedded]</literal> section. Options
+          specific to applications go under section labeled
+          <literal>[ApplicationName_SERVER]</literal>. See
+          <xref linkend="option-files"/>.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-todo">
+
+        <title id='title-libmysqld-todo'>&title-libmysqld-todo;</title>
+
+        <indexterm type="concept">
+          <primary>TODO</primary>
+          <secondary>embedded server</secondary>
+        </indexterm>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              We are going to provide options to leave out some parts of
+              MySQL to make the library smaller.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              There is still a lot of speed optimization to do.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Errors are written to <literal>stderr</literal>. We will
+              add an option to specify a filename for these.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              We have to change InnoDB not to be so verbose when using
+              the embedded version. If your database does not contain
+              InnoDB tables, to suppress related messages you can add
+              the <option>--skip-innodb</option> option to the options
+              file under the group <literal>[libmysqd_server]</literal>,
+              or when initializing the server with
+              <command>mysql_server_init()</command>.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+      </section>
+
+      <section id="libmysqld-example">
+
+        <title id='title-libmysqld-example'>&title-libmysqld-example;</title>
+
+        <para>
+          These two example programs should work without any changes on
+          a Linux or FreeBSD system. For other operating systems, minor
+          changes are needed, mostly with file paths. These examples are
+          designed to give enough details for you to understand the
+          problem, without the clutter that is a necessary part of a
+          real application. The first example is very straightforward.
+          The second example is a little more advanced with some error
+          checking. The first is followed by a command-line entry for
+          compiling the program. The second is followed by a GNUmake
+          file that may be used for compiling instead.
+        </para>
+
+        <para>
+          <emphasis role="bold">Example 1</emphasis>
+        </para>
+
+        <para>
+          <filename>test1_libmysqld.c</filename>
+        </para>
+
+        <para>
+<programlisting>
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;stdarg.h&gt;
+#include "mysql.h"
+
+MYSQL *mysql;
+MYSQL_RES *results;
+MYSQL_ROW record;
+
+static char *server_options[] = { "mysql_test", "--defaults-file=my.cnf" };
+int num_elements = sizeof(server_options)/ sizeof(char *);
+
+static char *server_groups[] = { "libmysqld_server", "libmysqld_client" };
+
+int main(void)
+{
+   mysql_server_init(num_elements, server_options, server_groups);
+   mysql = mysql_init(NULL);
+   mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, "libmysqld_client");
+   mysql_options(mysql, MYSQL_OPT_USE_EMBEDDED_CONNECTION, NULL);
+
+   mysql_real_connect(mysql, NULL,NULL,NULL, "database1", 0,NULL,0);
+
+   mysql_query(mysql, "SELECT column1, column2 FROM table1");
+
+   results = mysql_store_result(mysql);
+
+   while((record = mysql_fetch_row(results))) {
+      printf("%s - %s \n", record[0], record[1]);
+   }
+
+   mysql_free_result(results);
+   mysql_close(mysql);
+   mysql_server_end();
+
+   return 0;
+}
+</programlisting>
+        </para>
+
+        <para>
+          Here is the command line for compiling the above program:
+        </para>
+
+<programlisting>
+gcc test1_libmysqld.c -o test1_libmysqld -lz \
+ `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
+</programlisting>
+
+        <para>
+          <emphasis role="bold">Example 2</emphasis>
+        </para>
+
+        <para>
+          To try out the example, create an
+          <filename>test2_libmysqld</filename> directory at the same
+          level as the mysql-4.0 source directory. Save the
+          <filename>test2_libmysqld.c</filename> source and the
+          <filename>GNUmakefile</filename> in the directory, and run GNU
+          <filename>make</filename> from inside the
+          <filename>test2_libmysqld</filename> directory.
+        </para>
+
+        <para>
+          <filename>test2_libmysqld.c</filename>
+        </para>
+
+        <para>
+<programlisting>
+/*
+ * A simple example client, using the embedded MySQL server library
+*/
+
+#include &lt;mysql.h&gt;
+#include &lt;stdarg.h&gt;
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+
+MYSQL *db_connect(const char *dbname);
+void db_disconnect(MYSQL *db);
+void db_do_query(MYSQL *db, const char *query);
+
+const char *server_groups[] = {
+  "test2_libmysqld_SERVER", "embedded", "server", NULL
+};
+
+int
+main(int argc, char **argv)
+{
+  MYSQL *one, *two;
+
+  /* mysql_server_init() must be called before any other mysql
+   * functions.
+   *
+   * You can use mysql_server_init(0, NULL, NULL), and it
+   * initializes the server using groups = {
+   *   "server", "embedded", NULL
+   *  }.
+   *
+   * In your $HOME/.my.cnf file, you probably want to put:
+
+[test2_libmysqld_SERVER]
+language = /path/to/source/of/mysql/sql/share/english
+
+   * You could, of course, modify argc and argv before passing
+   * them to this function.  Or you could create new ones in any
+   * way you like.  But all of the arguments in argv (except for
+   * argv[0], which is the program name) should be valid options
+   * for the MySQL server.
+   *
+   * If you link this client against the normal mysqlclient
+   * library, this function is just a stub that does nothing.
+   */
+  mysql_server_init(argc, argv, (char **)server_groups);
+
+  one = db_connect("test");
+  two = db_connect(NULL);
+
+  db_do_query(one, "SHOW TABLE STATUS");
+  db_do_query(two, "SHOW DATABASES");
+
+  mysql_close(two);
+  mysql_close(one);
+
+  /* This must be called after all other mysql functions */
+  mysql_server_end();
+
+  exit(EXIT_SUCCESS);
+}
+
+static void
+die(MYSQL *db, char *fmt, ...)
+{
+  va_list ap;
+  va_start(ap, fmt);
+  vfprintf(stderr, fmt, ap);
+  va_end(ap);
+  (void)putc('\n', stderr);
+  if (db)
+    db_disconnect(db);
+  exit(EXIT_FAILURE);
+}
+
+MYSQL *
+db_connect(const char *dbname)
+{
+  MYSQL *db = mysql_init(NULL);
+  if (!db)
+    die(db, "mysql_init failed: no memory");
+  /*
+   * Notice that the client and server use separate group names.
+   * This is critical, because the server does not accept the
+   * client's options, and vice versa.
+   */
+  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test2_libmysqld_CLIENT");
+  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
+    die(db, "mysql_real_connect failed: %s", mysql_error(db));
+
+  return db;
+}
+
+void
+db_disconnect(MYSQL *db)
+{
+  mysql_close(db);
+}
+
+void
+db_do_query(MYSQL *db, const char *query)
+{
+  if (mysql_query(db, query) != 0)
+    goto err;
+
+  if (mysql_field_count(db) &gt; 0)
+  {
+    MYSQL_RES   *res;
+    MYSQL_ROW    row, end_row;
+    int num_fields;
+
+    if (!(res = mysql_store_result(db)))
+      goto err;
+    num_fields = mysql_num_fields(res);
+    while ((row = mysql_fetch_row(res)))
+    {
+      (void)fputs("&gt;&gt; ", stdout);
+      for (end_row = row + num_fields; row &lt; end_row; ++row)
+        (void)printf("%s\t", row ? (char*)*row : "NULL");
+      (void)fputc('\n', stdout);
+    }
+    (void)fputc('\n', stdout);
+    mysql_free_result(res);
+  }
+  else
+    (void)printf("Affected rows: %lld\n", mysql_affected_rows(db));
+
+  return;
+
+err:
+  die(db, "db_do_query failed: %s [%s]", mysql_error(db), query);
+}
+</programlisting>
+        </para>
+
+        <para>
+          <filename>GNUmakefile</filename>
+
+<programlisting>
+# This assumes the MySQL software is installed in /usr/local/mysql
+inc      := /usr/local/mysql/include/mysql
+lib      := /usr/local/mysql/lib
+
+# If you have not installed the MySQL software yet, try this instead
+#inc      := $(HOME)/mysql-4.0/include
+#lib      := $(HOME)/mysql-4.0/libmysqld
+
+CC       := gcc
+CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
+CFLAGS   := -g -W -Wall
+LDFLAGS  := -static
+# You can change -lmysqld to -lmysqlclient to use the
+# client/server library
+LDLIBS    = -L$(lib) -lmysqld -lz -lm -lcrypt
+
+ifneq (,$(shell grep FreeBSD /COPYRIGHT 2&gt;/dev/null))
+# FreeBSD
+LDFLAGS += -pthread
+else
+# Assume Linux
+LDLIBS += -lpthread
+endif
+
+# This works for simple one-file test programs
+sources := $(wildcard *.c)
+objects := $(patsubst %c,%o,$(sources))
+targets := $(basename $(sources))
+
+all: $(targets)
+
+clean:
+        rm -f $(targets) $(objects) *.core
+</programlisting>
+        </para>
+
+      </section>
+
+      <section id="libmysqld-licensing">
+
+        <title id='title-libmysqld-licensing'>&title-libmysqld-licensing;</title>
+
+        <para>
+          We encourage everyone to promote free software by releasing
+          code under the GPL or a compatible license. For those who are
+          not able to do this, another option is to purchase a
+          commercial license for the MySQL code from MySQL AB. For
+          details, please see
+          <ulink url="http://www.mysql.com/company/legal/licensing/"/>.
+        </para>
+
+      </section>
+
+    </section>
+
   <section id="programming-utilities">
 
     <title id='title-programming-utilities'>&title-programming-utilities;</title>
@@ -12286,619 +12899,6 @@
         most cases this is because you haven't included the thread
         libraries on the link/compile line.
       </para>
-
-    </section>
-
-    <section id="libmysqld">
-
-      <title id='title-libmysqld'>&title-libmysqld;</title>
-
-      <indexterm type="concept">
-        <primary>libmysqld</primary>
-      </indexterm>
-
-      <indexterm type="concept">
-        <primary>embedded MySQL server library</primary>
-      </indexterm>
-
-      <section id="libmysqld-overview">
-
-        <title id='title-libmysqld-overview'>&title-libmysqld-overview;</title>
-
-        <para>
-          The embedded MySQL server library makes it possible to run a
-          full-featured MySQL server inside a client application. The
-          main benefits are increased speed and more simple management
-          for embedded applications.
-        </para>
-
-        <para>
-          The embedded server library is based on the client/server
-          version of MySQL, which is written in C/C++. Consequently, the
-          embedded server also is written in C/C++. There is no embedded
-          server available in other languages.
-        </para>
-
-        <para>
-          The API is identical for the embedded MySQL version and the
-          client/server version. To change an old threaded application
-          to use the embedded library, you normally only have to add
-          calls to the following functions:
-        </para>
-
-        <informaltable>
-          <tgroup cols="2">
-            <colspec colwidth="25*"/>
-            <colspec colwidth="70*"/>
-            <tbody>
-              <row>
-                <entry><emphasis role="bold">Function</emphasis></entry>
-                <entry><emphasis role="bold">When to Call</emphasis></entry>
-              </row>
-              <row>
-                <entry><literal>mysql_server_init()</literal></entry>
-                <entry>Should be called before any other MySQL function is called, preferably
-                  early in the <literal>main()</literal> function.</entry>
-              </row>
-              <row>
-                <entry><literal>mysql_server_end()</literal></entry>
-                <entry>Should be called before your program exits.</entry>
-              </row>
-              <row>
-                <entry><literal>mysql_thread_init()</literal></entry>
-                <entry>Should be called in each thread you create that accesses MySQL.</entry>
-              </row>
-              <row>
-                <entry><literal>mysql_thread_end()</literal></entry>
-                <entry>Should be called before calling <literal>pthread_exit()</literal></entry>
-              </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-
-        <para>
-          Then you must link your code with
-          <filename>libmysqld.a</filename> instead of
-          <filename>libmysqlclient.a</filename>.
-        </para>
-
-        <para>
-          The
-          <literal>mysql_server_<replaceable>xxx</replaceable>()</literal>
-          functions are also included in
-          <filename>libmysqlclient.a</filename> to allow you to change
-          between the embedded and the client/server version by just
-          linking your application with the right library. See
-          <xref linkend="mysql-server-init"/>.
-        </para>
-
-        <para>
-          One difference between the embedded server and the standalone
-          server is that for the embedded server, authentication for
-          connections is disabled by default. To use authentication for
-          the embedded server, specify the
-          <option>--with-embedded-privilege-control</option> option when
-          you invoke <command>configure</command> to configure your
-          MySQL distribution. This option is available as of MySQL
-          4.1.3.
-        </para>
-
-      </section>
-
-      <section id="libmysqld-compiling">
-
-        <title id='title-libmysqld-compiling'>&title-libmysqld-compiling;</title>
-
-        <para>
-          To get a <literal>libmysqld</literal> library you should
-          configure MySQL with the
-          <option>--with-embedded-server</option> option. See
-          <xref linkend="configure-options"/>.
-        </para>
-
-        <para>
-          When you link your program with <literal>libmysqld</literal>,
-          you must also include the system-specific
-          <literal>pthread</literal> libraries and some libraries that
-          the MySQL server uses. You can get the full list of libraries
-          by executing <command>mysql_config --libmysqld-libs</command>.
-        </para>
-
-        <para>
-          The correct flags for compiling and linking a threaded program
-          must be used, even if you do not directly call any thread
-          functions in your code.
-        </para>
-
-        <para>
-          To compile a C program to include the necessary files to embed
-          the MySQL server library into a compiled version of a program,
-          use the GNU C compiler (<literal>gcc</literal>). The compiler
-          will need to know where to find various files and need
-          instructions on how to compile the program. Below is an
-          example of how a program could be compiled from the
-          command-line:
-
-<programlisting>
-gcc mysql_test.c -o mysql_test -lz \
-`/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
-</programlisting>
-        </para>
-
-        <para>
-          Immediately following the <literal>gcc</literal> command is
-          the name of the uncompiled C program file. After it, the
-          <option>-o</option> option is given to indicate that the file
-          name that follows is the name that the compiler is to give to
-          the output file, the compiled program. The next line of code
-          tells the compiler to obtain the location of the include files
-          and libraries and other settings for the system on which it's
-          compiled. Because of a problem with
-          <command>mysql_config</command>, the option
-          <option>-lz</option> (for compression) is added here. The
-          <command>mysql_config</command> piece is contained in
-          backticks, not single quotes.
-        </para>
-
-      </section>
-
-      <section id="libmysqld-restrictions">
-
-        <title id='title-libmysqld-restrictions'>&title-libmysqld-restrictions;</title>
-
-        <para>
-          The embedded server has the following limitations:
-        </para>
-
-        <itemizedlist>
-
-          <listitem>
-            <para>
-              No support for <literal>ISAM</literal> tables. (This is
-              mainly done to make the library smaller)
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              No user-defined functions (UDFs).
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              No stack trace on core dump.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              No internal RAID support. (This is not normally needed as
-              most current operating systems support big files).
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              You cannot set this up as a master or a slave (no
-              replication).
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              Very large result sets may be unusable on low memory
-              systems.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              You cannot connect to an embedded server from an outside
-              process with sockets or TCP/IP. However, you can connect
-              to an intermediate application, which in turn can connect
-              to an embedded server on the behalf of a remote client or
-              outside process.
-            </para>
-          </listitem>
-
-        </itemizedlist>
-
-        <para>
-          Some of these limitations can be changed by editing the
-          <filename>mysql_embed.h</filename> include file and
-          recompiling MySQL.
-        </para>
-
-      </section>
-
-      <section id="libmysqld-options">
-
-        <title id='title-libmysqld-options'>&title-libmysqld-options;</title>
-
-        <indexterm type="concept">
-          <primary>defaults</primary>
-          <secondary>embedded</secondary>
-        </indexterm>
-
-        <indexterm type="concept">
-          <primary>options</primary>
-          <secondary>embedded server</secondary>
-        </indexterm>
-
-        <indexterm type="concept">
-          <primary>options</primary>
-          <secondary>libmysqld</secondary>
-        </indexterm>
-
-        <indexterm type="concept">
-          <primary>libmysqld</primary>
-          <secondary>options</secondary>
-        </indexterm>
-
-        <para>
-          Any options that may be given with the
-          <command>mysqld</command> server daemon, may be used with an
-          embedded server library. Server options may be given in an
-          array as an argument to the
-          <literal>mysql_server_init()</literal>, which initializes the
-          server. They also may be given in an option file like
-          <filename>my.cnf</filename>. To specify an option file for a C
-          program, use the <option>--defaults-file</option> option as
-          one of the elements of the second argument of the
-          <literal>mysql_server_init()</literal> function. See
-          <xref linkend="mysql-server-init"/> for more information on
-          the <literal>mysql_server_init()</literal> function.
-        </para>
-
-        <para>
-          Using option files can make it easier to switch between a
-          client/server application and one where MySQL is embedded. Put
-          common options under the <literal>[server]</literal> group.
-          These are read by both MySQL versions. Client/server-specific
-          options should go under the <literal>[mysqld]</literal>
-          section. Put options specific to the embedded MySQL server
-          library in the <literal>[embedded]</literal> section. Options
-          specific to applications go under section labeled
-          <literal>[ApplicationName_SERVER]</literal>. See
-          <xref linkend="option-files"/>.
-        </para>
-
-      </section>
-
-      <section id="libmysqld-todo">
-
-        <title id='title-libmysqld-todo'>&title-libmysqld-todo;</title>
-
-        <indexterm type="concept">
-          <primary>TODO</primary>
-          <secondary>embedded server</secondary>
-        </indexterm>
-
-        <itemizedlist>
-
-          <listitem>
-            <para>
-              We are going to provide options to leave out some parts of
-              MySQL to make the library smaller.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              There is still a lot of speed optimization to do.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              Errors are written to <literal>stderr</literal>. We will
-              add an option to specify a filename for these.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              We have to change InnoDB not to be so verbose when using
-              the embedded version. If your database does not contain
-              InnoDB tables, to suppress related messages you can add
-              the <option>--skip-innodb</option> option to the options
-              file under the group <literal>[libmysqd_server]</literal>,
-              or when initializing the server with
-              <command>mysql_server_init()</command>.
-            </para>
-          </listitem>
-
-        </itemizedlist>
-
-      </section>
-
-      <section id="libmysqld-example">
-
-        <title id='title-libmysqld-example'>&title-libmysqld-example;</title>
-
-        <para>
-          These two example programs should work without any changes on
-          a Linux or FreeBSD system. For other operating systems, minor
-          changes are needed, mostly with file paths. These examples are
-          designed to give enough details for you to understand the
-          problem, without the clutter that is a necessary part of a
-          real application. The first example is very straightforward.
-          The second example is a little more advanced with some error
-          checking. The first is followed by a command-line entry for
-          compiling the program. The second is followed by a GNUmake
-          file that may be used for compiling instead.
-        </para>
-
-        <para>
-          <emphasis role="bold">Example 1</emphasis>
-        </para>
-
-        <para>
-          <filename>test1_libmysqld.c</filename>
-        </para>
-
-        <para>
-<programlisting>
-#include &lt;stdio.h&gt;
-#include &lt;stdlib.h&gt;
-#include &lt;stdarg.h&gt;
-#include "mysql.h"
-
-MYSQL *mysql;
-MYSQL_RES *results;
-MYSQL_ROW record;
-
-static char *server_options[] = { "mysql_test", "--defaults-file=my.cnf" };
-int num_elements = sizeof(server_options)/ sizeof(char *);
-
-static char *server_groups[] = { "libmysqld_server", "libmysqld_client" };
-
-int main(void)
-{
-   mysql_server_init(num_elements, server_options, server_groups);
-   mysql = mysql_init(NULL);
-   mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, "libmysqld_client");
-   mysql_options(mysql, MYSQL_OPT_USE_EMBEDDED_CONNECTION, NULL);
-
-   mysql_real_connect(mysql, NULL,NULL,NULL, "database1", 0,NULL,0);
-
-   mysql_query(mysql, "SELECT column1, column2 FROM table1");
-
-   results = mysql_store_result(mysql);
-
-   while((record = mysql_fetch_row(results))) {
-      printf("%s - %s \n", record[0], record[1]);
-   }
-
-   mysql_free_result(results);
-   mysql_close(mysql);
-   mysql_server_end();
-
-   return 0;
-}
-</programlisting>
-        </para>
-
-        <para>
-          Here is the command line for compiling the above program:
-        </para>
-
-<programlisting>
-gcc test1_libmysqld.c -o test1_libmysqld -lz \
- `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
-</programlisting>
-
-        <para>
-          <emphasis role="bold">Example 2</emphasis>
-        </para>
-
-        <para>
-          To try out the example, create an
-          <filename>test2_libmysqld</filename> directory at the same
-          level as the mysql-4.0 source directory. Save the
-          <filename>test2_libmysqld.c</filename> source and the
-          <filename>GNUmakefile</filename> in the directory, and run GNU
-          <filename>make</filename> from inside the
-          <filename>test2_libmysqld</filename> directory.
-        </para>
-
-        <para>
-          <filename>test2_libmysqld.c</filename>
-        </para>
-
-        <para>
-<programlisting>
-/*
- * A simple example client, using the embedded MySQL server library
-*/
-
-#include &lt;mysql.h&gt;
-#include &lt;stdarg.h&gt;
-#include &lt;stdio.h&gt;
-#include &lt;stdlib.h&gt;
-
-MYSQL *db_connect(const char *dbname);
-void db_disconnect(MYSQL *db);
-void db_do_query(MYSQL *db, const char *query);
-
-const char *server_groups[] = {
-  "test2_libmysqld_SERVER", "embedded", "server", NULL
-};
-
-int
-main(int argc, char **argv)
-{
-  MYSQL *one, *two;
-
-  /* mysql_server_init() must be called before any other mysql
-   * functions.
-   *
-   * You can use mysql_server_init(0, NULL, NULL), and it
-   * initializes the server using groups = {
-   *   "server", "embedded", NULL
-   *  }.
-   *
-   * In your $HOME/.my.cnf file, you probably want to put:
-
-[test2_libmysqld_SERVER]
-language = /path/to/source/of/mysql/sql/share/english
-
-   * You could, of course, modify argc and argv before passing
-   * them to this function.  Or you could create new ones in any
-   * way you like.  But all of the arguments in argv (except for
-   * argv[0], which is the program name) should be valid options
-   * for the MySQL server.
-   *
-   * If you link this client against the normal mysqlclient
-   * library, this function is just a stub that does nothing.
-   */
-  mysql_server_init(argc, argv, (char **)server_groups);
-
-  one = db_connect("test");
-  two = db_connect(NULL);
-
-  db_do_query(one, "SHOW TABLE STATUS");
-  db_do_query(two, "SHOW DATABASES");
-
-  mysql_close(two);
-  mysql_close(one);
-
-  /* This must be called after all other mysql functions */
-  mysql_server_end();
-
-  exit(EXIT_SUCCESS);
-}
-
-static void
-die(MYSQL *db, char *fmt, ...)
-{
-  va_list ap;
-  va_start(ap, fmt);
-  vfprintf(stderr, fmt, ap);
-  va_end(ap);
-  (void)putc('\n', stderr);
-  if (db)
-    db_disconnect(db);
-  exit(EXIT_FAILURE);
-}
-
-MYSQL *
-db_connect(const char *dbname)
-{
-  MYSQL *db = mysql_init(NULL);
-  if (!db)
-    die(db, "mysql_init failed: no memory");
-  /*
-   * Notice that the client and server use separate group names.
-   * This is critical, because the server does not accept the
-   * client's options, and vice versa.
-   */
-  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test2_libmysqld_CLIENT");
-  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
-    die(db, "mysql_real_connect failed: %s", mysql_error(db));
-
-  return db;
-}
-
-void
-db_disconnect(MYSQL *db)
-{
-  mysql_close(db);
-}
-
-void
-db_do_query(MYSQL *db, const char *query)
-{
-  if (mysql_query(db, query) != 0)
-    goto err;
-
-  if (mysql_field_count(db) &gt; 0)
-  {
-    MYSQL_RES   *res;
-    MYSQL_ROW    row, end_row;
-    int num_fields;
-
-    if (!(res = mysql_store_result(db)))
-      goto err;
-    num_fields = mysql_num_fields(res);
-    while ((row = mysql_fetch_row(res)))
-    {
-      (void)fputs("&gt;&gt; ", stdout);
-      for (end_row = row + num_fields; row &lt; end_row; ++row)
-        (void)printf("%s\t", row ? (char*)*row : "NULL");
-      (void)fputc('\n', stdout);
-    }
-    (void)fputc('\n', stdout);
-    mysql_free_result(res);
-  }
-  else
-    (void)printf("Affected rows: %lld\n", mysql_affected_rows(db));
-
-  return;
-
-err:
-  die(db, "db_do_query failed: %s [%s]", mysql_error(db), query);
-}
-</programlisting>
-        </para>
-
-        <para>
-          <filename>GNUmakefile</filename>
-
-<programlisting>
-# This assumes the MySQL software is installed in /usr/local/mysql
-inc      := /usr/local/mysql/include/mysql
-lib      := /usr/local/mysql/lib
-
-# If you have not installed the MySQL software yet, try this instead
-#inc      := $(HOME)/mysql-4.0/include
-#lib      := $(HOME)/mysql-4.0/libmysqld
-
-CC       := gcc
-CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
-CFLAGS   := -g -W -Wall
-LDFLAGS  := -static
-# You can change -lmysqld to -lmysqlclient to use the
-# client/server library
-LDLIBS    = -L$(lib) -lmysqld -lz -lm -lcrypt
-
-ifneq (,$(shell grep FreeBSD /COPYRIGHT 2&gt;/dev/null))
-# FreeBSD
-LDFLAGS += -pthread
-else
-# Assume Linux
-LDLIBS += -lpthread
-endif
-
-# This works for simple one-file test programs
-sources := $(wildcard *.c)
-objects := $(patsubst %c,%o,$(sources))
-targets := $(basename $(sources))
-
-all: $(targets)
-
-clean:
-        rm -f $(targets) $(objects) *.core
-</programlisting>
-        </para>
-
-      </section>
-
-      <section id="libmysqld-licensing">
-
-        <title id='title-libmysqld-licensing'>&title-libmysqld-licensing;</title>
-
-        <para>
-          We encourage everyone to promote free software by releasing
-          code under the GPL or a compatible license. For those who are
-          not able to do this, another option is to purchase a
-          commercial license for the MySQL code from MySQL AB. For
-          details, please see
-          <ulink url="http://www.mysql.com/company/legal/licensing/"/>.
-        </para>
-
-      </section>
 
     </section>
 

--- 1.9/refman-5.0/mysql-apis.xml	2005-08-11 20:15:20 +02:00
+++ 1.10/refman-5.0/mysql-apis.xml	2005-08-11 21:16:09 +02:00
@@ -49,6 +49,619 @@
     basis for most of the other APIs.
   </para>
 
+    <section id="libmysqld">
+
+      <title id='title-libmysqld'>&title-libmysqld;</title>
+
+      <indexterm type="concept">
+        <primary>libmysqld</primary>
+      </indexterm>
+
+      <indexterm type="concept">
+        <primary>embedded MySQL server library</primary>
+      </indexterm>
+
+      <section id="libmysqld-overview">
+
+        <title id='title-libmysqld-overview'>&title-libmysqld-overview;</title>
+
+        <para>
+          The embedded MySQL server library makes it possible to run a
+          full-featured MySQL server inside a client application. The
+          main benefits are increased speed and more simple management
+          for embedded applications.
+        </para>
+
+        <para>
+          The embedded server library is based on the client/server
+          version of MySQL, which is written in C/C++. Consequently, the
+          embedded server also is written in C/C++. There is no embedded
+          server available in other languages.
+        </para>
+
+        <para>
+          The API is identical for the embedded MySQL version and the
+          client/server version. To change an old threaded application
+          to use the embedded library, you normally only have to add
+          calls to the following functions:
+        </para>
+
+        <informaltable>
+          <tgroup cols="2">
+            <colspec colwidth="25*"/>
+            <colspec colwidth="70*"/>
+            <tbody>
+              <row>
+                <entry><emphasis role="bold">Function</emphasis></entry>
+                <entry><emphasis role="bold">When to Call</emphasis></entry>
+              </row>
+              <row>
+                <entry><literal>mysql_server_init()</literal></entry>
+                <entry>Should be called before any other MySQL function is called, preferably
+                  early in the <literal>main()</literal> function.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_server_end()</literal></entry>
+                <entry>Should be called before your program exits.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_thread_init()</literal></entry>
+                <entry>Should be called in each thread you create that accesses MySQL.</entry>
+              </row>
+              <row>
+                <entry><literal>mysql_thread_end()</literal></entry>
+                <entry>Should be called before calling <literal>pthread_exit()</literal></entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+
+        <para>
+          Then you must link your code with
+          <filename>libmysqld.a</filename> instead of
+          <filename>libmysqlclient.a</filename>.
+        </para>
+
+        <para>
+          The
+          <literal>mysql_server_<replaceable>xxx</replaceable>()</literal>
+          functions are also included in
+          <filename>libmysqlclient.a</filename> to allow you to change
+          between the embedded and the client/server version by just
+          linking your application with the right library. See
+          <xref linkend="mysql-server-init"/>.
+        </para>
+
+        <para>
+          One difference between the embedded server and the standalone
+          server is that for the embedded server, authentication for
+          connections is disabled by default. To use authentication for
+          the embedded server, specify the
+          <option>--with-embedded-privilege-control</option> option when
+          you invoke <command>configure</command> to configure your
+          MySQL distribution. This option is available as of MySQL
+          4.1.3.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-compiling">
+
+        <title id='title-libmysqld-compiling'>&title-libmysqld-compiling;</title>
+
+        <para>
+          To get a <literal>libmysqld</literal> library you should
+          configure MySQL with the
+          <option>--with-embedded-server</option> option. See
+          <xref linkend="configure-options"/>.
+        </para>
+
+        <para>
+          When you link your program with <literal>libmysqld</literal>,
+          you must also include the system-specific
+          <literal>pthread</literal> libraries and some libraries that
+          the MySQL server uses. You can get the full list of libraries
+          by executing <command>mysql_config --libmysqld-libs</command>.
+        </para>
+
+        <para>
+          The correct flags for compiling and linking a threaded program
+          must be used, even if you do not directly call any thread
+          functions in your code.
+        </para>
+
+        <para>
+          To compile a C program to include the necessary files to embed
+          the MySQL server library into a compiled version of a program,
+          use the GNU C compiler (<literal>gcc</literal>). The compiler
+          will need to know where to find various files and need
+          instructions on how to compile the program. Below is an
+          example of how a program could be compiled from the
+          command-line:
+
+<programlisting>
+gcc mysql_test.c -o mysql_test -lz \
+`/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
+</programlisting>
+        </para>
+
+        <para>
+          Immediately following the <literal>gcc</literal> command is
+          the name of the uncompiled C program file. After it, the
+          <option>-o</option> option is given to indicate that the file
+          name that follows is the name that the compiler is to give to
+          the output file, the compiled program. The next line of code
+          tells the compiler to obtain the location of the include files
+          and libraries and other settings for the system on which it's
+          compiled. Because of a problem with
+          <command>mysql_config</command>, the option
+          <option>-lz</option> (for compression) is added here. The
+          <command>mysql_config</command> piece is contained in
+          backticks, not single quotes.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-restrictions">
+
+        <title id='title-libmysqld-restrictions'>&title-libmysqld-restrictions;</title>
+
+        <para>
+          The embedded server has the following limitations:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              No support for <literal>ISAM</literal> tables. (This is
+              mainly done to make the library smaller)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No user-defined functions (UDFs).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No stack trace on core dump.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No internal RAID support. (This is not normally needed as
+              most current operating systems support big files).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You cannot set this up as a master or a slave (no
+              replication).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Very large result sets may be unusable on low memory
+              systems.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You cannot connect to an embedded server from an outside
+              process with sockets or TCP/IP. However, you can connect
+              to an intermediate application, which in turn can connect
+              to an embedded server on the behalf of a remote client or
+              outside process.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          Some of these limitations can be changed by editing the
+          <filename>mysql_embed.h</filename> include file and
+          recompiling MySQL.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-options">
+
+        <title id='title-libmysqld-options'>&title-libmysqld-options;</title>
+
+        <indexterm type="concept">
+          <primary>defaults</primary>
+          <secondary>embedded</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>options</primary>
+          <secondary>embedded server</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>options</primary>
+          <secondary>libmysqld</secondary>
+        </indexterm>
+
+        <indexterm type="concept">
+          <primary>libmysqld</primary>
+          <secondary>options</secondary>
+        </indexterm>
+
+        <para>
+          Any options that may be given with the
+          <command>mysqld</command> server daemon, may be used with an
+          embedded server library. Server options may be given in an
+          array as an argument to the
+          <literal>mysql_server_init()</literal>, which initializes the
+          server. They also may be given in an option file like
+          <filename>my.cnf</filename>. To specify an option file for a C
+          program, use the <option>--defaults-file</option> option as
+          one of the elements of the second argument of the
+          <literal>mysql_server_init()</literal> function. See
+          <xref linkend="mysql-server-init"/> for more information on
+          the <literal>mysql_server_init()</literal> function.
+        </para>
+
+        <para>
+          Using option files can make it easier to switch between a
+          client/server application and one where MySQL is embedded. Put
+          common options under the <literal>[server]</literal> group.
+          These are read by both MySQL versions. Client/server-specific
+          options should go under the <literal>[mysqld]</literal>
+          section. Put options specific to the embedded MySQL server
+          library in the <literal>[embedded]</literal> section. Options
+          specific to applications go under section labeled
+          <literal>[ApplicationName_SERVER]</literal>. See
+          <xref linkend="option-files"/>.
+        </para>
+
+      </section>
+
+      <section id="libmysqld-todo">
+
+        <title id='title-libmysqld-todo'>&title-libmysqld-todo;</title>
+
+        <indexterm type="concept">
+          <primary>TODO</primary>
+          <secondary>embedded server</secondary>
+        </indexterm>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              We are going to provide options to leave out some parts of
+              MySQL to make the library smaller.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              There is still a lot of speed optimization to do.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Errors are written to <literal>stderr</literal>. We will
+              add an option to specify a filename for these.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              We have to change InnoDB not to be so verbose when using
+              the embedded version. If your database does not contain
+              InnoDB tables, to suppress related messages you can add
+              the <option>--skip-innodb</option> option to the options
+              file under the group <literal>[libmysqd_server]</literal>,
+              or when initializing the server with
+              <command>mysql_server_init()</command>.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+      </section>
+
+      <section id="libmysqld-example">
+
+        <title id='title-libmysqld-example'>&title-libmysqld-example;</title>
+
+        <para>
+          These two example programs should work without any changes on
+          a Linux or FreeBSD system. For other operating systems, minor
+          changes are needed, mostly with file paths. These examples are
+          designed to give enough details for you to understand the
+          problem, without the clutter that is a necessary part of a
+          real application. The first example is very straightforward.
+          The second example is a little more advanced with some error
+          checking. The first is followed by a command-line entry for
+          compiling the program. The second is followed by a GNUmake
+          file that may be used for compiling instead.
+        </para>
+
+        <para>
+          <emphasis role="bold">Example 1</emphasis>
+        </para>
+
+        <para>
+          <filename>test1_libmysqld.c</filename>
+        </para>
+
+        <para>
+<programlisting>
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+#include &lt;stdarg.h&gt;
+#include "mysql.h"
+
+MYSQL *mysql;
+MYSQL_RES *results;
+MYSQL_ROW record;
+
+static char *server_options[] = { "mysql_test", "--defaults-file=my.cnf" };
+int num_elements = sizeof(server_options)/ sizeof(char *);
+
+static char *server_groups[] = { "libmysqld_server", "libmysqld_client" };
+
+int main(void)
+{
+   mysql_server_init(num_elements, server_options, server_groups);
+   mysql = mysql_init(NULL);
+   mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, "libmysqld_client");
+   mysql_options(mysql, MYSQL_OPT_USE_EMBEDDED_CONNECTION, NULL);
+
+   mysql_real_connect(mysql, NULL,NULL,NULL, "database1", 0,NULL,0);
+
+   mysql_query(mysql, "SELECT column1, column2 FROM table1");
+
+   results = mysql_store_result(mysql);
+
+   while((record = mysql_fetch_row(results))) {
+      printf("%s - %s \n", record[0], record[1]);
+   }
+
+   mysql_free_result(results);
+   mysql_close(mysql);
+   mysql_server_end();
+
+   return 0;
+}
+</programlisting>
+        </para>
+
+        <para>
+          Here is the command line for compiling the above program:
+        </para>
+
+<programlisting>
+gcc test1_libmysqld.c -o test1_libmysqld -lz \
+ `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
+</programlisting>
+
+        <para>
+          <emphasis role="bold">Example 2</emphasis>
+        </para>
+
+        <para>
+          To try out the example, create an
+          <filename>test2_libmysqld</filename> directory at the same
+          level as the mysql-4.0 source directory. Save the
+          <filename>test2_libmysqld.c</filename> source and the
+          <filename>GNUmakefile</filename> in the directory, and run GNU
+          <filename>make</filename> from inside the
+          <filename>test2_libmysqld</filename> directory.
+        </para>
+
+        <para>
+          <filename>test2_libmysqld.c</filename>
+        </para>
+
+        <para>
+<programlisting>
+/*
+ * A simple example client, using the embedded MySQL server library
+*/
+
+#include &lt;mysql.h&gt;
+#include &lt;stdarg.h&gt;
+#include &lt;stdio.h&gt;
+#include &lt;stdlib.h&gt;
+
+MYSQL *db_connect(const char *dbname);
+void db_disconnect(MYSQL *db);
+void db_do_query(MYSQL *db, const char *query);
+
+const char *server_groups[] = {
+  "test2_libmysqld_SERVER", "embedded", "server", NULL
+};
+
+int
+main(int argc, char **argv)
+{
+  MYSQL *one, *two;
+
+  /* mysql_server_init() must be called before any other mysql
+   * functions.
+   *
+   * You can use mysql_server_init(0, NULL, NULL), and it
+   * initializes the server using groups = {
+   *   "server", "embedded", NULL
+   *  }.
+   *
+   * In your $HOME/.my.cnf file, you probably want to put:
+
+[test2_libmysqld_SERVER]
+language = /path/to/source/of/mysql/sql/share/english
+
+   * You could, of course, modify argc and argv before passing
+   * them to this function.  Or you could create new ones in any
+   * way you like.  But all of the arguments in argv (except for
+   * argv[0], which is the program name) should be valid options
+   * for the MySQL server.
+   *
+   * If you link this client against the normal mysqlclient
+   * library, this function is just a stub that does nothing.
+   */
+  mysql_server_init(argc, argv, (char **)server_groups);
+
+  one = db_connect("test");
+  two = db_connect(NULL);
+
+  db_do_query(one, "SHOW TABLE STATUS");
+  db_do_query(two, "SHOW DATABASES");
+
+  mysql_close(two);
+  mysql_close(one);
+
+  /* This must be called after all other mysql functions */
+  mysql_server_end();
+
+  exit(EXIT_SUCCESS);
+}
+
+static void
+die(MYSQL *db, char *fmt, ...)
+{
+  va_list ap;
+  va_start(ap, fmt);
+  vfprintf(stderr, fmt, ap);
+  va_end(ap);
+  (void)putc('\n', stderr);
+  if (db)
+    db_disconnect(db);
+  exit(EXIT_FAILURE);
+}
+
+MYSQL *
+db_connect(const char *dbname)
+{
+  MYSQL *db = mysql_init(NULL);
+  if (!db)
+    die(db, "mysql_init failed: no memory");
+  /*
+   * Notice that the client and server use separate group names.
+   * This is critical, because the server does not accept the
+   * client's options, and vice versa.
+   */
+  mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "test2_libmysqld_CLIENT");
+  if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
+    die(db, "mysql_real_connect failed: %s", mysql_error(db));
+
+  return db;
+}
+
+void
+db_disconnect(MYSQL *db)
+{
+  mysql_close(db);
+}
+
+void
+db_do_query(MYSQL *db, const char *query)
+{
+  if (mysql_query(db, query) != 0)
+    goto err;
+
+  if (mysql_field_count(db) &gt; 0)
+  {
+    MYSQL_RES   *res;
+    MYSQL_ROW    row, end_row;
+    int num_fields;
+
+    if (!(res = mysql_store_result(db)))
+      goto err;
+    num_fields = mysql_num_fields(res);
+    while ((row = mysql_fetch_row(res)))
+    {
+      (void)fputs("&gt;&gt; ", stdout);
+      for (end_row = row + num_fields; row &lt; end_row; ++row)
+        (void)printf("%s\t", row ? (char*)*row : "NULL");
+      (void)fputc('\n', stdout);
+    }
+    (void)fputc('\n', stdout);
+    mysql_free_result(res);
+  }
+  else
+    (void)printf("Affected rows: %lld\n", mysql_affected_rows(db));
+
+  return;
+
+err:
+  die(db, "db_do_query failed: %s [%s]", mysql_error(db), query);
+}
+</programlisting>
+        </para>
+
+        <para>
+          <filename>GNUmakefile</filename>
+
+<programlisting>
+# This assumes the MySQL software is installed in /usr/local/mysql
+inc      := /usr/local/mysql/include/mysql
+lib      := /usr/local/mysql/lib
+
+# If you have not installed the MySQL software yet, try this instead
+#inc      := $(HOME)/mysql-4.0/include
+#lib      := $(HOME)/mysql-4.0/libmysqld
+
+CC       := gcc
+CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
+CFLAGS   := -g -W -Wall
+LDFLAGS  := -static
+# You can change -lmysqld to -lmysqlclient to use the
+# client/server library
+LDLIBS    = -L$(lib) -lmysqld -lz -lm -lcrypt
+
+ifneq (,$(shell grep FreeBSD /COPYRIGHT 2&gt;/dev/null))
+# FreeBSD
+LDFLAGS += -pthread
+else
+# Assume Linux
+LDLIBS += -lpthread
+endif
+
+# This works for simple one-file test programs
+sources := $(wildcard *.c)
+objects := $(patsubst %c,%o,$(sources))
+targets := $(basename $(sources))
+
+all: $(targets)
+
+clean:
+        rm -f $(targets) $(objects) *.core
+</programlisting>
+        </para>
+
+      </section>
+
+      <section id="libmysqld-licensing">
+
+        <title id='title-libmysqld-licensing'>&title-libmysqld-licensing;</title>
+
+        <para>
+          We encourage everyone to promote free software by releasing
+          code under the GPL or a compatible license. For those who are
+          not able to do this, another option is to purchase a
+          commercial license for the MySQL code from MySQL AB. For
+          details, please see
+          <ulink url="http://www.mysql.com/company/legal/licensing/"/>.
+        </para>
+
+      </section>
+
+    </section>
+
   <section id="programming-utilities">
 
     <title id='title-programming-utilities'>&title-programming-utilities;</title>