Author: shinz
Date: 2006-07-21 18:22:38 +0200 (Fri, 21 Jul 2006)
New Revision: 2797
Log:
Remove most of the libmysqld section because MySQL doesn't (and won't ever) include the Embedded Server (Bug #20810)
Modified:
trunk/refman-5.0/apis.xml
trunk/refman-5.0/renamed-nodes.txt
Modified: trunk/refman-5.0/apis.xml
===================================================================
--- trunk/refman-5.0/apis.xml 2006-07-21 11:25:27 UTC (rev 2796)
+++ trunk/refman-5.0/apis.xml 2006-07-21 16:22:38 UTC (rev 2797)
Changed blocks: 4, Lines Added: 84, Lines Deleted: 590; 23202 bytes
@@ -48,9 +48,8 @@
This chapter describes the APIs available for MySQL, where to get
them, and how to use them. The C API is the most extensively
covered, because it was developed by the MySQL team, and is the
- basis for most of the other APIs. This chapter also covers the
- <literal>libmysqld</literal> library (the embedded server), as well
- as some programs that are useful for application developers.
+ basis for most of the other APIs. This chapter also covers some
+ programs that are useful for application developers.
</para>
<section id="libmysqld">
@@ -65,599 +64,91 @@
<primary>embedded MySQL server library</primary>
</indexterm>
- <section id="libmysqld-overview">
+ <para>
+ <emphasis role="bold"> The embedded MySQL server library is NOT
+ part of MySQL 5.0. It is part of previous editions and will be
+ included in future versions, starting with MySQL 5.1. You can find
+ appropriate documentation in the corresponding manuals for these
+ versions. In this manual, only an overview of the embedded library
+ is provided. </emphasis>
+ </para>
- <title>Overview of the Embedded MySQL Server Library</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 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 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>
- <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>
- <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>
- 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>
- 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.
+ </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.
- </para>
-
- </section>
-
- <section id="libmysqld-compiling">
-
- <title>Compiling Programs with <literal>libmysqld</literal></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. The following
- example shows how a program could be compiled from the command
- line:
- </para>
-
-<programlisting>
-gcc mysql_test.c -o mysql_test -lz \
-`/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
-</programlisting>
-
- <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>Restrictions When Using the Embedded MySQL Server</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>Options with the Embedded Server</title>
-
- <indexterm>
- <primary>defaults</primary>
- <secondary>embedded</secondary>
- </indexterm>
-
- <indexterm>
- <primary>options</primary>
- <secondary>embedded server</secondary>
- </indexterm>
-
- <indexterm>
- <primary>options</primary>
- <secondary>libmysqld</secondary>
- </indexterm>
-
- <indexterm>
- <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>Things Left to Do in Embedded Server (TODO)</title>
-
- <indexterm>
- <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 <literal>InnoDB</literal> not to be so
- verbose when using the embedded version. If your database
- does not contain <literal>InnoDB</literal> 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>Embedded Server Examples</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>
-
-<programlisting>
-#include <stdio.h>
-#include <stdlib.h>
-#include <stdarg.h>
-#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>
- 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 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>
-
-<programlisting>
-/*
- * A simple example client, using the embedded MySQL server library
-*/
-
-#include <mysql.h>
-#include <stdarg.h>
-#include <stdio.h>
-#include <stdlib.h>
-
-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) > 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(">> ", stdout);
- for (end_row = row + num_fields; row < 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>
- <filename>GNUmakefile</filename>
- </para>
-
-<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-¤t-series;/include
-#lib := $(HOME)/mysql-¤t-series;/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>/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>
-
- </section>
-
- <section id="libmysqld-licensing">
-
- <title>Licensing the Embedded Server</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="c">
@@ -12753,7 +12244,9 @@
<section id="null-mysql-store-result">
- <title>Why <literal>mysql_store_result()</literal> Sometimes Returns <literal>NULL</literal> After <literal>mysql_query()</literal> Returns Success</title>
+ <title>Why <literal>mysql_store_result()</literal> Sometimes Returns
+ <literal>NULL</literal> After <literal>mysql_query()</literal>
+ Returns Success</title>
<para>
It is possible for <literal>mysql_store_result()</literal> to
@@ -13438,7 +12931,8 @@
<section id="php-mysql-mysqli">
- <title>Enabling Both <literal>mysql</literal> and <literal>mysqli</literal> in PHP</title>
+ <title>Enabling Both <literal>mysql</literal> and <literal>mysqli</literal> in
+ PHP</title>
<para>
If you're experiencing problems with enabling both the
Modified: trunk/refman-5.0/renamed-nodes.txt
===================================================================
--- trunk/refman-5.0/renamed-nodes.txt 2006-07-21 11:25:27 UTC (rev 2796)
+++ trunk/refman-5.0/renamed-nodes.txt 2006-07-21 16:22:38 UTC (rev 2797)
Changed blocks: 1, Lines Added: 8, Lines Deleted: 0; 851 bytes
@@ -45,6 +45,14 @@
isam myisam-storage-engine
java java-connector
left-join-optimisation left-join-optimization
+# libmysqld isn't part of MySQL 5.0
+libmysqld-overview libmysqld
+libmysqld-compiling ../../5.1/en/libmysqld-compiling
+libmysqld-restrictions ../../5.1/en/libmysqld-restrictions
+libmysqld-options ../../5.1/en/libmysqld-options
+libmysqld-todo ../../5.1/en/libmysqld-todo
+libmysqld-example ../../5.1/en/libmysqld-example
+libmysqld-licensing ../../5.1/en/libmysqld-licensing
limit-optimisation limit-optimization
locking-methods internal-locking
maintenance-regimen maintenance-schedule
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2797 - trunk/refman-5.0 | shinz | 21 Jul |
