MySQL Lists are EOL. Please join:

List:Commits« Previous MessageNext Message »
From:paul.dubois Date:April 30 2010 1:19am
Subject:svn commit - mysqldoc@docsrva: r20357 - in trunk: . dynamic-docs/changelog refman-5.5 refman-6.0
View as plain text  
Author: paul
Date: 2010-04-30 03:19:04 +0200 (Fri, 30 Apr 2010)
New Revision: 20357

Log:
 r58422@frost:  paul | 2010-04-29 20:15:51 -0500
 Document bug fix:
 Bug#47059: In audit plugin I cannot see the event subclasses, e.g.MYSQL_AUDIT_GENERAL_ERROR


Modified:
   trunk/dynamic-docs/changelog/mysqld-2.xml
   trunk/refman-5.5/extending-mysql.xml
   trunk/refman-6.0/extending-mysql.xml

Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - 07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/mysqldoc/trunk:35498
07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/trunk:38641
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:43968
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/trunk:44480
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:58420
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:39036
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/trunk:39546
   + 07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/mysqldoc/trunk:35498
07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/trunk:38641
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:43968
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/trunk:44480
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:58422
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:39036
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/trunk:39546


Modified: trunk/dynamic-docs/changelog/mysqld-2.xml
===================================================================
--- trunk/dynamic-docs/changelog/mysqld-2.xml	2010-04-29 23:57:59 UTC (rev 20356)
+++ trunk/dynamic-docs/changelog/mysqld-2.xml	2010-04-30 01:19:04 UTC (rev 20357)
Changed blocks: 1, Lines Added: 58, Lines Deleted: 0; 1926 bytes

@@ -12664,4 +12664,62 @@
 
   </logentry>
 
+  <logentry entrytype="bug">
+
+    <tags>
+      <manual type="plugins"/>
+    </tags>
+
+    <bugs>
+      <fixes bugid="47059"/>
+    </bugs>
+
+    <versions>
+      <version ver="5.5.5"/>
+      <version ver="6.0.14"/>
+    </versions>
+
+    <message>
+
+      <para>
+        For events of <literal>MYSQL_AUDIT_GENERAL_CLASS</literal>, the
+        event subtype was not passed to audit plugins even though the
+        server passed the subtype to the plugin handler. The subtype is
+        now available through the following changes:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            The <literal>struct mysql_event_general</literal> structure
+            has a new <literal>event_subtype</literal> member.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            The new member changes the interface, so the audit plugin
+            interface version,
+            <literal>MYSQL_AUDIT_INTERFACE_VERSION</literal>, has been
+            incremented from <literal>0x0100</literal> to
+            <literal>0x0200</literal>. Plugins that require access to
+            the new member should check that the version is
+            <literal>0x0200</literal> or higher.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        The example plugin in the <filename>plugin/audit_null</filename>
+        directory has been modified to count events of each subtype,
+        based on the <literal>event_subtype</literal> value. See
+        <xref linkend="writing-audit-plugins"/>.
+      </para>
+
+    </message>
+
+  </logentry>
+
 </changelog>


Modified: trunk/refman-5.5/extending-mysql.xml
===================================================================
--- trunk/refman-5.5/extending-mysql.xml	2010-04-29 23:57:59 UTC (rev 20356)
+++ trunk/refman-5.5/extending-mysql.xml	2010-04-30 01:19:04 UTC (rev 20357)
Changed blocks: 7, Lines Added: 92, Lines Deleted: 29; 7304 bytes

@@ -3064,6 +3064,37 @@
         <title>Writing Audit Plugins</title>
 
         <para>
+          This description includes references to interface elements
+          that are present only as of MySQL 5.5.5:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              The <literal>event_subtype</literal> member of
+              <literal>struct mysql_event_general</literal>
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Status variables that count calls for individual event
+              subtypes
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          An audit plugin that requires those elements should verify
+          that the value of
+          <literal>MYSQL_AUDIT_INTERFACE_VERSION</literal>, the
+          type-specific interface version, is <literal>0x0200</literal>
+          or greater.
+        </para>
+
+        <para>
           On the server side, the pluggable audit interface is
           implemented in the <filename>sql_audit.h</filename> and
           <filename>sql_audit.cc</filename> files in the

@@ -3151,8 +3182,8 @@
 </programlisting>
 
         <para>
-          The name field indicates the name
-          (<literal>NULL_AUDIT</literal>) that you use to refer to the
+          The <literal>name</literal> field indicates the name
+          (<literal>NULL_AUDIT</literal>) to use for references to the
           plugin in statements such as <literal role="stmt">INSTALL
           PLUGIN</literal> or <literal role="stmt">UNINSTALL
           PLUGIN</literal>. This is also the name displayed by

@@ -3168,27 +3199,41 @@
 
         <para>
           The general descriptor also refers to
-          <literal>simple_status</literal>, a structure that exposes a
-          status variable to the <literal role="stmt">SHOW
+          <literal>simple_status</literal>, a structure that exposes
+          status variables to the <literal role="stmt">SHOW
           STATUS</literal> statement:
         </para>
 
 <programlisting>
 static struct st_mysql_show_var simple_status[]=
 {
-  {"Audit_null_called", (char *)&amp;number_of_calls, SHOW_INT},
-  {0,0,0}
+  { "Audit_null_called", (char *) &amp;number_of_calls, SHOW_INT },
+  { "Audit_null_general_log", (char *) &amp;number_of_calls_general_log,
+    SHOW_INT },
+  { "Audit_null_general_error", (char *) &amp;number_of_calls_general_error,
+    SHOW_INT },
+  { "Audit_null_general_result", (char *) &amp;number_of_calls_general_result,
+    SHOW_INT },
+  { 0, 0, 0}
 };
 </programlisting>
 
         <para>
-          The <literal>audit_null_plugin_init</literal> initialization
-          function sets the status variable to zero when the plugin is
-          loaded. The <literal>audit_null_plugin_deinit</literal>
-          function performs cleanup with the plugin is unloaded.
+          The plugin increments the first variable for each notification
+          it receives. It increments the others according to the event
+          subtype. In efect, the first variable aggregates counts over
+          the element subtypes.
         </para>
 
         <para>
+          The status variables are set to zero in the
+          <literal>audit_null_plugin_init</literal> initialization
+          function when the plugin is loaded. The
+          <literal>audit_null_plugin_deinit</literal> function performs
+          cleanup with the plugin is unloaded.
+        </para>
+
+        <para>
           Audit plugins have a type-specific descriptor with this
           structure:
         </para>

@@ -3302,10 +3347,10 @@
 <programlisting>
 static struct st_mysql_audit audit_null_descriptor=
 {
-  MYSQL_AUDIT_INTERFACE_VERSION,    /* interface version      */
-  NULL,                             /* release_thd function   */
-  audit_null_notify,                /* notify function        */
-  { MYSQL_AUDIT_GENERAL_CLASSMASK } /* class mask             */
+  MYSQL_AUDIT_INTERFACE_VERSION,                    /* interface version    */
+  NULL,                                             /* release_thd function */
+  audit_null_notify,                                /* notify function      */
+  { (unsigned long) MYSQL_AUDIT_GENERAL_CLASSMASK } /* class mask           */
 };
 </programlisting>
 

@@ -3349,7 +3394,8 @@
 <programlisting>
 struct mysql_event_general
 {
-  int event_class;
+  unsigned int event_class;
+  unsigned int event_subclass;
   int general_error_code;
   unsigned long general_thread_id;
   const char *general_user;

@@ -3380,6 +3426,19 @@
 
           <listitem>
             <para>
+              <literal>event_subtype</literal>: The event subtype, one
+              of the following values:
+            </para>
+
+<programlisting>
+#define MYSQL_AUDIT_GENERAL_LOG 0
+#define MYSQL_AUDIT_GENERAL_ERROR 1
+#define MYSQL_AUDIT_GENERAL_RESULT 2
+</programlisting>
+          </listitem>
+
+          <listitem>
+            <para>
               <literal>general_error_code</literal>: The error code (0
               means <quote>no error</quote>). This is a value like that
               returned by the

@@ -3519,29 +3578,33 @@
         </para>
 
         <para>
-          While the audit plugin is installed, it exposes one status
-          variable that indicates how many times the plugin has been
-          called:
+          While the audit plugin is installed, it exposes status
+          variables that indicates how the plugin has been called:
         </para>
 
 <programlisting>
-mysql&gt; <userinput>SHOW STATUS LIKE 'Audit_null_called';</userinput>
-+-------------------+-------+
-| Variable_name     | Value |
-+-------------------+-------+
-| Audit_null_called | 2     |
-+-------------------+-------+
+mysql&gt; <userinput>SHOW STATUS LIKE 'Audit_null%';</userinput>
++---------------------------+-------+
+| Variable_name             | Value |
++---------------------------+-------+
+| Audit_null_called         | 2     |
+| Audit_null_general_error  | 0     |
+| Audit_null_general_log    | 1     |
+| Audit_null_general_result | 1     |
++---------------------------+-------+
 </programlisting>
 
         <para>
-          The status variable counts all events for any subtype of the
-          <quote>general</quote> class. The preceding
+          <literal>Audit_null_called</literal> counts all events for any
+          subtype of the <quote>general</quote> class, and the others
+          count instances of each event subtype. The preceding
           <literal role="stmt">SHOW STATUS</literal> statement causes
           the server to send a result to the client and to write a
           message to the general query log if that log is enabled. Thus,
-          a client that issues the statement repeatedly causes the
-          counter to be incremented by 1 or 2 depending on whether the
-          log is enabled.
+          a client that issues the statement repeatedly causes
+          <literal>Audit_null_general_result</literal> to be incremented
+          each time and <literal>Audit_null_general_log</literal> to be
+          incremented if the log is enabled.
         </para>
 
       </section>


Modified: trunk/refman-6.0/extending-mysql.xml
===================================================================
--- trunk/refman-6.0/extending-mysql.xml	2010-04-29 23:57:59 UTC (rev 20356)
+++ trunk/refman-6.0/extending-mysql.xml	2010-04-30 01:19:04 UTC (rev 20357)
Changed blocks: 7, Lines Added: 92, Lines Deleted: 29; 7305 bytes

@@ -3101,6 +3101,37 @@
         <title>Writing Audit Plugins</title>
 
         <para>
+          This description includes references to interface elements
+          that are present only as of MySQL 6.0.14:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              The <literal>event_subtype</literal> member of
+              <literal>struct mysql_event_general</literal>
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Status variables that count calls for individual event
+              subtypes
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          An audit plugin that requires those elements should verify
+          that the value of
+          <literal>MYSQL_AUDIT_INTERFACE_VERSION</literal>, the
+          type-specific interface version, is <literal>0x0200</literal>
+          or greater.
+        </para>
+
+        <para>
           On the server side, the pluggable audit interface is
           implemented in the <filename>sql_audit.h</filename> and
           <filename>sql_audit.cc</filename> files in the

@@ -3188,8 +3219,8 @@
 </programlisting>
 
         <para>
-          The name field indicates the name
-          (<literal>NULL_AUDIT</literal>) that you use to refer to the
+          The <literal>name</literal> field indicates the name
+          (<literal>NULL_AUDIT</literal>) to use for references to the
           plugin in statements such as <literal role="stmt">INSTALL
           PLUGIN</literal> or <literal role="stmt">UNINSTALL
           PLUGIN</literal>. This is also the name displayed by

@@ -3205,27 +3236,41 @@
 
         <para>
           The general descriptor also refers to
-          <literal>simple_status</literal>, a structure that exposes a
-          status variable to the <literal role="stmt">SHOW
+          <literal>simple_status</literal>, a structure that exposes
+          status variables to the <literal role="stmt">SHOW
           STATUS</literal> statement:
         </para>
 
 <programlisting>
 static struct st_mysql_show_var simple_status[]=
 {
-  {"Audit_null_called", (char *)&amp;number_of_calls, SHOW_INT},
-  {0,0,0}
+  { "Audit_null_called", (char *) &amp;number_of_calls, SHOW_INT },
+  { "Audit_null_general_log", (char *) &amp;number_of_calls_general_log,
+    SHOW_INT },
+  { "Audit_null_general_error", (char *) &amp;number_of_calls_general_error,
+    SHOW_INT },
+  { "Audit_null_general_result", (char *) &amp;number_of_calls_general_result,
+    SHOW_INT },
+  { 0, 0, 0}
 };
 </programlisting>
 
         <para>
-          The <literal>audit_null_plugin_init</literal> initialization
-          function sets the status variable to zero when the plugin is
-          loaded. The <literal>audit_null_plugin_deinit</literal>
-          function performs cleanup with the plugin is unloaded.
+          The plugin increments the first variable for each notification
+          it receives. It increments the others according to the event
+          subtype. In efect, the first variable aggregates counts over
+          the element subtypes.
         </para>
 
         <para>
+          The status variables are set to zero in the
+          <literal>audit_null_plugin_init</literal> initialization
+          function when the plugin is loaded. The
+          <literal>audit_null_plugin_deinit</literal> function performs
+          cleanup with the plugin is unloaded.
+        </para>
+
+        <para>
           Audit plugins have a type-specific descriptor with this
           structure:
         </para>

@@ -3339,10 +3384,10 @@
 <programlisting>
 static struct st_mysql_audit audit_null_descriptor=
 {
-  MYSQL_AUDIT_INTERFACE_VERSION,    /* interface version      */
-  NULL,                             /* release_thd function   */
-  audit_null_notify,                /* notify function        */
-  { MYSQL_AUDIT_GENERAL_CLASSMASK } /* class mask             */
+  MYSQL_AUDIT_INTERFACE_VERSION,                    /* interface version    */
+  NULL,                                             /* release_thd function */
+  audit_null_notify,                                /* notify function      */
+  { (unsigned long) MYSQL_AUDIT_GENERAL_CLASSMASK } /* class mask           */
 };
 </programlisting>
 

@@ -3386,7 +3431,8 @@
 <programlisting>
 struct mysql_event_general
 {
-  int event_class;
+  unsigned int event_class;
+  unsigned int event_subclass;
   int general_error_code;
   unsigned long general_thread_id;
   const char *general_user;

@@ -3417,6 +3463,19 @@
 
           <listitem>
             <para>
+              <literal>event_subtype</literal>: The event subtype, one
+              of the following values:
+            </para>
+
+<programlisting>
+#define MYSQL_AUDIT_GENERAL_LOG 0
+#define MYSQL_AUDIT_GENERAL_ERROR 1
+#define MYSQL_AUDIT_GENERAL_RESULT 2
+</programlisting>
+          </listitem>
+
+          <listitem>
+            <para>
               <literal>general_error_code</literal>: The error code (0
               means <quote>no error</quote>). This is a value like that
               returned by the

@@ -3556,29 +3615,33 @@
         </para>
 
         <para>
-          While the audit plugin is installed, it exposes one status
-          variable that indicates how many times the plugin has been
-          called:
+          While the audit plugin is installed, it exposes status
+          variables that indicates how the plugin has been called:
         </para>
 
 <programlisting>
-mysql&gt; <userinput>SHOW STATUS LIKE 'Audit_null_called';</userinput>
-+-------------------+-------+
-| Variable_name     | Value |
-+-------------------+-------+
-| Audit_null_called | 2     |
-+-------------------+-------+
+mysql&gt; <userinput>SHOW STATUS LIKE 'Audit_null%';</userinput>
++---------------------------+-------+
+| Variable_name             | Value |
++---------------------------+-------+
+| Audit_null_called         | 2     |
+| Audit_null_general_error  | 0     |
+| Audit_null_general_log    | 1     |
+| Audit_null_general_result | 1     |
++---------------------------+-------+
 </programlisting>
 
         <para>
-          The status variable counts all events for any subtype of the
-          <quote>general</quote> class. The preceding
+          <literal>Audit_null_called</literal> counts all events for any
+          subtype of the <quote>general</quote> class, and the others
+          count instances of each event subtype. The preceding
           <literal role="stmt">SHOW STATUS</literal> statement causes
           the server to send a result to the client and to write a
           message to the general query log if that log is enabled. Thus,
-          a client that issues the statement repeatedly causes the
-          counter to be incremented by 1 or 2 depending on whether the
-          log is enabled.
+          a client that issues the statement repeatedly causes
+          <literal>Audit_null_general_result</literal> to be incremented
+          each time and <literal>Audit_null_general_log</literal> to be
+          incremented if the log is enabled.
         </para>
 
       </section>


Thread
svn commit - mysqldoc@docsrva: r20357 - in trunk: . dynamic-docs/changelog refman-5.5 refman-6.0paul.dubois30 Apr