List:Commits« Previous MessageNext Message »
From:paul.dubois Date:June 21 2011 6:02pm
Subject:svn commit - mysqldoc@oter02: r26574 - in trunk: . refman-5.1 refman-5.5 refman-5.6 refman-6.0
View as plain text  
Author: pd221994
Date: 2011-06-21 20:02:15 +0200 (Tue, 21 Jun 2011)
New Revision: 26574

Log:
 r49172@dhcp-adc-twvpn-1-vpnpool-10-154-30-168:  paul | 2011-06-21 12:46:29 -0500
 Replace three scattered sections on plugin loading with a single section
 covering same information in less fragmentary manner.
 
 Old::
 plugin-installing-uninstalling
 registering-plugins
 server-plugin-options
 
 New:
 server-plugin-loading


Modified:
   svk:merge
   trunk/refman-5.1/dba-mysqld-server-core.xml
   trunk/refman-5.1/extending-mysql.xml
   trunk/refman-5.1/sql-syntax-server-administration.xml
   trunk/refman-5.5/dba-mysqld-server-core.xml
   trunk/refman-5.5/extending-mysql.xml
   trunk/refman-5.5/sql-syntax-server-administration.xml
   trunk/refman-5.6/dba-mysqld-server-core.xml
   trunk/refman-5.6/extending-mysql.xml
   trunk/refman-5.6/sql-syntax-server-administration.xml
   trunk/refman-6.0/dba-mysqld-server-core.xml
   trunk/refman-6.0/extending-mysql.xml
   trunk/refman-6.0/sql-syntax-server-administration.xml

Property changes on: trunk
___________________________________________________________________

Modified: svk:merge
===================================================================


Changed blocks: 0, Lines Added: 0, Lines Deleted: 0; 1277 bytes


Modified: trunk/refman-5.1/dba-mysqld-server-core.xml
===================================================================
--- trunk/refman-5.1/dba-mysqld-server-core.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.1/dba-mysqld-server-core.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 6, Lines Added: 292, Lines Deleted: 21; 14837 bytes

@@ -15002,20 +15002,263 @@
       partitioning support, and server extensions.
     </para>
 
-    <section id="server-plugin-options">
+    <section id="server-plugin-loading">
 
-      <title>Server Options for Loading Plugins</title>
+      <title>Installing and Uninstalling Plugins</title>
 
+      <indexterm>
+        <primary>installing plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>installing</secondary>
+      </indexterm>
+
+      <indexterm>
+        <primary>activating plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>activating</secondary>
+      </indexterm>
+
+      <indexterm>
+        <primary>uninstalling plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>uninstalling</secondary>
+      </indexterm>
+
       <para>
-        The server can control plugin activation using startup options
-        named for the plugins. For example, many storage engines can be
-        built in pluggable form and loaded when the server starts. In
-        the following descriptions,
+        Server plugins must be loaded in to the server before they can
+        be used. MySQL enables you to load a plugin at server startup or
+        at runtime. It is also possible to control the activation of
+        loaded plugins at startup, and to unload them at runtime.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-installing">Installing
+            plugins</link>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-activating">Controlling plugin
+            activation</link>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-uninstalling">Uninstalling
+            plugins</link>
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <bridgehead id="server-plugin-installing">
+        Installing Plugins
+      </bridgehead>
+
+      <para>
+        Server plugins must be known to the server before they can be
+        used. A plugin can be made known several ways, as described
+        here. In the following descriptions,
         <replaceable>plugin_name</replaceable> stands for a plugin name
         such as <literal>innodb</literal> or <literal>csv</literal>.
       </para>
 
       <para>
+        <emphasis role="bold">Built-in plugins:</emphasis>
+      </para>
+
+      <para>
+        A plugin that is built in to the server is known by the server
+        automatically. Normally, the server enables the plugin at
+        startup, although this can be changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins registered in the
+        <literal>mysql.plugin</literal> table:</emphasis>
+      </para>
+
+      <para>
+        The <literal>mysql.plugin</literal> table serves as a registry
+        of plugins. The server normally enables each plugin listed in
+        the table at startup, although whether a given plugin is enabled
+        can be changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option. If the server is started with the
+        <option role="mysqld">--skip-grant-tables</option> option, it
+        does not consult this table and does not load the plugins listed
+        there.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins named with the
+        <option role="mysqld">--plugin-load</option> option:</emphasis>
+      </para>
+
+      <para>
+        A plugin that is located in a plugin library file can be loaded
+        at server startup with the
+        <option role="mysqld">--plugin-load</option> option. Normally,
+        the server enables the plugin at startup, although this can be
+        changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option.
+      </para>
+
+      <para>
+        The option value is a semicolon-separated list of
+        <literal><replaceable>name</replaceable>=<replaceable>plugin_library</replaceable></literal>
+        pairs. Each <replaceable>name</replaceable> is the name of the
+        plugin, and <replaceable>plugin_library</replaceable> is the
+        name of the shared library that contains the plugin code. If a
+        plugin library is named without any preceding plugin name, the
+        server loads all plugins in the library. Each library file must
+        be located in the directory named by the
+        <literal role="sysvar">plugin_dir</literal> system variable.
+      </para>
+
+      <para>
+        This option does not register any plugin in the
+        <literal>mysql.plugin</literal> table. For subsequent restarts,
+        the server loads the plugin again only if
+        <option role="mysqld">--plugin-load</option> is given again.
+        That is, this option effects a one-time installation that
+        persists only for one server invocation.
+      </para>
+
+      <para>
+        <option role="mysqld">--plugin-load</option> enables plugins to
+        be loaded even when
+        <option role="mysqld">--skip-grant-tables</option> is given
+        (which causes the server to ignore the
+        <literal>mysql.plugin</literal> table).
+        <option role="mysqld">--plugin-load</option> also enables
+        plugins to be loaded at startup under configurations when
+        plugins cannot be loaded at runtime.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins installed with the
+        <literal role="stmt">INSTALL PLUGIN</literal>
+        statement:</emphasis>
+      </para>
+
+      <para>
+        A plugin that is located in a plugin library file can be loaded
+        at runtime with the <literal role="mysqld">INSTALL
+        PLUGIN</literal> statement. The statement also registers the
+        plugin in the <literal>mysql.plugin</literal> table to cause the
+        server to load it on subsequent restarts. For this reason,
+        <literal role="mysqld">INSTALL PLUGIN</literal> requires the
+        <literal role="priv">INSERT</literal> privilege for the
+        <literal>mysql.plugin</literal> table.
+      </para>
+
+      <para>
+        If a plugin is named both using a
+        <option role="mysqld">--plugin-load</option> option and in the
+        <literal>mysql.plugin</literal> table, the server starts but
+        writes these messages to the error log:
+      </para>
+
+<programlisting>
+100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
+100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
+with soname '<replaceable>plugin_object_file</replaceable>'.
+</programlisting>
+
+      <para>
+        Example: The <option role="mysqld">--plugin-load</option> option
+        installs a plugin at server startup. To install a plugin named
+        <literal>myplugin</literal> in a plugin library file named
+        <filename>somepluglib.so</filename>, use these lines in a
+        <filename>my.cnf</filename> file:
+      </para>
+
+<programlisting>
+[mysqld]
+plugin-load=myplugin=somepluglib.so
+</programlisting>
+
+      <para>
+        In this case, the plugin is not registered in
+        <literal>mysql.plugin</literal>. Restarting the server without
+        the <option role="mysqld">--plugin-load</option> option causes
+        the plugin not to be loaded at startup.
+      </para>
+
+      <para>
+        Alternatively, the <literal role="stmt">INSTALL PLUGIN</literal>
+        statement causes the server to load the plugin code from the
+        library file at runtime:
+      </para>
+
+<programlisting>
+mysql&gt; <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
+</programlisting>
+
+      <para>
+        <literal role="stmt">INSTALL PLUGIN</literal> also causes
+        <quote>permanent</quote> plugin registration: The server lists
+        the plugin in the <literal>mysql.plugin</literal> table to
+        ensure that it is loaded on subsequent server restarts.
+      </para>
+
+      <para>
+        Many plugins can be loaded either at server startup or at
+        runtime. However, if a plugin is designed such that it must be
+        loaded and initialized during server startup, use
+        <option role="mysqld">--plugin-load</option> rather than
+        <literal role="stmt">INSTALL PLUGIN</literal>.
+      </para>
+
+      <para>
+        While a plugin is loaded, information about it is available at
+        runtime from several sources, such as the
+        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
+        and the <literal role="stmt">SHOW PLUGINS</literal> statement.
+        For more information, see
+        <xref linkend="obtaining-plugin-information"/>.
+      </para>
+
+      <bridgehead id="server-plugin-activating">
+        Controlling Plugin Activation
+      </bridgehead>
+
+      <para>
+        If the server knows about a plugin when it starts (for example,
+        because the plugin is named using a
+        <option role="mysqld">--plugin-load</option> option or
+        registered in the <literal>mysql.plugin</literal> table), the
+        server loads and enables the plugin by default. It is possible
+        to control activation for such a plugin using a
+        <literal>--<replaceable>plugin_name</replaceable>[=<replaceable>value</replaceable>]</literal>
+        startup option named after the plugin. In the following
+        descriptions, <replaceable>plugin_name</replaceable> stands for
+        a plugin name such as <literal>innodb</literal> or
+        <literal>csv</literal>. As with other options, dashes and
+        underscores are interchangeable in option names. For example,
+        <option>--my_plugin=ON</option> and
+        <option>--my-plugin=ON</option> are equivalent.
+      </para>
+
+      <para>
         As of MySQL 5.1.36, these options control plugin loading:
       </para>
 

@@ -15027,7 +15270,7 @@
           </para>
 
           <para>
-            Tells the server not to enable the plugin.
+            Tells the server to disable the plugin.
           </para>
         </listitem>
 

@@ -15037,11 +15280,11 @@
           </para>
 
           <para>
-            Tells the server to enable the plugin. If the plugin fails
-            to initialize, the server runs with the plugin disabled.
-            Specifying the option as
+            Tells the server to enable the plugin. (Specifying the
+            option as
             <option>--<replaceable>plugin_name</replaceable></option>
-            without a value also tells the server to enable the plugin.
+            without a value has the same effect.) If the plugin fails to
+            initialize, the server runs with the plugin disabled.
           </para>
         </listitem>
 

@@ -15054,7 +15297,7 @@
             Tells the server to enable the plugin, but if plugin
             initialization fails, the server does not start. In other
             words, this option forces the server to run with the plugin
-            or not at all.
+            enabled or not at all.
           </para>
         </listitem>
 

@@ -15068,12 +15311,13 @@
       <para>
         Suppose that <literal>CSV</literal>,
         <literal>BLACKHOLE</literal>, and <literal>ARCHIVE</literal> are
-        built as pluggable storage engines and that you want the server
+        built-in pluggable storage engines and that you want the server
         to load them at startup, subject to these conditions: The server
         is permitted to run if <literal>CSV</literal> initialization
         fails, but must require that <literal>BLACKHOLE</literal>
-        initialization succeed. <literal>ARCHIVE</literal> should be
-        disabled. To accomplish that, use these lines in an option file:
+        initialization succeeds, and <literal>ARCHIVE</literal> should
+        be disabled. To accomplish that, use these lines in an option
+        file:
       </para>
 
 <programlisting>

@@ -15146,23 +15390,50 @@
       </para>
 
       <para>
-        Absence of a plugin may require adjustment to other options. For
+        Disabling a plugin may require adjustment to other options. For
         example, if <literal role="se">InnoDB</literal> is disabled,
         other <filename>innodb_<replaceable>xxx</replaceable></filename>
         options likely will need to be omitted from the startup command.
-        In addition, if the server would use
+        In addition, if the server is configured to use
         <literal role="se">InnoDB</literal> as the default storage
-        engine, it will not start unless you select another available
+        engine, it will not start unless you specify another available
         storage engine with
         <option role="mysqld">--default-storage-engine</option>.
       </para>
 
+      <bridgehead id="server-plugin-uninstalling">
+        Uninstalling Plugins
+      </bridgehead>
+
       <para>
-        Plugins can also be loaded at runtime, using the
-        <literal role="stmt">INSTALL PLUGIN</literal> statement. See
-        <xref linkend="plugin-installing-uninstalling"/>.
+        A plugin known to the server can be uninstalled to disable it at
+        runtime with the <literal role="stmt">UNINSTALL PLUGIN</literal>
+        statement. The statement unloads the plugin and removes it from
+        the <literal>mysql.plugin</literal> table if it is registered
+        there. For this reason, <literal role="stmt">UNINSTALL
+        PLUGIN</literal> statement requires the
+        <literal role="priv">DELETE</literal> privilege for the
+        <literal>mysql.plugin</literal> table. With the plugin no longer
+        registered in the table, the server will not load the plugin
+        automatically for subsequent restarts.
       </para>
 
+      <para>
+        <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
+        plugins regardless of whether they were loaded with
+        <literal role="stmt">INSTALL PLUGIN</literal> or
+        <option role="mysqld">--plugin-load</option>.
+      </para>
+
+      <para>
+        <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
+        plugins that are built in to the server. These can be identified
+        as those that have a library name of <literal>NULL</literal> in
+        the output from
+        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
+        <literal role="stmt">SHOW PLUGINS</literal>.
+      </para>
+
     </section>
 
     <section id="obtaining-plugin-information">


Modified: trunk/refman-5.1/extending-mysql.xml
===================================================================
--- trunk/refman-5.1/extending-mysql.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.1/extending-mysql.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 3, Lines Added: 4, Lines Deleted: 77; 3763 bytes

@@ -2274,79 +2274,6 @@
 
       </section>
 
-      <section id="registering-plugins">
-
-        <title>Registering Plugins with the Server</title>
-
-        <para>
-          Server plugins must be registered with the server before they
-          can be used. You can load a plugin at server startup with the
-          <option role="mysqld">plugin-load</option> option or at
-          runtime with the <literal role="stmt">INSTALL PLUGIN</literal>
-          statement.
-        </para>
-
-        <para>
-          The <option role="mysqld">plugin-load</option> option installs
-          a plugin at server startup. To install a plugin named
-          <literal>myplugin</literal> in a plugin library file named
-          <filename>somepluglib.so</filename>, use these lines in a
-          <filename>my.cnf</filename> file:
-        </para>
-
-<programlisting>
-[mysqld]
-plugin-load=myplugin=somepluglib.so
-</programlisting>
-
-        <para>
-          In this case, the plugin is not installed permanently.
-          Restarting without the
-          <option role="mysqld">plugin-load</option> option causes the
-          plugin not to be loaded at startup.
-        </para>
-
-        <para>
-          Alternatively, the <literal role="stmt">INSTALL
-          PLUGIN</literal> statement causes the server to register the
-          plugin and load the plugin code from the library file at
-          runtime:
-        </para>
-
-<programlisting>
-mysql&gt; <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
-</programlisting>
-
-        <para>
-          <literal role="stmt">INSTALL PLUGIN</literal> causes
-          <quote>permanent</quote> plugin registration: The server lists
-          the plugin in the <literal>mysql.plugin</literal> table to
-          ensure that it is loaded on subsequent server restarts.
-        </para>
-
-        <para>
-          Many plugins can be loaded either at server startup or at
-          runtime. However, if a plugin is designed such that it must be
-          loaded and initialized during server startup,
-          <literal role="stmt">INSTALL PLUGIN</literal> is not
-          appropriate and you must use
-          <option role="mysqld">plugin-load</option>.
-        </para>
-
-        <para>
-              To verify plugin installation, examine the
-          <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-          or use the <literal role="stmt">SHOW PLUGINS</literal>
-          statement.
-        </para>
-
-        <para>
-          For additional information about plugin loading, see
-          <xref linkend="plugin-installing-uninstalling"/>.
-        </para>
-
-      </section>
-
 <!--
       <section id="writing-storage-engine-plugins">
 

@@ -3126,9 +3053,9 @@
           <listitem>
             <para>
               To verify plugin installation, examine the
-          <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-          or use the <literal role="stmt">SHOW PLUGINS</literal>
-          statement.
+              <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+              table or use the <literal role="stmt">SHOW
+              PLUGINS</literal> statement.
             </para>
           </listitem>
 

@@ -3382,7 +3309,7 @@
         </para>
 
         <para>
-              To verify plugin installation, examine the
+          To verify plugin installation, examine the
           <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
           or use the <literal role="stmt">SHOW PLUGINS</literal>
           statement.


Modified: trunk/refman-5.1/sql-syntax-server-administration.xml
===================================================================
--- trunk/refman-5.1/sql-syntax-server-administration.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.1/sql-syntax-server-administration.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 2, Lines Added: 1, Lines Deleted: 174; 6415 bytes

@@ -409,8 +409,7 @@
 
       <para>
         There are several aspects to the <literal>GRANT</literal>
-        statement, described under the following topics in this
-        section:
+        statement, described under the following topics in this section:
       </para>
 
       <itemizedlist>

@@ -3227,178 +3226,6 @@
 
     <title>Plugin and User-Defined Function Statements</title>
 
-    <section id="plugin-installing-uninstalling">
-
-      <title>Installing and Uninstalling Plugins</title>
-
-      <indexterm>
-        <primary>installing plugins</primary>
-      </indexterm>
-
-      <indexterm>
-        <primary>plugins</primary>
-        <secondary>installing</secondary>
-      </indexterm>
-
-      <indexterm>
-        <primary>uninstalling plugins</primary>
-      </indexterm>
-
-      <indexterm>
-        <primary>plugins</primary>
-        <secondary>uninstalling</secondary>
-      </indexterm>
-
-      <para>
-        This section compares the various methods of installing and
-        uninstalling server plugins. See also
-        <xref linkend="server-plugin-options"/>.
-      </para>
-
-      <para>
-        <option role="mysqld">--plugin-load</option> option:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Loads the plugin code at server startup to enable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Does not register the plugin in
-            <literal>mysql.plugin</literal>. For subsequent restarts,
-            the server loads the plugin again only if
-            <option role="mysqld">--plugin-load</option> is given again.
-            That is, this option effects a one-time installation that
-            persists only for one server invocation.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        <literal role="stmt">INSTALL PLUGIN</literal> statement:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Loads the plugin code at runtime to enable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Registers the plugin in the <literal>mysql.plugin</literal>
-            table. Registration causes the server to load the plugin
-            automatically for subsequent restarts. That is, it effects
-            an installation that persists until the plugin is
-            uninstalled explicitly.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Requires the <literal role="priv">INSERT</literal> privilege
-            for the <literal>mysql.plugin</literal> table.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> statement:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Unloads the plugin code at runtime to disable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Unregisters the plugin from <literal>mysql.plugin</literal>
-            if it is registered there. The server will not load it
-            automatically for subsequent restarts.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Requires the <literal role="priv">DELETE</literal> privilege
-            for the <literal>mysql.plugin</literal> table.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        While a plugin is loaded, information about it is available at
-        runtime from several sources, such as the
-        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-        and the <literal role="stmt">SHOW PLUGINS</literal> statement.
-        For more information, see
-        <xref linkend="obtaining-plugin-information"/>.
-      </para>
-
-      <para>
-        If <option role="mysqld">--plugin-load</option> is given at
-        startup for a plugin already installed with
-        <literal role="stmt">INSTALL PLUGIN</literal> during a previous
-        server invocation, the server starts but writes these messages
-        to the error log:
-      </para>
-
-<programlisting>
-100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
-100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
-with soname '<replaceable>plugin_object_file</replaceable>'.
-</programlisting>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
-        plugins regardless of whether they were loaded with
-        <literal role="stmt">INSTALL PLUGIN</literal> or
-        <option role="mysqld">--plugin-load</option>. In the latter
-        case, <literal role="stmt">UNINSTALL PLUGIN</literal> does not
-        unregister the plugin from <literal>mysql.plugin</literal>
-        because <option role="mysqld">--plugin-load</option> did not
-        register it.
-      </para>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
-        plugins that are compiled into the server. (These can be
-        identified as those that have a library name of
-        <literal>NULL</literal> in the output from
-        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
-        <literal role="stmt">SHOW PLUGINS</literal>.)
-      </para>
-
-      <para>
-        If the server is started with the
-        <option role="mysqld">--skip-grant-tables</option> option, it
-        does not consult the <literal>mysql.plugins</literal> table and
-        thus does not load plugins installed with the
-        <literal role="stmt">INSTALL PLUGIN</literal> statement.
-        <option role="mysqld">--plugin-load</option> enables plugins to
-        be loaded even when
-        <option role="mysqld">--skip-grant-tables</option> is given.
-        <option role="mysqld">--plugin-load</option> also enables
-        plugins to be loaded at startup under configurations when
-        plugins cannot be loaded at runtime.
-      </para>
-
-    </section>
-
     <section id="create-function-udf">
 
       <title><literal role="stmt">CREATE FUNCTION</literal> Syntax for User-Defined


Modified: trunk/refman-5.5/dba-mysqld-server-core.xml
===================================================================
--- trunk/refman-5.5/dba-mysqld-server-core.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.5/dba-mysqld-server-core.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 9, Lines Added: 325, Lines Deleted: 28; 17121 bytes

@@ -15583,23 +15583,262 @@
       and server extensions.
     </para>
 
-    <section id="server-plugin-options">
+    <section id="server-plugin-loading">
 
-      <title>Server Options for Loading Plugins</title>
+      <title>Installing and Uninstalling Plugins</title>
 
+      <indexterm>
+        <primary>installing plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>installing</secondary>
+      </indexterm>
+
+      <indexterm>
+        <primary>activating plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>activating</secondary>
+      </indexterm>
+
+      <indexterm>
+        <primary>uninstalling plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>uninstalling</secondary>
+      </indexterm>
+
       <para>
-        The server can control plugin activation using startup options
-        named for the plugins. For example, many storage engines can be
-        built in pluggable form and loaded when the server starts. In
-        the following descriptions,
+        Server plugins must be loaded in to the server before they can
+        be used. MySQL enables you to load a plugin at server startup or
+        at runtime. It is also possible to control the activation of
+        loaded plugins at startup, and to unload them at runtime.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-installing">Installing
+            plugins</link>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-activating">Controlling plugin
+            activation</link>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-uninstalling">Uninstalling
+            plugins</link>
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <bridgehead id="server-plugin-installing">
+        Installing Plugins
+      </bridgehead>
+
+      <para>
+        Server plugins must be known to the server before they can be
+        used. A plugin can be made known several ways, as described
+        here. In the following descriptions,
         <replaceable>plugin_name</replaceable> stands for a plugin name
         such as <literal>innodb</literal> or <literal>csv</literal>.
       </para>
 
       <para>
-        In MySQL &current-series;, these options control plugin loading:
+        <emphasis role="bold">Built-in plugins:</emphasis>
       </para>
 
+      <para>
+        A plugin that is built in to the server is known by the server
+        automatically. Normally, the server enables the plugin at
+        startup, although this can be changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins registered in the
+        <literal>mysql.plugin</literal> table:</emphasis>
+      </para>
+
+      <para>
+        The <literal>mysql.plugin</literal> table serves as a registry
+        of plugins. The server normally enables each plugin listed in
+        the table at startup, although whether a given plugin is enabled
+        can be changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option. If the server is started with the
+        <option role="mysqld">--skip-grant-tables</option> option, it
+        does not consult this table and does not load the plugins listed
+        there.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins named with the
+        <option role="mysqld">--plugin-load</option> option:</emphasis>
+      </para>
+
+      <para>
+        A plugin that is located in a plugin library file can be loaded
+        at server startup with the
+        <option role="mysqld">--plugin-load</option> option. Normally,
+        the server enables the plugin at startup, although this can be
+        changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option.
+      </para>
+
+      <para>
+        The option value is a semicolon-separated list of
+        <literal><replaceable>name</replaceable>=<replaceable>plugin_library</replaceable></literal>
+        pairs. Each <replaceable>name</replaceable> is the name of the
+        plugin, and <replaceable>plugin_library</replaceable> is the
+        name of the shared library that contains the plugin code. If a
+        plugin library is named without any preceding plugin name, the
+        server loads all plugins in the library. Each library file must
+        be located in the directory named by the
+        <literal role="sysvar">plugin_dir</literal> system variable.
+      </para>
+
+      <para>
+        This option does not register any plugin in the
+        <literal>mysql.plugin</literal> table. For subsequent restarts,
+        the server loads the plugin again only if
+        <option role="mysqld">--plugin-load</option> is given again.
+        That is, this option effects a one-time installation that
+        persists only for one server invocation.
+      </para>
+
+      <para>
+        <option role="mysqld">--plugin-load</option> enables plugins to
+        be loaded even when
+        <option role="mysqld">--skip-grant-tables</option> is given
+        (which causes the server to ignore the
+        <literal>mysql.plugin</literal> table).
+        <option role="mysqld">--plugin-load</option> also enables
+        plugins to be loaded at startup under configurations when
+        plugins cannot be loaded at runtime.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins installed with the
+        <literal role="stmt">INSTALL PLUGIN</literal>
+        statement:</emphasis>
+      </para>
+
+      <para>
+        A plugin that is located in a plugin library file can be loaded
+        at runtime with the <literal role="mysqld">INSTALL
+        PLUGIN</literal> statement. The statement also registers the
+        plugin in the <literal>mysql.plugin</literal> table to cause the
+        server to load it on subsequent restarts. For this reason,
+        <literal role="mysqld">INSTALL PLUGIN</literal> requires the
+        <literal role="priv">INSERT</literal> privilege for the
+        <literal>mysql.plugin</literal> table.
+      </para>
+
+      <para>
+        If a plugin is named both using a
+        <option role="mysqld">--plugin-load</option> option and in the
+        <literal>mysql.plugin</literal> table, the server starts but
+        writes these messages to the error log:
+      </para>
+
+<programlisting>
+100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
+100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
+with soname '<replaceable>plugin_object_file</replaceable>'.
+</programlisting>
+
+      <para>
+        Example: The <option role="mysqld">--plugin-load</option> option
+        installs a plugin at server startup. To install a plugin named
+        <literal>myplugin</literal> in a plugin library file named
+        <filename>somepluglib.so</filename>, use these lines in a
+        <filename>my.cnf</filename> file:
+      </para>
+
+<programlisting>
+[mysqld]
+plugin-load=myplugin=somepluglib.so
+</programlisting>
+
+      <para>
+        In this case, the plugin is not registered in
+        <literal>mysql.plugin</literal>. Restarting the server without
+        the <option role="mysqld">--plugin-load</option> option causes
+        the plugin not to be loaded at startup.
+      </para>
+
+      <para>
+        Alternatively, the <literal role="stmt">INSTALL PLUGIN</literal>
+        statement causes the server to load the plugin code from the
+        library file at runtime:
+      </para>
+
+<programlisting>
+mysql&gt; <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
+</programlisting>
+
+      <para>
+        <literal role="stmt">INSTALL PLUGIN</literal> also causes
+        <quote>permanent</quote> plugin registration: The server lists
+        the plugin in the <literal>mysql.plugin</literal> table to
+        ensure that it is loaded on subsequent server restarts.
+      </para>
+
+      <para>
+        Many plugins can be loaded either at server startup or at
+        runtime. However, if a plugin is designed such that it must be
+        loaded and initialized during server startup, use
+        <option role="mysqld">--plugin-load</option> rather than
+        <literal role="stmt">INSTALL PLUGIN</literal>.
+      </para>
+
+      <para>
+        While a plugin is loaded, information about it is available at
+        runtime from several sources, such as the
+        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
+        and the <literal role="stmt">SHOW PLUGINS</literal> statement.
+        For more information, see
+        <xref linkend="obtaining-plugin-information"/>.
+      </para>
+
+      <bridgehead id="server-plugin-activating">
+        Controlling Plugin Activation
+      </bridgehead>
+
+      <para>
+        If the server knows about a plugin when it starts (for example,
+        because the plugin is named using a
+        <option role="mysqld">--plugin-load</option> option or
+        registered in the <literal>mysql.plugin</literal> table), the
+        server loads and enables the plugin by default. It is possible
+        to control activation for such a plugin using a
+        <literal>--<replaceable>plugin_name</replaceable>[=<replaceable>value</replaceable>]</literal>
+        startup option named after the plugin. In the following
+        descriptions, <replaceable>plugin_name</replaceable> stands for
+        a plugin name such as <literal>innodb</literal> or
+        <literal>csv</literal>. As with other options, dashes and
+        underscores are interchangeable in option names. For example,
+        <option>--my_plugin=ON</option> and
+        <option>--my-plugin=ON</option> are equivalent.
+      </para>
+
       <itemizedlist>
 
         <listitem>

@@ -15608,7 +15847,7 @@
           </para>
 
           <para>
-            Tells the server not to enable the plugin.
+            Tells the server to disable the plugin.
           </para>
         </listitem>
 

@@ -15618,11 +15857,11 @@
           </para>
 
           <para>
-            Tells the server to enable the plugin. If the plugin fails
-            to initialize, the server runs with the plugin disabled.
-            Specifying the option as
+            Tells the server to enable the plugin. (Specifying the
+            option as
             <option>--<replaceable>plugin_name</replaceable></option>
-            without a value also tells the server to enable the plugin.
+            without a value has the same effect.) If the plugin fails to
+            initialize, the server runs with the plugin disabled.
           </para>
         </listitem>
 

@@ -15635,7 +15874,7 @@
             Tells the server to enable the plugin, but if plugin
             initialization fails, the server does not start. In other
             words, this option forces the server to run with the plugin
-            or not at all.
+            enabled or not at all.
           </para>
         </listitem>
 

@@ -15661,14 +15900,21 @@
       </para>
 
       <para>
+        The activation state for plugins is visible in the
+        <literal>LOAD_OPTION</literal> column of the
+        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table.
+      </para>
+
+      <para>
         Suppose that <literal>CSV</literal>,
         <literal>BLACKHOLE</literal>, and <literal>ARCHIVE</literal> are
-        built as pluggable storage engines and that you want the server
+        built-in pluggable storage engines and that you want the server
         to load them at startup, subject to these conditions: The server
         is permitted to run if <literal>CSV</literal> initialization
         fails, but must require that <literal>BLACKHOLE</literal>
-        initialization succeed. <literal>ARCHIVE</literal> should be
-        disabled. To accomplish that, use these lines in an option file:
+        initialization succeeds, and <literal>ARCHIVE</literal> should
+        be disabled. To accomplish that, use these lines in an option
+        file:
       </para>
 
 <programlisting>

@@ -15692,9 +15938,9 @@
       </para>
 
       <para>
-        Before MySQL &current-series;, plugin options are boolean
-        options (see <xref linkend="option-modifiers"/>). That is, any
-        of these options enable the plugin:
+        Before MySQL 5.1.36, plugin options are boolean options (see
+        <xref linkend="option-modifiers"/>). That is, any of these
+        options enable the plugin:
       </para>
 
 <programlisting>

@@ -15714,8 +15960,8 @@
 </programlisting>
 
       <para>
-        If you upgrade to MySQL &current-series; from an older version
-        and previously used options of the form
+        If you upgrade to MySQL &current-series; from a version older
+        than 5.1.36 and previously used options of the form
         <option>--<replaceable>plugin_name</replaceable>=0</option> or
         <option>--<replaceable>plugin_name</replaceable>=1</option>, the
         equivalent options are now

@@ -15724,7 +15970,9 @@
         <option>--<replaceable>plugin_name</replaceable>=ON</option>,
         respectively. You also have the choice of requiring plugins to
         start successfully by using
-        <option>--<replaceable>plugin_name</replaceable>=FORCE</option>.
+        <option>--<replaceable>plugin_name</replaceable>=FORCE</option>
+        or
+        <option>--<replaceable>plugin_name</replaceable>=FORCE_PLUS_PERMANENT</option>.
       </para>
 
       <para>

@@ -15741,23 +15989,72 @@
       </para>
 
       <para>
-        Absence of a plugin may require adjustment to other options. For
+        Disabling a plugin may require adjustment to other options. For
         example, if <literal role="se">InnoDB</literal> is disabled,
         other <filename>innodb_<replaceable>xxx</replaceable></filename>
         options likely will need to be omitted from the startup command.
-        In addition, if the server would use
+        In addition, if the server is configured to use
         <literal role="se">InnoDB</literal> as the default storage
-        engine, it will not start unless you select another available
+        engine, it will not start unless you specify another available
         storage engine with
         <option role="mysqld">--default-storage-engine</option>.
       </para>
 
+      <bridgehead id="server-plugin-uninstalling">
+        Uninstalling Plugins
+      </bridgehead>
+
       <para>
-        Plugins can also be loaded at runtime, using the
-        <literal role="stmt">INSTALL PLUGIN</literal> statement. See
-        <xref linkend="plugin-installing-uninstalling"/>.
+        A plugin known to the server can be uninstalled to disable it at
+        runtime with the <literal role="stmt">UNINSTALL PLUGIN</literal>
+        statement. The statement unloads the plugin and removes it from
+        the <literal>mysql.plugin</literal> table if it is registered
+        there. For this reason, <literal role="stmt">UNINSTALL
+        PLUGIN</literal> statement requires the
+        <literal role="priv">DELETE</literal> privilege for the
+        <literal>mysql.plugin</literal> table. With the plugin no longer
+        registered in the table, the server will not load the plugin
+        automatically for subsequent restarts.
       </para>
 
+      <para>
+        <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
+        plugins regardless of whether they were loaded with
+        <literal role="stmt">INSTALL PLUGIN</literal> or
+        <option role="mysqld">--plugin-load</option>.
+      </para>
+
+      <para>
+        <literal role="stmt">UNINSTALL PLUGIN</literal> is subject to
+        these exceptions:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            It cannot unload plugins that are built in to the server.
+            These can be identified as those that have a library name of
+            <literal>NULL</literal> in the output from
+            <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
+            <literal role="stmt">SHOW PLUGINS</literal>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            It cannot unload plugins for which the server was started
+            with
+            <option>--<replaceable>plugin_name</replaceable>=FORCE_PLUS_PERMANENT</option>,
+            which prevents plugin unloading at runtime. These can be
+            identified from the <literal>LOAD_OPTION</literal> column of
+            the <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+            table.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </section>
 
     <section id="obtaining-plugin-information">


Modified: trunk/refman-5.5/extending-mysql.xml
===================================================================
--- trunk/refman-5.5/extending-mysql.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.5/extending-mysql.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 4, Lines Added: 5, Lines Deleted: 78; 4084 bytes

@@ -2853,79 +2853,6 @@
 
       </section>
 
-      <section id="registering-plugins">
-
-        <title>Registering Plugins with the Server</title>
-
-        <para>
-          Server plugins must be registered with the server before they
-          can be used. You can load a plugin at server startup with the
-          <option role="mysqld">plugin-load</option> option or at
-          runtime with the <literal role="stmt">INSTALL PLUGIN</literal>
-          statement.
-        </para>
-
-        <para>
-          The <option role="mysqld">plugin-load</option> option installs
-          a plugin at server startup. To install a plugin named
-          <literal>myplugin</literal> in a plugin library file named
-          <filename>somepluglib.so</filename>, use these lines in a
-          <filename>my.cnf</filename> file:
-        </para>
-
-<programlisting>
-[mysqld]
-plugin-load=myplugin=somepluglib.so
-</programlisting>
-
-        <para>
-          In this case, the plugin is not installed permanently.
-          Restarting without the
-          <option role="mysqld">plugin-load</option> option causes the
-          plugin not to be loaded at startup.
-        </para>
-
-        <para>
-          Alternatively, the <literal role="stmt">INSTALL
-          PLUGIN</literal> statement causes the server to register the
-          plugin and load the plugin code from the library file at
-          runtime:
-        </para>
-
-<programlisting>
-mysql&gt; <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
-</programlisting>
-
-        <para>
-          <literal role="stmt">INSTALL PLUGIN</literal> causes
-          <quote>permanent</quote> plugin registration: The server lists
-          the plugin in the <literal>mysql.plugin</literal> table to
-          ensure that it is loaded on subsequent server restarts.
-        </para>
-
-        <para>
-          Many plugins can be loaded either at server startup or at
-          runtime. However, if a plugin is designed such that it must be
-          loaded and initialized during server startup,
-          <literal role="stmt">INSTALL PLUGIN</literal> is not
-          appropriate and you must use
-          <option role="mysqld">plugin-load</option>.
-        </para>
-
-        <para>
-              To verify plugin installation, examine the
-          <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-          or use the <literal role="stmt">SHOW PLUGINS</literal>
-          statement.
-        </para>
-
-        <para>
-          For additional information about plugin loading, see
-          <xref linkend="plugin-installing-uninstalling"/>.
-        </para>
-
-      </section>
-
 <!--
       <section id="writing-storage-engine-plugins">
 

@@ -3697,9 +3624,9 @@
           <listitem>
             <para>
               To verify plugin installation, examine the
-          <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-          or use the <literal role="stmt">SHOW PLUGINS</literal>
-          statement.
+              <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+              table or use the <literal role="stmt">SHOW
+              PLUGINS</literal> statement.
             </para>
           </listitem>
 

@@ -3953,7 +3880,7 @@
         </para>
 
         <para>
-              To verify plugin installation, examine the
+          To verify plugin installation, examine the
           <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
           or use the <literal role="stmt">SHOW PLUGINS</literal>
           statement.

@@ -4677,7 +4604,7 @@
         </para>
 
         <para>
-              To verify plugin installation, examine the
+          To verify plugin installation, examine the
           <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
           or use the <literal role="stmt">SHOW PLUGINS</literal>
           statement.


Modified: trunk/refman-5.5/sql-syntax-server-administration.xml
===================================================================
--- trunk/refman-5.5/sql-syntax-server-administration.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.5/sql-syntax-server-administration.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 1, Lines Added: 0, Lines Deleted: 172; 6126 bytes

@@ -3107,178 +3107,6 @@
 
     <title>Plugin and User-Defined Function Statements</title>
 
-    <section id="plugin-installing-uninstalling">
-
-      <title>Installing and Uninstalling Plugins</title>
-
-      <indexterm>
-        <primary>installing plugins</primary>
-      </indexterm>
-
-      <indexterm>
-        <primary>plugins</primary>
-        <secondary>installing</secondary>
-      </indexterm>
-
-      <indexterm>
-        <primary>uninstalling plugins</primary>
-      </indexterm>
-
-      <indexterm>
-        <primary>plugins</primary>
-        <secondary>uninstalling</secondary>
-      </indexterm>
-
-      <para>
-        This section compares the various methods of installing and
-        uninstalling server plugins. See also
-        <xref linkend="server-plugin-options"/>.
-      </para>
-
-      <para>
-        <option role="mysqld">--plugin-load</option> option:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Loads the plugin code at server startup to enable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Does not register the plugin in
-            <literal>mysql.plugin</literal>. For subsequent restarts,
-            the server loads the plugin again only if
-            <option role="mysqld">--plugin-load</option> is given again.
-            That is, this option effects a one-time installation that
-            persists only for one server invocation.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        <literal role="stmt">INSTALL PLUGIN</literal> statement:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Loads the plugin code at runtime to enable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Registers the plugin in the <literal>mysql.plugin</literal>
-            table. Registration causes the server to load the plugin
-            automatically for subsequent restarts. That is, it effects
-            an installation that persists until the plugin is
-            uninstalled explicitly.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Requires the <literal role="priv">INSERT</literal> privilege
-            for the <literal>mysql.plugin</literal> table.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> statement:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Unloads the plugin code at runtime to disable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Unregisters the plugin from <literal>mysql.plugin</literal>
-            if it is registered there. The server will not load it
-            automatically for subsequent restarts.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Requires the <literal role="priv">DELETE</literal> privilege
-            for the <literal>mysql.plugin</literal> table.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        While a plugin is loaded, information about it is available at
-        runtime from several sources, such as the
-        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-        and the <literal role="stmt">SHOW PLUGINS</literal> statement.
-        For more information, see
-        <xref linkend="obtaining-plugin-information"/>.
-      </para>
-
-      <para>
-        If <option role="mysqld">--plugin-load</option> is given at
-        startup for a plugin already installed with
-        <literal role="stmt">INSTALL PLUGIN</literal> during a previous
-        server invocation, the server starts but writes these messages
-        to the error log:
-      </para>
-
-<programlisting>
-100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
-100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
-with soname '<replaceable>plugin_object_file</replaceable>'.
-</programlisting>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
-        plugins regardless of whether they were loaded with
-        <literal role="stmt">INSTALL PLUGIN</literal> or
-        <option role="mysqld">--plugin-load</option>. In the latter
-        case, <literal role="stmt">UNINSTALL PLUGIN</literal> does not
-        unregister the plugin from <literal>mysql.plugin</literal>
-        because <option role="mysqld">--plugin-load</option> did not
-        register it.
-      </para>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
-        plugins that are compiled into the server. (These can be
-        identified as those that have a library name of
-        <literal>NULL</literal> in the output from
-        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
-        <literal role="stmt">SHOW PLUGINS</literal>.)
-      </para>
-
-      <para>
-        If the server is started with the
-        <option role="mysqld">--skip-grant-tables</option> option, it
-        does not consult the <literal>mysql.plugins</literal> table and
-        thus does not load plugins installed with the
-        <literal role="stmt">INSTALL PLUGIN</literal> statement.
-        <option role="mysqld">--plugin-load</option> enables plugins to
-        be loaded even when
-        <option role="mysqld">--skip-grant-tables</option> is given.
-        <option role="mysqld">--plugin-load</option> also enables
-        plugins to be loaded at startup under configurations when
-        plugins cannot be loaded at runtime.
-      </para>
-
-    </section>
-
     <section id="create-function-udf">
 
       <title><literal role="stmt">CREATE FUNCTION</literal> Syntax for User-Defined


Modified: trunk/refman-5.6/dba-mysqld-server-core.xml
===================================================================
--- trunk/refman-5.6/dba-mysqld-server-core.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.6/dba-mysqld-server-core.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 6, Lines Added: 317, Lines Deleted: 22; 15731 bytes

@@ -15235,23 +15235,262 @@
       and server extensions.
     </para>
 
-    <section id="server-plugin-options">
+    <section id="server-plugin-loading">
 
-      <title>Server Options for Loading Plugins</title>
+      <title>Installing and Uninstalling Plugins</title>
 
+      <indexterm>
+        <primary>installing plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>installing</secondary>
+      </indexterm>
+
+      <indexterm>
+        <primary>activating plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>activating</secondary>
+      </indexterm>
+
+      <indexterm>
+        <primary>uninstalling plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>uninstalling</secondary>
+      </indexterm>
+
       <para>
-        The server can control plugin activation using startup options
-        named for the plugins. For example, many storage engines can be
-        built in pluggable form and loaded when the server starts. In
-        the following descriptions,
+        Server plugins must be loaded in to the server before they can
+        be used. MySQL enables you to load a plugin at server startup or
+        at runtime. It is also possible to control the activation of
+        loaded plugins at startup, and to unload them at runtime.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-installing">Installing
+            plugins</link>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-activating">Controlling plugin
+            activation</link>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-uninstalling">Uninstalling
+            plugins</link>
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <bridgehead id="server-plugin-installing">
+        Installing Plugins
+      </bridgehead>
+
+      <para>
+        Server plugins must be known to the server before they can be
+        used. A plugin can be made known several ways, as described
+        here. In the following descriptions,
         <replaceable>plugin_name</replaceable> stands for a plugin name
         such as <literal>innodb</literal> or <literal>csv</literal>.
       </para>
 
       <para>
-        In MySQL &current-series;, these options control plugin loading:
+        <emphasis role="bold">Built-in plugins:</emphasis>
       </para>
 
+      <para>
+        A plugin that is built in to the server is known by the server
+        automatically. Normally, the server enables the plugin at
+        startup, although this can be changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins registered in the
+        <literal>mysql.plugin</literal> table:</emphasis>
+      </para>
+
+      <para>
+        The <literal>mysql.plugin</literal> table serves as a registry
+        of plugins. The server normally enables each plugin listed in
+        the table at startup, although whether a given plugin is enabled
+        can be changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option. If the server is started with the
+        <option role="mysqld">--skip-grant-tables</option> option, it
+        does not consult this table and does not load the plugins listed
+        there.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins named with the
+        <option role="mysqld">--plugin-load</option> option:</emphasis>
+      </para>
+
+      <para>
+        A plugin that is located in a plugin library file can be loaded
+        at server startup with the
+        <option role="mysqld">--plugin-load</option> option. Normally,
+        the server enables the plugin at startup, although this can be
+        changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option.
+      </para>
+
+      <para>
+        The option value is a semicolon-separated list of
+        <literal><replaceable>name</replaceable>=<replaceable>plugin_library</replaceable></literal>
+        pairs. Each <replaceable>name</replaceable> is the name of the
+        plugin, and <replaceable>plugin_library</replaceable> is the
+        name of the shared library that contains the plugin code. If a
+        plugin library is named without any preceding plugin name, the
+        server loads all plugins in the library. Each library file must
+        be located in the directory named by the
+        <literal role="sysvar">plugin_dir</literal> system variable.
+      </para>
+
+      <para>
+        This option does not register any plugin in the
+        <literal>mysql.plugin</literal> table. For subsequent restarts,
+        the server loads the plugin again only if
+        <option role="mysqld">--plugin-load</option> is given again.
+        That is, this option effects a one-time installation that
+        persists only for one server invocation.
+      </para>
+
+      <para>
+        <option role="mysqld">--plugin-load</option> enables plugins to
+        be loaded even when
+        <option role="mysqld">--skip-grant-tables</option> is given
+        (which causes the server to ignore the
+        <literal>mysql.plugin</literal> table).
+        <option role="mysqld">--plugin-load</option> also enables
+        plugins to be loaded at startup under configurations when
+        plugins cannot be loaded at runtime.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins installed with the
+        <literal role="stmt">INSTALL PLUGIN</literal>
+        statement:</emphasis>
+      </para>
+
+      <para>
+        A plugin that is located in a plugin library file can be loaded
+        at runtime with the <literal role="mysqld">INSTALL
+        PLUGIN</literal> statement. The statement also registers the
+        plugin in the <literal>mysql.plugin</literal> table to cause the
+        server to load it on subsequent restarts. For this reason,
+        <literal role="mysqld">INSTALL PLUGIN</literal> requires the
+        <literal role="priv">INSERT</literal> privilege for the
+        <literal>mysql.plugin</literal> table.
+      </para>
+
+      <para>
+        If a plugin is named both using a
+        <option role="mysqld">--plugin-load</option> option and in the
+        <literal>mysql.plugin</literal> table, the server starts but
+        writes these messages to the error log:
+      </para>
+
+<programlisting>
+100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
+100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
+with soname '<replaceable>plugin_object_file</replaceable>'.
+</programlisting>
+
+      <para>
+        Example: The <option role="mysqld">--plugin-load</option> option
+        installs a plugin at server startup. To install a plugin named
+        <literal>myplugin</literal> in a plugin library file named
+        <filename>somepluglib.so</filename>, use these lines in a
+        <filename>my.cnf</filename> file:
+      </para>
+
+<programlisting>
+[mysqld]
+plugin-load=myplugin=somepluglib.so
+</programlisting>
+
+      <para>
+        In this case, the plugin is not registered in
+        <literal>mysql.plugin</literal>. Restarting the server without
+        the <option role="mysqld">--plugin-load</option> option causes
+        the plugin not to be loaded at startup.
+      </para>
+
+      <para>
+        Alternatively, the <literal role="stmt">INSTALL PLUGIN</literal>
+        statement causes the server to load the plugin code from the
+        library file at runtime:
+      </para>
+
+<programlisting>
+mysql&gt; <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
+</programlisting>
+
+      <para>
+        <literal role="stmt">INSTALL PLUGIN</literal> also causes
+        <quote>permanent</quote> plugin registration: The server lists
+        the plugin in the <literal>mysql.plugin</literal> table to
+        ensure that it is loaded on subsequent server restarts.
+      </para>
+
+      <para>
+        Many plugins can be loaded either at server startup or at
+        runtime. However, if a plugin is designed such that it must be
+        loaded and initialized during server startup, use
+        <option role="mysqld">--plugin-load</option> rather than
+        <literal role="stmt">INSTALL PLUGIN</literal>.
+      </para>
+
+      <para>
+        While a plugin is loaded, information about it is available at
+        runtime from several sources, such as the
+        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
+        and the <literal role="stmt">SHOW PLUGINS</literal> statement.
+        For more information, see
+        <xref linkend="obtaining-plugin-information"/>.
+      </para>
+
+      <bridgehead id="server-plugin-activating">
+        Controlling Plugin Activation
+      </bridgehead>
+
+      <para>
+        If the server knows about a plugin when it starts (for example,
+        because the plugin is named using a
+        <option role="mysqld">--plugin-load</option> option or
+        registered in the <literal>mysql.plugin</literal> table), the
+        server loads and enables the plugin by default. It is possible
+        to control activation for such a plugin using a
+        <literal>--<replaceable>plugin_name</replaceable>[=<replaceable>value</replaceable>]</literal>
+        startup option named after the plugin. In the following
+        descriptions, <replaceable>plugin_name</replaceable> stands for
+        a plugin name such as <literal>innodb</literal> or
+        <literal>csv</literal>. As with other options, dashes and
+        underscores are interchangeable in option names. For example,
+        <option>--my_plugin=ON</option> and
+        <option>--my-plugin=ON</option> are equivalent.
+      </para>
+
       <itemizedlist>
 
         <listitem>

@@ -15260,7 +15499,7 @@
           </para>
 
           <para>
-            Tells the server not to enable the plugin.
+            Tells the server to disable the plugin.
           </para>
         </listitem>
 

@@ -15270,11 +15509,11 @@
           </para>
 
           <para>
-            Tells the server to enable the plugin. If the plugin fails
-            to initialize, the server runs with the plugin disabled.
-            Specifying the option as
+            Tells the server to enable the plugin. (Specifying the
+            option as
             <option>--<replaceable>plugin_name</replaceable></option>
-            without a value also tells the server to enable the plugin.
+            without a value has the same effect.) If the plugin fails to
+            initialize, the server runs with the plugin disabled.
           </para>
         </listitem>
 

@@ -15287,7 +15526,7 @@
             Tells the server to enable the plugin, but if plugin
             initialization fails, the server does not start. In other
             words, this option forces the server to run with the plugin
-            or not at all.
+            enabled or not at all.
           </para>
         </listitem>
 

@@ -15313,14 +15552,21 @@
       </para>
 
       <para>
+        The activation state for plugins is visible in the
+        <literal>LOAD_OPTION</literal> column of the
+        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table.
+      </para>
+
+      <para>
         Suppose that <literal>CSV</literal>,
         <literal>BLACKHOLE</literal>, and <literal>ARCHIVE</literal> are
-        built as pluggable storage engines and that you want the server
+        built-in pluggable storage engines and that you want the server
         to load them at startup, subject to these conditions: The server
         is permitted to run if <literal>CSV</literal> initialization
         fails, but must require that <literal>BLACKHOLE</literal>
-        initialization succeed. <literal>ARCHIVE</literal> should be
-        disabled. To accomplish that, use these lines in an option file:
+        initialization succeeds, and <literal>ARCHIVE</literal> should
+        be disabled. To accomplish that, use these lines in an option
+        file:
       </para>
 
 <programlisting>

@@ -15357,23 +15603,72 @@
       </para>
 
       <para>
-        Absence of a plugin may require adjustment to other options. For
+        Disabling a plugin may require adjustment to other options. For
         example, if <literal role="se">InnoDB</literal> is disabled,
         other <filename>innodb_<replaceable>xxx</replaceable></filename>
         options likely will need to be omitted from the startup command.
-        In addition, if the server would use
+        In addition, if the server is configured to use
         <literal role="se">InnoDB</literal> as the default storage
-        engine, it will not start unless you select another available
+        engine, it will not start unless you specify another available
         storage engine with
         <option role="mysqld">--default-storage-engine</option>.
       </para>
 
+      <bridgehead id="server-plugin-uninstalling">
+        Uninstalling Plugins
+      </bridgehead>
+
       <para>
-        Plugins can also be loaded at runtime, using the
-        <literal role="stmt">INSTALL PLUGIN</literal> statement. See
-        <xref linkend="plugin-installing-uninstalling"/>.
+        A plugin known to the server can be uninstalled to disable it at
+        runtime with the <literal role="stmt">UNINSTALL PLUGIN</literal>
+        statement. The statement unloads the plugin and removes it from
+        the <literal>mysql.plugin</literal> table if it is registered
+        there. For this reason, <literal role="stmt">UNINSTALL
+        PLUGIN</literal> statement requires the
+        <literal role="priv">DELETE</literal> privilege for the
+        <literal>mysql.plugin</literal> table. With the plugin no longer
+        registered in the table, the server will not load the plugin
+        automatically for subsequent restarts.
       </para>
 
+      <para>
+        <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
+        plugins regardless of whether they were loaded with
+        <literal role="stmt">INSTALL PLUGIN</literal> or
+        <option role="mysqld">--plugin-load</option>.
+      </para>
+
+      <para>
+        <literal role="stmt">UNINSTALL PLUGIN</literal> is subject to
+        these exceptions:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            It cannot unload plugins that are built in to the server.
+            These can be identified as those that have a library name of
+            <literal>NULL</literal> in the output from
+            <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
+            <literal role="stmt">SHOW PLUGINS</literal>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            It cannot unload plugins for which the server was started
+            with
+            <option>--<replaceable>plugin_name</replaceable>=FORCE_PLUS_PERMANENT</option>,
+            which prevents plugin unloading at runtime. These can be
+            identified from the <literal>LOAD_OPTION</literal> column of
+            the <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+            table.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </section>
 
     <section id="obtaining-plugin-information">


Modified: trunk/refman-5.6/extending-mysql.xml
===================================================================
--- trunk/refman-5.6/extending-mysql.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.6/extending-mysql.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 4, Lines Added: 5, Lines Deleted: 78; 4084 bytes

@@ -2853,79 +2853,6 @@
 
       </section>
 
-      <section id="registering-plugins">
-
-        <title>Registering Plugins with the Server</title>
-
-        <para>
-          Server plugins must be registered with the server before they
-          can be used. You can load a plugin at server startup with the
-          <option role="mysqld">plugin-load</option> option or at
-          runtime with the <literal role="stmt">INSTALL PLUGIN</literal>
-          statement.
-        </para>
-
-        <para>
-          The <option role="mysqld">plugin-load</option> option installs
-          a plugin at server startup. To install a plugin named
-          <literal>myplugin</literal> in a plugin library file named
-          <filename>somepluglib.so</filename>, use these lines in a
-          <filename>my.cnf</filename> file:
-        </para>
-
-<programlisting>
-[mysqld]
-plugin-load=myplugin=somepluglib.so
-</programlisting>
-
-        <para>
-          In this case, the plugin is not installed permanently.
-          Restarting without the
-          <option role="mysqld">plugin-load</option> option causes the
-          plugin not to be loaded at startup.
-        </para>
-
-        <para>
-          Alternatively, the <literal role="stmt">INSTALL
-          PLUGIN</literal> statement causes the server to register the
-          plugin and load the plugin code from the library file at
-          runtime:
-        </para>
-
-<programlisting>
-mysql&gt; <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
-</programlisting>
-
-        <para>
-          <literal role="stmt">INSTALL PLUGIN</literal> causes
-          <quote>permanent</quote> plugin registration: The server lists
-          the plugin in the <literal>mysql.plugin</literal> table to
-          ensure that it is loaded on subsequent server restarts.
-        </para>
-
-        <para>
-          Many plugins can be loaded either at server startup or at
-          runtime. However, if a plugin is designed such that it must be
-          loaded and initialized during server startup,
-          <literal role="stmt">INSTALL PLUGIN</literal> is not
-          appropriate and you must use
-          <option role="mysqld">plugin-load</option>.
-        </para>
-
-        <para>
-              To verify plugin installation, examine the
-          <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-          or use the <literal role="stmt">SHOW PLUGINS</literal>
-          statement.
-        </para>
-
-        <para>
-          For additional information about plugin loading, see
-          <xref linkend="plugin-installing-uninstalling"/>.
-        </para>
-
-      </section>
-
 <!--
       <section id="writing-storage-engine-plugins">
 

@@ -3697,9 +3624,9 @@
           <listitem>
             <para>
               To verify plugin installation, examine the
-          <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-          or use the <literal role="stmt">SHOW PLUGINS</literal>
-          statement.
+              <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+              table or use the <literal role="stmt">SHOW
+              PLUGINS</literal> statement.
             </para>
           </listitem>
 

@@ -3953,7 +3880,7 @@
         </para>
 
         <para>
-              To verify plugin installation, examine the
+          To verify plugin installation, examine the
           <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
           or use the <literal role="stmt">SHOW PLUGINS</literal>
           statement.

@@ -4671,7 +4598,7 @@
         </para>
 
         <para>
-              To verify plugin installation, examine the
+          To verify plugin installation, examine the
           <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
           or use the <literal role="stmt">SHOW PLUGINS</literal>
           statement.


Modified: trunk/refman-5.6/sql-syntax-server-administration.xml
===================================================================
--- trunk/refman-5.6/sql-syntax-server-administration.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.6/sql-syntax-server-administration.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 1, Lines Added: 0, Lines Deleted: 172; 6126 bytes

@@ -3106,178 +3106,6 @@
 
     <title>Plugin and User-Defined Function Statements</title>
 
-    <section id="plugin-installing-uninstalling">
-
-      <title>Installing and Uninstalling Plugins</title>
-
-      <indexterm>
-        <primary>installing plugins</primary>
-      </indexterm>
-
-      <indexterm>
-        <primary>plugins</primary>
-        <secondary>installing</secondary>
-      </indexterm>
-
-      <indexterm>
-        <primary>uninstalling plugins</primary>
-      </indexterm>
-
-      <indexterm>
-        <primary>plugins</primary>
-        <secondary>uninstalling</secondary>
-      </indexterm>
-
-      <para>
-        This section compares the various methods of installing and
-        uninstalling server plugins. See also
-        <xref linkend="server-plugin-options"/>.
-      </para>
-
-      <para>
-        <option role="mysqld">--plugin-load</option> option:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Loads the plugin code at server startup to enable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Does not register the plugin in
-            <literal>mysql.plugin</literal>. For subsequent restarts,
-            the server loads the plugin again only if
-            <option role="mysqld">--plugin-load</option> is given again.
-            That is, this option effects a one-time installation that
-            persists only for one server invocation.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        <literal role="stmt">INSTALL PLUGIN</literal> statement:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Loads the plugin code at runtime to enable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Registers the plugin in the <literal>mysql.plugin</literal>
-            table. Registration causes the server to load the plugin
-            automatically for subsequent restarts. That is, it effects
-            an installation that persists until the plugin is
-            uninstalled explicitly.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Requires the <literal role="priv">INSERT</literal> privilege
-            for the <literal>mysql.plugin</literal> table.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> statement:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Unloads the plugin code at runtime to disable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Unregisters the plugin from <literal>mysql.plugin</literal>
-            if it is registered there. The server will not load it
-            automatically for subsequent restarts.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Requires the <literal role="priv">DELETE</literal> privilege
-            for the <literal>mysql.plugin</literal> table.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        While a plugin is loaded, information about it is available at
-        runtime from several sources, such as the
-        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-        and the <literal role="stmt">SHOW PLUGINS</literal> statement.
-        For more information, see
-        <xref linkend="obtaining-plugin-information"/>.
-      </para>
-
-      <para>
-        If <option role="mysqld">--plugin-load</option> is given at
-        startup for a plugin already installed with
-        <literal role="stmt">INSTALL PLUGIN</literal> during a previous
-        server invocation, the server starts but writes these messages
-        to the error log:
-      </para>
-
-<programlisting>
-100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
-100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
-with soname '<replaceable>plugin_object_file</replaceable>'.
-</programlisting>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
-        plugins regardless of whether they were loaded with
-        <literal role="stmt">INSTALL PLUGIN</literal> or
-        <option role="mysqld">--plugin-load</option>. In the latter
-        case, <literal role="stmt">UNINSTALL PLUGIN</literal> does not
-        unregister the plugin from <literal>mysql.plugin</literal>
-        because <option role="mysqld">--plugin-load</option> did not
-        register it.
-      </para>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
-        plugins that are compiled into the server. (These can be
-        identified as those that have a library name of
-        <literal>NULL</literal> in the output from
-        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
-        <literal role="stmt">SHOW PLUGINS</literal>.)
-      </para>
-
-      <para>
-        If the server is started with the
-        <option role="mysqld">--skip-grant-tables</option> option, it
-        does not consult the <literal>mysql.plugins</literal> table and
-        thus does not load plugins installed with the
-        <literal role="stmt">INSTALL PLUGIN</literal> statement.
-        <option role="mysqld">--plugin-load</option> enables plugins to
-        be loaded even when
-        <option role="mysqld">--skip-grant-tables</option> is given.
-        <option role="mysqld">--plugin-load</option> also enables
-        plugins to be loaded at startup under configurations when
-        plugins cannot be loaded at runtime.
-      </para>
-
-    </section>
-
     <section id="create-function-udf">
 
       <title><literal role="stmt">CREATE FUNCTION</literal> Syntax for User-Defined


Modified: trunk/refman-6.0/dba-mysqld-server-core.xml
===================================================================
--- trunk/refman-6.0/dba-mysqld-server-core.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-6.0/dba-mysqld-server-core.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 3, Lines Added: 285, Lines Deleted: 14; 13471 bytes

@@ -16283,20 +16283,263 @@
       and server extensions.
     </para>
 
-    <section id="server-plugin-options">
+    <section id="server-plugin-loading">
 
-      <title>Server Options for Loading Plugins</title>
+      <title>Installing and Uninstalling Plugins</title>
 
+      <indexterm>
+        <primary>installing plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>installing</secondary>
+      </indexterm>
+
+      <indexterm>
+        <primary>activating plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>activating</secondary>
+      </indexterm>
+
+      <indexterm>
+        <primary>uninstalling plugins</primary>
+      </indexterm>
+
+      <indexterm>
+        <primary>plugins</primary>
+        <secondary>uninstalling</secondary>
+      </indexterm>
+
       <para>
-        The server can control plugin activation using startup options
-        named for the plugins. For example, many storage engines can be
-        built in pluggable form and loaded when the server starts. In
-        the following descriptions,
+        Server plugins must be loaded in to the server before they can
+        be used. MySQL enables you to load a plugin at server startup or
+        at runtime. It is also possible to control the activation of
+        loaded plugins at startup, and to unload them at runtime.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-installing">Installing
+            plugins</link>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-activating">Controlling plugin
+            activation</link>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <link linkend="server-plugin-uninstalling">Uninstalling
+            plugins</link>
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <bridgehead id="server-plugin-installing">
+        Installing Plugins
+      </bridgehead>
+
+      <para>
+        Server plugins must be known to the server before they can be
+        used. A plugin can be made known several ways, as described
+        here. In the following descriptions,
         <replaceable>plugin_name</replaceable> stands for a plugin name
         such as <literal>innodb</literal> or <literal>csv</literal>.
       </para>
 
       <para>
+        <emphasis role="bold">Built-in plugins:</emphasis>
+      </para>
+
+      <para>
+        A plugin that is built in to the server is known by the server
+        automatically. Normally, the server enables the plugin at
+        startup, although this can be changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins registered in the
+        <literal>mysql.plugin</literal> table:</emphasis>
+      </para>
+
+      <para>
+        The <literal>mysql.plugin</literal> table serves as a registry
+        of plugins. The server normally enables each plugin listed in
+        the table at startup, although whether a given plugin is enabled
+        can be changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option. If the server is started with the
+        <option role="mysqld">--skip-grant-tables</option> option, it
+        does not consult this table and does not load the plugins listed
+        there.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins named with the
+        <option role="mysqld">--plugin-load</option> option:</emphasis>
+      </para>
+
+      <para>
+        A plugin that is located in a plugin library file can be loaded
+        at server startup with the
+        <option role="mysqld">--plugin-load</option> option. Normally,
+        the server enables the plugin at startup, although this can be
+        changed with the
+        <option>--<replaceable>plugin_name</replaceable></option>
+        option.
+      </para>
+
+      <para>
+        The option value is a semicolon-separated list of
+        <literal><replaceable>name</replaceable>=<replaceable>plugin_library</replaceable></literal>
+        pairs. Each <replaceable>name</replaceable> is the name of the
+        plugin, and <replaceable>plugin_library</replaceable> is the
+        name of the shared library that contains the plugin code. If a
+        plugin library is named without any preceding plugin name, the
+        server loads all plugins in the library. Each library file must
+        be located in the directory named by the
+        <literal role="sysvar">plugin_dir</literal> system variable.
+      </para>
+
+      <para>
+        This option does not register any plugin in the
+        <literal>mysql.plugin</literal> table. For subsequent restarts,
+        the server loads the plugin again only if
+        <option role="mysqld">--plugin-load</option> is given again.
+        That is, this option effects a one-time installation that
+        persists only for one server invocation.
+      </para>
+
+      <para>
+        <option role="mysqld">--plugin-load</option> enables plugins to
+        be loaded even when
+        <option role="mysqld">--skip-grant-tables</option> is given
+        (which causes the server to ignore the
+        <literal>mysql.plugin</literal> table).
+        <option role="mysqld">--plugin-load</option> also enables
+        plugins to be loaded at startup under configurations when
+        plugins cannot be loaded at runtime.
+      </para>
+
+      <para>
+        <emphasis role="bold">Plugins installed with the
+        <literal role="stmt">INSTALL PLUGIN</literal>
+        statement:</emphasis>
+      </para>
+
+      <para>
+        A plugin that is located in a plugin library file can be loaded
+        at runtime with the <literal role="mysqld">INSTALL
+        PLUGIN</literal> statement. The statement also registers the
+        plugin in the <literal>mysql.plugin</literal> table to cause the
+        server to load it on subsequent restarts. For this reason,
+        <literal role="mysqld">INSTALL PLUGIN</literal> requires the
+        <literal role="priv">INSERT</literal> privilege for the
+        <literal>mysql.plugin</literal> table.
+      </para>
+
+      <para>
+        If a plugin is named both using a
+        <option role="mysqld">--plugin-load</option> option and in the
+        <literal>mysql.plugin</literal> table, the server starts but
+        writes these messages to the error log:
+      </para>
+
+<programlisting>
+100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
+100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
+with soname '<replaceable>plugin_object_file</replaceable>'.
+</programlisting>
+
+      <para>
+        Example: The <option role="mysqld">--plugin-load</option> option
+        installs a plugin at server startup. To install a plugin named
+        <literal>myplugin</literal> in a plugin library file named
+        <filename>somepluglib.so</filename>, use these lines in a
+        <filename>my.cnf</filename> file:
+      </para>
+
+<programlisting>
+[mysqld]
+plugin-load=myplugin=somepluglib.so
+</programlisting>
+
+      <para>
+        In this case, the plugin is not registered in
+        <literal>mysql.plugin</literal>. Restarting the server without
+        the <option role="mysqld">--plugin-load</option> option causes
+        the plugin not to be loaded at startup.
+      </para>
+
+      <para>
+        Alternatively, the <literal role="stmt">INSTALL PLUGIN</literal>
+        statement causes the server to load the plugin code from the
+        library file at runtime:
+      </para>
+
+<programlisting>
+mysql&gt; <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
+</programlisting>
+
+      <para>
+        <literal role="stmt">INSTALL PLUGIN</literal> also causes
+        <quote>permanent</quote> plugin registration: The server lists
+        the plugin in the <literal>mysql.plugin</literal> table to
+        ensure that it is loaded on subsequent server restarts.
+      </para>
+
+      <para>
+        Many plugins can be loaded either at server startup or at
+        runtime. However, if a plugin is designed such that it must be
+        loaded and initialized during server startup, use
+        <option role="mysqld">--plugin-load</option> rather than
+        <literal role="stmt">INSTALL PLUGIN</literal>.
+      </para>
+
+      <para>
+        While a plugin is loaded, information about it is available at
+        runtime from several sources, such as the
+        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
+        and the <literal role="stmt">SHOW PLUGINS</literal> statement.
+        For more information, see
+        <xref linkend="obtaining-plugin-information"/>.
+      </para>
+
+      <bridgehead id="server-plugin-activating">
+        Controlling Plugin Activation
+      </bridgehead>
+
+      <para>
+        If the server knows about a plugin when it starts (for example,
+        because the plugin is named using a
+        <option role="mysqld">--plugin-load</option> option or
+        registered in the <literal>mysql.plugin</literal> table), the
+        server loads and enables the plugin by default. It is possible
+        to control activation for such a plugin using a
+        <literal>--<replaceable>plugin_name</replaceable></literal>
+        startup option named after the plugin. In the following
+        descriptions, <replaceable>plugin_name</replaceable> stands for
+        a plugin name such as <literal>innodb</literal> or
+        <literal>csv</literal>. As with other options, dashes and
+        underscores are interchangeable in option names. For example,
+        <option>--my_plugin=1</option> and
+        <option>--my-plugin=1</option> are equivalent.
+      </para>
+
+      <para>
         Options to load plugins are boolean options and are handled like
         other boolean options (see <xref linkend="option-modifiers"/>).
         That is, any of these options enable the plugin:

@@ -16335,8 +16578,9 @@
 </programlisting>
 
       <para>
-        If a plugin is disabled, either explicitly, or implicitly
-        because it was enabled but failed to initialize, aspects of
+        If a plugin is disabled, either explicitly with
+        <literal>OFF</literal> or implicitly because it was enabled with
+        <literal>ON</literal> but failed to initialize, aspects of
         server operation that require the plugin will change. For
         example, if the plugin implements a storage engine, existing
         tables for the storage engine become inaccessible, and attempts

@@ -16347,23 +16591,50 @@
       </para>
 
       <para>
-        Absence of a plugin may require adjustment to other options. For
+        Disabling a plugin may require adjustment to other options. For
         example, if <literal role="se">InnoDB</literal> is disabled,
         other <filename>innodb_<replaceable>xxx</replaceable></filename>
         options likely will need to be omitted from the startup command.
-        In addition, if the server would use
+        In addition, if the server is configured to use
         <literal role="se">InnoDB</literal> as the default storage
-        engine, it will not start unless you select another available
+        engine, it will not start unless you specify another available
         storage engine with
         <option role="mysqld">--default-storage-engine</option>.
       </para>
 
+      <bridgehead id="server-plugin-uninstalling">
+        Uninstalling Plugins
+      </bridgehead>
+
       <para>
-        Plugins can also be loaded at runtime, using the
-        <literal role="stmt">INSTALL PLUGIN</literal> statement. See
-        <xref linkend="plugin-installing-uninstalling"/>.
+        A plugin known to the server can be uninstalled to disable it at
+        runtime with the <literal role="stmt">UNINSTALL PLUGIN</literal>
+        statement. The statement unloads the plugin and removes it from
+        the <literal>mysql.plugin</literal> table if it is registered
+        there. For this reason, <literal role="stmt">UNINSTALL
+        PLUGIN</literal> statement requires the
+        <literal role="priv">DELETE</literal> privilege for the
+        <literal>mysql.plugin</literal> table. With the plugin no longer
+        registered in the table, the server will not load the plugin
+        automatically for subsequent restarts.
       </para>
 
+      <para>
+        <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
+        plugins regardless of whether they were loaded with
+        <literal role="stmt">INSTALL PLUGIN</literal> or
+        <option role="mysqld">--plugin-load</option>.
+      </para>
+
+      <para>
+        <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
+        plugins that are built in to the server. These can be identified
+        as those that have a library name of <literal>NULL</literal> in
+        the output from
+        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
+        <literal role="stmt">SHOW PLUGINS</literal>.
+      </para>
+
     </section>
 
     <section id="obtaining-plugin-information">


Modified: trunk/refman-6.0/extending-mysql.xml
===================================================================
--- trunk/refman-6.0/extending-mysql.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-6.0/extending-mysql.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 4, Lines Added: 5, Lines Deleted: 78; 4084 bytes

@@ -2455,79 +2455,6 @@
 
       </section>
 
-      <section id="registering-plugins">
-
-        <title>Registering Plugins with the Server</title>
-
-        <para>
-          Server plugins must be registered with the server before they
-          can be used. You can load a plugin at server startup with the
-          <option role="mysqld">plugin-load</option> option or at
-          runtime with the <literal role="stmt">INSTALL PLUGIN</literal>
-          statement.
-        </para>
-
-        <para>
-          The <option role="mysqld">plugin-load</option> option installs
-          a plugin at server startup. To install a plugin named
-          <literal>myplugin</literal> in a plugin library file named
-          <filename>somepluglib.so</filename>, use these lines in a
-          <filename>my.cnf</filename> file:
-        </para>
-
-<programlisting>
-[mysqld]
-plugin-load=myplugin=somepluglib.so
-</programlisting>
-
-        <para>
-          In this case, the plugin is not installed permanently.
-          Restarting without the
-          <option role="mysqld">plugin-load</option> option causes the
-          plugin not to be loaded at startup.
-        </para>
-
-        <para>
-          Alternatively, the <literal role="stmt">INSTALL
-          PLUGIN</literal> statement causes the server to register the
-          plugin and load the plugin code from the library file at
-          runtime:
-        </para>
-
-<programlisting>
-mysql&gt; <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
-</programlisting>
-
-        <para>
-          <literal role="stmt">INSTALL PLUGIN</literal> causes
-          <quote>permanent</quote> plugin registration: The server lists
-          the plugin in the <literal>mysql.plugin</literal> table to
-          ensure that it is loaded on subsequent server restarts.
-        </para>
-
-        <para>
-          Many plugins can be loaded either at server startup or at
-          runtime. However, if a plugin is designed such that it must be
-          loaded and initialized during server startup,
-          <literal role="stmt">INSTALL PLUGIN</literal> is not
-          appropriate and you must use
-          <option role="mysqld">plugin-load</option>.
-        </para>
-
-        <para>
-              To verify plugin installation, examine the
-          <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-          or use the <literal role="stmt">SHOW PLUGINS</literal>
-          statement.
-        </para>
-
-        <para>
-          For additional information about plugin loading, see
-          <xref linkend="plugin-installing-uninstalling"/>.
-        </para>
-
-      </section>
-
 <!--
       <section id="writing-storage-engine-plugins">
 

@@ -3299,9 +3226,9 @@
           <listitem>
             <para>
               To verify plugin installation, examine the
-          <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-          or use the <literal role="stmt">SHOW PLUGINS</literal>
-          statement.
+              <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+              table or use the <literal role="stmt">SHOW
+              PLUGINS</literal> statement.
             </para>
           </listitem>
 

@@ -3555,7 +3482,7 @@
         </para>
 
         <para>
-              To verify plugin installation, examine the
+          To verify plugin installation, examine the
           <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
           or use the <literal role="stmt">SHOW PLUGINS</literal>
           statement.

@@ -4129,7 +4056,7 @@
         </para>
 
         <para>
-              To verify plugin installation, examine the
+          To verify plugin installation, examine the
           <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
           or use the <literal role="stmt">SHOW PLUGINS</literal>
           statement.


Modified: trunk/refman-6.0/sql-syntax-server-administration.xml
===================================================================
--- trunk/refman-6.0/sql-syntax-server-administration.xml	2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-6.0/sql-syntax-server-administration.xml	2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 1, Lines Added: 0, Lines Deleted: 172; 6126 bytes

@@ -3516,178 +3516,6 @@
 
     <title>Plugin and User-Defined Function Statements</title>
 
-    <section id="plugin-installing-uninstalling">
-
-      <title>Installing and Uninstalling Plugins</title>
-
-      <indexterm>
-        <primary>installing plugins</primary>
-      </indexterm>
-
-      <indexterm>
-        <primary>plugins</primary>
-        <secondary>installing</secondary>
-      </indexterm>
-
-      <indexterm>
-        <primary>uninstalling plugins</primary>
-      </indexterm>
-
-      <indexterm>
-        <primary>plugins</primary>
-        <secondary>uninstalling</secondary>
-      </indexterm>
-
-      <para>
-        This section compares the various methods of installing and
-        uninstalling server plugins. See also
-        <xref linkend="server-plugin-options"/>.
-      </para>
-
-      <para>
-        <option role="mysqld">--plugin-load</option> option:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Loads the plugin code at server startup to enable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Does not register the plugin in
-            <literal>mysql.plugin</literal>. For subsequent restarts,
-            the server loads the plugin again only if
-            <option role="mysqld">--plugin-load</option> is given again.
-            That is, this option effects a one-time installation that
-            persists only for one server invocation.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        <literal role="stmt">INSTALL PLUGIN</literal> statement:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Loads the plugin code at runtime to enable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Registers the plugin in the <literal>mysql.plugin</literal>
-            table. Registration causes the server to load the plugin
-            automatically for subsequent restarts. That is, it effects
-            an installation that persists until the plugin is
-            uninstalled explicitly.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Requires the <literal role="priv">INSERT</literal> privilege
-            for the <literal>mysql.plugin</literal> table.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> statement:
-      </para>
-
-      <itemizedlist>
-
-        <listitem>
-          <para>
-            Unloads the plugin code at runtime to disable it.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Unregisters the plugin from <literal>mysql.plugin</literal>
-            if it is registered there. The server will not load it
-            automatically for subsequent restarts.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Requires the <literal role="priv">DELETE</literal> privilege
-            for the <literal>mysql.plugin</literal> table.
-          </para>
-        </listitem>
-
-      </itemizedlist>
-
-      <para>
-        While a plugin is loaded, information about it is available at
-        runtime from several sources, such as the
-        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
-        and the <literal role="stmt">SHOW PLUGINS</literal> statement.
-        For more information, see
-        <xref linkend="obtaining-plugin-information"/>.
-      </para>
-
-      <para>
-        If <option role="mysqld">--plugin-load</option> is given at
-        startup for a plugin already installed with
-        <literal role="stmt">INSTALL PLUGIN</literal> during a previous
-        server invocation, the server starts but writes these messages
-        to the error log:
-      </para>
-
-<programlisting>
-100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
-100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
-with soname '<replaceable>plugin_object_file</replaceable>'.
-</programlisting>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
-        plugins regardless of whether they were loaded with
-        <literal role="stmt">INSTALL PLUGIN</literal> or
-        <option role="mysqld">--plugin-load</option>. In the latter
-        case, <literal role="stmt">UNINSTALL PLUGIN</literal> does not
-        unregister the plugin from <literal>mysql.plugin</literal>
-        because <option role="mysqld">--plugin-load</option> did not
-        register it.
-      </para>
-
-      <para>
-        <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
-        plugins that are compiled into the server. (These can be
-        identified as those that have a library name of
-        <literal>NULL</literal> in the output from
-        <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
-        <literal role="stmt">SHOW PLUGINS</literal>.)
-      </para>
-
-      <para>
-        If the server is started with the
-        <option role="mysqld">--skip-grant-tables</option> option, it
-        does not consult the <literal>mysql.plugins</literal> table and
-        thus does not load plugins installed with the
-        <literal role="stmt">INSTALL PLUGIN</literal> statement.
-        <option role="mysqld">--plugin-load</option> enables plugins to
-        be loaded even when
-        <option role="mysqld">--skip-grant-tables</option> is given.
-        <option role="mysqld">--plugin-load</option> also enables
-        plugins to be loaded at startup under configurations when
-        plugins cannot be loaded at runtime.
-      </para>
-
-    </section>
-
     <section id="create-function-udf">
 
       <title><literal role="stmt">CREATE FUNCTION</literal> Syntax for User-Defined


Thread
svn commit - mysqldoc@oter02: r26574 - in trunk: . refman-5.1 refman-5.5 refman-5.6 refman-6.0paul.dubois22 Jun