List:Commits« Previous MessageNext Message »
From:paul Date:December 7 2005 3:40pm
Subject:svn commit - mysqldoc@docsrva: r513 - in trunk: . refman-5.1 refman-common
View as plain text  
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-commonpaul7 Dec