Author: paul
Date: 2005-12-07 16:40:02 +0100 (Wed, 07 Dec 2005)
New Revision: 513
Log:
r4568@frost: paul | 2005-12-07 09:16:58 -0600
Preliminary plugin stuff.
Modified:
trunk/
trunk/refman-5.1/extending-mysql.xml
trunk/refman-common/titles.en.ent
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:4567
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1505
+ b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:4568
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1505
Modified: trunk/refman-5.1/extending-mysql.xml
===================================================================
--- trunk/refman-5.1/extending-mysql.xml 2005-12-07 15:39:50 UTC (rev 512)
+++ trunk/refman-5.1/extending-mysql.xml 2005-12-07 15:40:02 UTC (rev 513)
@@ -475,6 +475,226 @@
</section>
+ <section id="plugin-api">
+
+ <title id="title-plugin-api">&title-plugin-api;</title>
+
+ <indexterm>
+ <primary>plugin API</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>adding</secondary>
+ </indexterm>
+
+ <remark role="todo">
+ Also to mention: Note the API in the 5.1 upgrading section. Point
+ out that if you're upgrading, you must upgrade the grant tables by
+ running mysql_fix_privilege_tables to make sure the mysql.plugin
+ table exists. Describe the interface functions. Add change note
+ for I.P./U.P. in 5.1.3 changelog.
+ </remark>
+
+ <remark role="help-category" condition="Plugins"/>
+
+ <para>
+ MySQL 5.1 provides a plugin interface that can be used to add new
+ functions to the server. This interface is the successor to the
+ older user-defined function (UDF) interface. It is intended that
+ the UDF interface will be phased out.
+ </para>
+
+ <section id="install-plugin">
+
+ <title id="title-install-plugin">&title-install-plugin;</title>
+
+ <indexterm type="function">
+ <primary><literal>INSTALL PLUGIN</literal></primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>installing plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>installing</secondary>
+ </indexterm>
+
+ <remark role="help-topic" condition="INSTALL PLUGIN"/>
+
+ <remark role="help-keywords">
+ INSTALL PLUGIN
+ </remark>
+
+ <remark role="help-syntax-begin"/>
+
+<programlisting>
+INSTALL PLUGIN <replaceable>plugin_name</replaceable> SONAME '<replaceable>plugin_library</replaceable>'
+</programlisting>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ This statement installs a plugin.
+ </para>
+
+ <para>
+ <replaceable>plugin_name</replaceable> is the name of the plugin
+ as defined in the plugin declaration structure contained in the
+ library file.
+ </para>
+
+ <remark role="todo">
+ Is plugin_name case sensitive? Or is case sensitivity a function
+ of the host system filename semanitics?
+ </remark>
+
+ <para>
+ <replaceable>plugin_library</replaceable> is the name of the
+ shared library that contains the plugin code. The name includes
+ the filename extension (for example,
+ <filename>libmyplugin.so</filename> or
+ <filename>libmyplugin.dylib</filename>).
+ </para>
+
+ <remark role="todo">
+ What is the library name on Windows? libmyplugin.dll?
+ </remark>
+
+ <para>
+ The shared library must be located in the plugin directory (that
+ is, the directory named by the <literal>plugin_dir</literal>
+ system variable). The library must be in the plugin directory
+ itself, not in a subdirectory. By default,
+ <literal>plugin_dir</literal> is the directory named by the
+ <literal>pkglibdir</literal> configuration variable, but it can
+ be changed by setting the value of <literal>plugin_dir</literal>
+ at server startup. For example, set its value in a
+ <filename>my.cnf</filename> file:
+ </para>
+
+<programlisting>
+[mysqld]
+plugin_dir=<replaceable>/path/to/plugin/directory</replaceable>
+</programlisting>
+
+ <para>
+ If the value of <literal>plugin_dir</literal> is a relative
+ pathname, it is taken to be relative to the MySQL base directory
+ (the value of the <literal>basedir</literal> system variable).
+ </para>
+
+ <para>
+ <literal>INSTALL PLUGIN</literal> adds a line to the
+ <literal>mysql.plugin</literal> table that describes the
+ <literal>plugin</literal>. Currently, this table contains only
+ the plugin name and library filename.
+ </para>
+
+ <para>
+ <literal>INSTALL PLUGIN</literal> also loads and initializes the
+ plugin code to make the plugin available for use. A plugin is
+ initialized by executing its initialization function, which
+ handles any setup that the plugin must perform before it can be
+ used.
+ </para>
+
+ <para>
+ To use <literal>INSTALL PLUGIN</literal>, you must have the
+ <literal>INSERT privilege</literal> for the
+ <literal>mysql.plugin</literal> table.
+ </para>
+
+ <para>
+ At server startup, the server loads and initializes any plugin
+ that is listed in the <literal>mysql.plugin</literal> table.
+ This means that a plugin is installed with <literal>INSTALL
+ PLUGIN</literal> only once, not every time the server starts.
+ Plugin loading at startup does not occur if the server is
+ started with the <option>--skip-grant-tables</option> option.
+ </para>
+
+ <para>
+ When the server shuts down, it executes the termination
+ (<literal>deinit()</literal>) function for each plugin that is
+ loaded so that the plugin has a change to perform any final
+ cleanup.
+ </para>
+
+ <para>
+ To remove a plugin entirely, use the <literal>UNINSTALL
+ PLUGIN</literal> statement:
+ </para>
+
+ <remark role="help-description-end"/>
+
+ </section>
+
+ <section id="uninstall-plugin">
+
+ <title id="title-uninstall-plugin">&title-uninstall-plugin;</title>
+
+ <indexterm type="function">
+ <primary><literal>UNINSTALL PLUGIN</literal></primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>uninstalling plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>uninstalling</secondary>
+ </indexterm>
+
+ <remark role="help-topic" condition="UNINSTALL PLUGIN"/>
+
+ <remark role="help-keywords">
+ UNINSTALL PLUGIN
+ </remark>
+
+ <remark role="help-syntax-begin"/>
+
+<programlisting>
+UNINSTALL PLUGIN <replaceable>plugin_name</replaceable>
+</programlisting>
+
+ <remark role="help-syntax-end"/>
+
+ <remark role="help-description-begin"/>
+
+ <para>
+ This statement removes an installed plugin.
+ </para>
+
+ <para>
+ <replaceable>plugin_name</replaceable> must be the name of some
+ plugin that is listed in the
+ <replaceable>mysql.plugin</replaceable> table. The server
+ executes the plugin's termination (<literal>deinit()</literal>)
+ function. It also removes the row for the plugin from the
+ <literal>mysql.plugin</literal> table, so that subsequent server
+ restarts will not load and initialize the plugin.
+ <literal>UNINSTALL PLUGIN</literal> does not remove the plugin's
+ shared library file.
+ </para>
+
+ <para>
+ To use <literal>UNINSTALL PLUGIN</literal>, you must have the
+ <literal>DELETE</literal> privilege for the
+ <literal>mysql.plugin</literal> table.
+ </para>
+
+ <remark role="help-description-end"/>
+
+ </section>
+
+ </section>
+
<section id="adding-functions">
<title id="title-adding-functions">&title-adding-functions;</title>
@@ -504,6 +724,8 @@
<secondary>user-defined</secondary>
</indexterm>
+ <remark role="help-category" condition="Functions"/>
+
<para>
There are two ways to add new functions to MySQL:
</para>
@@ -675,8 +897,6 @@
<secondary>user-defined</secondary>
</indexterm>
- <remark role="help-category" condition="Functions"/>
-
<remark role="help-topic" condition="FUNCTION"/>
<remark role="help-keywords">
Modified: trunk/refman-common/titles.en.ent
===================================================================
--- trunk/refman-common/titles.en.ent 2005-12-07 15:39:50 UTC (rev 512)
+++ trunk/refman-common/titles.en.ent 2005-12-07 15:40:02 UTC (rev 513)
@@ -556,6 +556,7 @@
<!ENTITY title-insert-delayed "<literal>INSERT DELAYED</literal> Syntax">
<!ENTITY title-insert-select "<literal>INSERT ... SELECT</literal> Syntax">
<!ENTITY title-insert-speed "Speed of <literal>INSERT</literal> Statements">
+<!ENTITY title-install-plugin "<literal>INSTALL PLUGIN</literal> Syntax">
<!ENTITY title-installation-issues "Installation-Related Issues">
<!ENTITY title-installation-layouts "Installation Layouts">
<!ENTITY title-installing "Installing MySQL">
@@ -1327,6 +1328,7 @@
<!ENTITY title-pluggable-storage-security "Security Implications of Pluggable Storage">
<!ENTITY title-pluggable-storage-transactions "Storage Engines and Transactions">
<!ENTITY title-pluggable-storage-unplugging "Unplugging a Storage Engine">
+<!ENTITY title-plugin-api "The MySQL Plugin Interface">
<!ENTITY title-point-in-time-recovery "Point-in-Time Recovery">
<!ENTITY title-point-in-time-recovery-positions "Specifying Positions for Recovery">
<!ENTITY title-point-in-time-recovery-times "Specifying Times for Recovery">
@@ -1609,6 +1611,7 @@
<!ENTITY title-udf-features "Features of the User-Defined Function Interface">
<!ENTITY title-udf-return-values "UDF Return Values and Error Handling">
<!ENTITY title-udf-security "User-Defined Function Security Precautions">
+<!ENTITY title-uninstall-plugin "<literal>UNINSTALL PLUGIN</literal> Syntax">
<!ENTITY title-union "<literal>UNION</literal> Syntax">
<!ENTITY title-unix-post-installation "Unix Post-Installation Procedures">
<!ENTITY title-unnamed-views "Subqueries in the <literal>FROM</literal> clause">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r513 - in trunk: . refman-5.1 refman-common | paul | 7 Dec |
