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.0 | paul.dubois | 3 May |
