List:Commits« Previous MessageNext Message »
From:paul.dubois Date:May 3 2010 3:56pm
Subject:svn commit - mysqldoc@docsrva: r20393 - in trunk: . refman-5.5 refman-6.0
View as plain text  
Author: paul
Date: 2010-05-03 17:56:40 +0200 (Mon, 03 May 2010)
New Revision: 20393

Log:
 r58507@frost:  paul | 2010-05-03 10:55:50 -0500
 Audit plugin API tweaks


Modified:
   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:38723
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:58506
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:38723
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:58507
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/refman-5.5/extending-mysql.xml
===================================================================
--- trunk/refman-5.5/extending-mysql.xml	2010-05-03 15:56:34 UTC (rev 20392)
+++ trunk/refman-5.5/extending-mysql.xml	2010-05-03 15:56:40 UTC (rev 20393)
Changed blocks: 14, Lines Added: 51, Lines Deleted: 51; 9524 bytes

@@ -3064,8 +3064,13 @@
         </para>
 
         <para>
-          This description includes references to interface elements
-          that are present only as of MySQL 5.5.5:
+          This description includes references to audit plugin interface
+          elements that are present only as of MySQL 5.5.5. A plugin
+          that requires these elements must be compiled against MySQL
+          source for which the value of
+          <literal>MYSQL_AUDIT_INTERFACE_VERSION</literal>, the
+          type-specific interface version, is <literal>0x0200</literal>
+          or greater:
         </para>
 
         <itemizedlist>

@@ -3087,14 +3092,6 @@
         </itemizedlist>
 
         <para>
-          An audit plugin that requires those elements must be compiled
-          against source for which 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

@@ -3102,7 +3099,7 @@
           distributions. Additionally, a few other places in the server
           are modified to call the audit interface when an auditable
           event occurs, so that registered audit plugins can be notified
-          about the event if necessary. To see where these calls occur,
+          about the event if necessary. To see where such calls occur,
           look for invocations of functions with names of the form
           <filename>mysql_audit_<replaceable>xxx</replaceable>()</filename>.
           Audit notification occurs for these server operations:

@@ -3137,15 +3134,12 @@
         </para>
 
         <para>
-          On the plugin side, an audit plugin should use the interface
-          defined in <filename>plugin_audit.h</filename>, which includes
+          On the plugin side, an audit plugin uses the interface defined
+          in <filename>plugin_audit.h</filename>, which includes
           <filename>plugin.h</filename> for general plugin interface
           information. These include files are located in the
-          <filename>include/mysql</filename> directory.
-        </para>
-
-        <para>
-          The <filename>audit_null.c</filename> source file in the
+          <filename>include/mysql</filename> directory. The
+          <filename>audit_null.c</filename> source file in the
           <filename>plugin/audit_null</filename> directory implements a
           simple example audit plugin named
           <literal>NULL_AUDIT</literal>.

@@ -3217,17 +3211,14 @@
 </programlisting>
 
         <para>
-          The plugin increments the first variable for each notification
-          it receives. It increments the others according to the event
-          subclass. In effect, the first variable is the aggregate of
-          the counts for the element subclasses.
-        </para>
-
-        <para>
           The <literal>audit_null_plugin_init</literal> initialization
           function sets the status variables to zero when the plugin is
           loaded. The <literal>audit_null_plugin_deinit</literal>
-          function performs cleanup with the plugin is unloaded.
+          function performs cleanup with the plugin is unloaded. During
+          operation, the plugin increments the first variable for each
+          notification it receives. It increments the others according
+          to the event subclass. In effect, the first variable is the
+          aggregate of the counts for the event subclasses.
         </para>
 
         <para>

@@ -3246,7 +3237,7 @@
 </programlisting>
 
         <para>
-          The type-specific descriptor has these fields:
+          The type-specific descriptor has these members:
         </para>
 
         <itemizedlist>

@@ -3298,7 +3289,7 @@
           The server uses the <literal>event_notify</literal> and
           <literal>release_thd</literal> functions together. They are
           called within the context of a specific thread, and a thread
-          might engage in an activity that produces several event
+          might perform an activity that produces several event
           notifications. The first time the server calls
           <literal>event_notify</literal> for a thread, it creates a
           binding of the plugin to the thread. The plugin cannot be

@@ -3308,9 +3299,10 @@
           then destroys the binding. For example, when a client issues a
           statement, the thread processing the statement might notify
           audit plugins about the result set produced by the statement
-          and about the statement being logged. The notifications occur
-          and then the server releases the plugin before putting the
-          thread to sleep until the client issues another statement.
+          and about the statement being logged. After these
+          notifications occur, the server releases the plugin before
+          putting the thread to sleep until the client issues another
+          statement.
         </para>
 
         <para>

@@ -3375,21 +3367,28 @@
         <para>
           In the type-specific descriptor, the second parameter of the
           <literal>event_notify</literal> function prototype is a
-          generic <literal>mysql_event</literal> pointer, but the server
-          actually passes the notification function a pointer to a
-          structure that depends on the event class. The first member of
-          all event structures must indicate the event class to enable
-          the notification function to determine what kind of structure
-          it was passed so that it can tell what other structure members
-          exist.
+          generic <literal>mysql_event</literal> pointer:
         </para>
 
+<programlisting>
+void (*event_notify)(MYSQL_THD, const struct mysql_event *);
+</programlisting>
+
         <para>
-          Events in the <quote>general</quote> event class are passed to
-          the <literal>event_notify</literal> function using this
-          structure:
+          The server actually passes the notification function a pointer
+          to a structure that depends on the event class. The first
+          member of all event structures must indicate the event class
+          to enable the notification function to determine what kind of
+          structure it was passed so that it can tell what other
+          structure members exist.
         </para>
 
+        <para>
+          The server passes events in the <quote>general</quote> event
+          class to the <literal>event_notify</literal> function using
+          this structure:
+        </para>
+
 <programlisting>
 struct mysql_event_general
 {

@@ -3410,7 +3409,8 @@
 </programlisting>
 
         <para>
-          The structure members are used as follows:
+          Audit plugins can interpret
+          <literal>mysql_event_general</literal> members as follows:
         </para>
 
         <itemizedlist>

@@ -3438,11 +3438,10 @@
 
           <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
+              <literal>general_error_code</literal>: The error code.
+              This is a value like that returned by the
               <literal role="capi">mysql_errno()</literal> C API
-              function.
+              function; 0 means <quote>no error.</quote>
             </para>
           </listitem>
 

@@ -3473,10 +3472,10 @@
               events, the type of operation. Examples:
               <literal>Connect</literal>, <literal>Query</literal>,
               <literal>Shutdown</literal>. For error log events, the
-              error message (empty means <quote>no error</quote>). This
-              is a value like that returned by the
+              error message. This is a value like that returned by the
               <literal role="capi">mysql_error()</literal> C API
-              function. For result events, this is empty.
+              function; an empty string means <quote>no error.</quote>
+              For result events, this is empty.
             </para>
           </listitem>
 

@@ -3535,8 +3534,8 @@
         </itemizedlist>
 
         <para>
-          The example audit plugin is configured in and built by default
-          when you build MySQL from source. No special configuration
+          When you build MySQL from source, the example audit plugin is
+          configured in and built by default. No special configuration
           options are needed to cause it to be compiled. The build
           process produces a shared object library with a name of
           <filename>adt_null.so</filename> (the extension might be

@@ -3608,6 +3607,7 @@
           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
+          <literal>Audit_null_called</literal> and
           <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.


Modified: trunk/refman-6.0/extending-mysql.xml
===================================================================
--- trunk/refman-6.0/extending-mysql.xml	2010-05-03 15:56:34 UTC (rev 20392)
+++ trunk/refman-6.0/extending-mysql.xml	2010-05-03 15:56:40 UTC (rev 20393)
Changed blocks: 14, Lines Added: 51, Lines Deleted: 51; 9526 bytes

@@ -3101,8 +3101,13 @@
         </para>
 
         <para>
-          This description includes references to interface elements
-          that are present only as of MySQL 6.0.14:
+          This description includes references to audit plugin interface
+          elements that are present only as of MySQL 6.0.14. A plugin
+          that requires these elements must be compiled against MySQL
+          source for which the value of
+          <literal>MYSQL_AUDIT_INTERFACE_VERSION</literal>, the
+          type-specific interface version, is <literal>0x0200</literal>
+          or greater:
         </para>
 
         <itemizedlist>

@@ -3124,14 +3129,6 @@
         </itemizedlist>
 
         <para>
-          An audit plugin that requires those elements must be compiled
-          against source for which 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

@@ -3139,7 +3136,7 @@
           distributions. Additionally, a few other places in the server
           are modified to call the audit interface when an auditable
           event occurs, so that registered audit plugins can be notified
-          about the event if necessary. To see where these calls occur,
+          about the event if necessary. To see where such calls occur,
           look for invocations of functions with names of the form
           <filename>mysql_audit_<replaceable>xxx</replaceable>()</filename>.
           Audit notification occurs for these server operations:

@@ -3174,15 +3171,12 @@
         </para>
 
         <para>
-          On the plugin side, an audit plugin should use the interface
-          defined in <filename>plugin_audit.h</filename>, which includes
+          On the plugin side, an audit plugin uses the interface defined
+          in <filename>plugin_audit.h</filename>, which includes
           <filename>plugin.h</filename> for general plugin interface
           information. These include files are located in the
-          <filename>include/mysql</filename> directory.
-        </para>
-
-        <para>
-          The <filename>audit_null.c</filename> source file in the
+          <filename>include/mysql</filename> directory. The
+          <filename>audit_null.c</filename> source file in the
           <filename>plugin/audit_null</filename> directory implements a
           simple example audit plugin named
           <literal>NULL_AUDIT</literal>.

@@ -3254,17 +3248,14 @@
 </programlisting>
 
         <para>
-          The plugin increments the first variable for each notification
-          it receives. It increments the others according to the event
-          subclass. In effect, the first variable is the aggregate of
-          the counts for the element subclasses.
-        </para>
-
-        <para>
           The <literal>audit_null_plugin_init</literal> initialization
           function sets the status variables to zero when the plugin is
           loaded. The <literal>audit_null_plugin_deinit</literal>
-          function performs cleanup with the plugin is unloaded.
+          function performs cleanup with the plugin is unloaded. During
+          operation, the plugin increments the first variable for each
+          notification it receives. It increments the others according
+          to the event subclass. In effect, the first variable is the
+          aggregate of the counts for the event subclasses.
         </para>
 
         <para>

@@ -3283,7 +3274,7 @@
 </programlisting>
 
         <para>
-          The type-specific descriptor has these fields:
+          The type-specific descriptor has these members:
         </para>
 
         <itemizedlist>

@@ -3335,7 +3326,7 @@
           The server uses the <literal>event_notify</literal> and
           <literal>release_thd</literal> functions together. They are
           called within the context of a specific thread, and a thread
-          might engage in an activity that produces several event
+          might perform an activity that produces several event
           notifications. The first time the server calls
           <literal>event_notify</literal> for a thread, it creates a
           binding of the plugin to the thread. The plugin cannot be

@@ -3345,9 +3336,10 @@
           then destroys the binding. For example, when a client issues a
           statement, the thread processing the statement might notify
           audit plugins about the result set produced by the statement
-          and about the statement being logged. The notifications occur
-          and then the server releases the plugin before putting the
-          thread to sleep until the client issues another statement.
+          and about the statement being logged. After these
+          notifications occur, the server releases the plugin before
+          putting the thread to sleep until the client issues another
+          statement.
         </para>
 
         <para>

@@ -3412,21 +3404,28 @@
         <para>
           In the type-specific descriptor, the second parameter of the
           <literal>event_notify</literal> function prototype is a
-          generic <literal>mysql_event</literal> pointer, but the server
-          actually passes the notification function a pointer to a
-          structure that depends on the event class. The first member of
-          all event structures must indicate the event class to enable
-          the notification function to determine what kind of structure
-          it was passed so that it can tell what other structure members
-          exist.
+          generic <literal>mysql_event</literal> pointer:
         </para>
 
+<programlisting>
+void (*event_notify)(MYSQL_THD, const struct mysql_event *);
+</programlisting>
+
         <para>
-          Events in the <quote>general</quote> event class are passed to
-          the <literal>event_notify</literal> function using this
-          structure:
+          The server actually passes the notification function a pointer
+          to a structure that depends on the event class. The first
+          member of all event structures must indicate the event class
+          to enable the notification function to determine what kind of
+          structure it was passed so that it can tell what other
+          structure members exist.
         </para>
 
+        <para>
+          The server passes events in the <quote>general</quote> event
+          class to the <literal>event_notify</literal> function using
+          this structure:
+        </para>
+
 <programlisting>
 struct mysql_event_general
 {

@@ -3447,7 +3446,8 @@
 </programlisting>
 
         <para>
-          The structure members are used as follows:
+          Audit plugins can interpret
+          <literal>mysql_event_general</literal> members as follows:
         </para>
 
         <itemizedlist>

@@ -3475,11 +3475,10 @@
 
           <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
+              <literal>general_error_code</literal>: The error code.
+              This is a value like that returned by the
               <literal role="capi">mysql_errno()</literal> C API
-              function.
+              function; 0 means <quote>no error.</quote>
             </para>
           </listitem>
 

@@ -3510,10 +3509,10 @@
               events, the type of operation. Examples:
               <literal>Connect</literal>, <literal>Query</literal>,
               <literal>Shutdown</literal>. For error log events, the
-              error message (empty means <quote>no error</quote>). This
-              is a value like that returned by the
+              error message. This is a value like that returned by the
               <literal role="capi">mysql_error()</literal> C API
-              function. For result events, this is empty.
+              function; an empty string means <quote>no error.</quote>
+              For result events, this is empty.
             </para>
           </listitem>
 

@@ -3572,8 +3571,8 @@
         </itemizedlist>
 
         <para>
-          The example audit plugin is configured in and built by default
-          when you build MySQL from source. No special configuration
+          When you build MySQL from source, the example audit plugin is
+          configured in and built by default. No special configuration
           options are needed to cause it to be compiled. The build
           process produces a shared object library with a name of
           <filename>adt_null.so</filename> (the extension might be

@@ -3645,6 +3644,7 @@
           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
+          <literal>Audit_null_called</literal> and
           <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.


Thread
svn commit - mysqldoc@docsrva: r20393 - in trunk: . refman-5.5 refman-6.0paul.dubois3 May