List:Commits« Previous MessageNext Message »
From:paul Date:January 28 2006 11:42pm
Subject:svn commit - mysqldoc@docsrva: r1088 - in trunk: . refman-4.1 refman-5.0 refman-5.1
View as plain text  
Author: paul
Date: 2006-01-29 00:42:15 +0100 (Sun, 29 Jan 2006)
New Revision: 1088

Log:
 r6827@frost:  paul | 2006-01-28 16:13:21 -0600
 General revisions.


Modified:
   trunk/
   trunk/refman-4.1/database-administration.xml
   trunk/refman-5.0/database-administration.xml
   trunk/refman-5.1/database-administration.xml


Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6826
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2588
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6827
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2588

Modified: trunk/refman-4.1/database-administration.xml
===================================================================
--- trunk/refman-4.1/database-administration.xml	2006-01-28 23:41:44 UTC (rev 1087)
+++ trunk/refman-4.1/database-administration.xml	2006-01-28 23:42:15 UTC (rev 1088)
@@ -11997,8 +11997,8 @@
         accepts or rejects the connection based on your identity and
         whether you can verify your identity by supplying the correct
         password. If not, the server denies access to you completely.
-        Otherwise, the server accepts the connection, then enters Stage
-        2 and waits for requests.
+        Otherwise, the server accepts the connection, and then enters
+        Stage 2 and waits for requests.
       </para>
 
       <para>
@@ -12028,7 +12028,7 @@
         <literal>Password</literal>). The server accepts the connection
         only if the <literal>Host</literal> and <literal>User</literal>
         columns in some <literal>user</literal> table row match the
-        client hostname and username, and the client supplies the
+        client hostname and username and the client supplies the
         password specified in that row.
       </para>
 
@@ -12106,25 +12106,47 @@
 
           <para>
             IP numbers that satisfy this condition and can connect to
-            the MySQL server are those that lie in the range from
+            the MySQL server are those in the range from
             <literal>192.58.197.0</literal> to
             <literal>192.58.197.255</literal>.
           </para>
-        </listitem>
 
-        <listitem>
           <para>
             Note: The netmask can only be used to tell the server to use
-            8, 16, 24, or 32 bits of the address, for example:
+            8, 16, 24, or 32 bits of the address. Examples:
           </para>
 
-<programlisting>
-192.0.0.0/255.0.0.0 (anything on the 192 class A network)
-192.168.0.0/255.255.0.0 (anything on the 192.168 class B network)
-192.168.1.0/255.255.255.0 (anything on the 192.168.1 class C network)
-192.168.1.1 (only this specific IP) 
-</programlisting>
+          <itemizedlist>
 
+            <listitem>
+              <para>
+                <literal>192.0.0.0/255.0.0.0</literal>: anything on the
+                192 class A network
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>192.168.0.0/255.255.0.0</literal>: anything on
+                the 192.168 class B network
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>192.168.1.0/255.255.255.0</literal>: anything
+                on the 192.168.1 class C network
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>192.168.1.1</literal>: only this specific IP
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
           <para>
             The following netmask (28 bits) will not work:
           </para>
@@ -12141,9 +12163,9 @@
             should be combined with those in the row in the
             <literal>host</literal> table that matches the client
             hostname. The privileges are combined using an AND
-            (intersection) operation, not OR (union). You can find more
-            information about the <literal>host</literal> table in
-            <xref linkend="request-access"/>.
+            (intersection) operation, not OR (union).
+            <xref linkend="request-access"/>, discusses use of the
+            <literal>host</literal> table further.
           </para>
 
           <para>
@@ -12218,9 +12240,9 @@
       </para>
 
       <para>
-        The following examples show how various combinations of
+        The following table shows how various combinations of
         <literal>Host</literal> and <literal>User</literal> values in
-        the <literal>user</literal> table apply to incoming connections:
+        the <literal>user</literal> table apply to incoming connections.
       </para>
 
       <informaltable>
@@ -12232,7 +12254,7 @@
             <row>
               <entry><literal>Host</literal> <emphasis role="bold">Value</emphasis></entry>
               <entry><literal>User</literal> <emphasis role="bold">Value</emphasis></entry>
-              <entry><emphasis role="bold">Connections Matched by Entry</emphasis></entry>
+              <entry><emphasis role="bold">Allowable Connections</emphasis></entry>
             </row>
             <row>
               <entry><literal>'thomas.loc.gov'</literal></entry>
@@ -12266,7 +12288,7 @@
               <entry><literal>'fred'</literal></entry>
               <entry><literal>fred</literal>, connecting from <literal>x.y.net</literal>,
                 <literal>x.y.com</literal>, <literal>x.y.edu</literal>,
-                and so on. (this is probably not useful)</entry>
+                and so on (this is probably not useful)</entry>
             </row>
             <row>
               <entry><literal>'144.155.166.177'</literal></entry>
@@ -12308,14 +12330,14 @@
         <listitem>
           <para>
             Whenever the server reads the <literal>user</literal> table
-            into memory, it sorts the entries.
+            into memory, it sorts the rows.
           </para>
         </listitem>
 
         <listitem>
           <para>
             When a client attempts to connect, the server looks through
-            the entries in sorted order.
+            the rows in sorted order.
           </para>
         </listitem>
 
@@ -12345,11 +12367,11 @@
 </programlisting>
 
       <para>
-        When the server reads in the table, it orders the entries with
-        the most-specific <literal>Host</literal> values first. Literal
-        hostnames and IP numbers are the most specific. The pattern
-        <literal>'%'</literal> means <quote>any host</quote> and is
-        least specific. Entries with the same <literal>Host</literal>
+        When the server reads the table into memory, it orders the rows
+        with the most-specific <literal>Host</literal> values first.
+        Literal hostnames and IP numbers are the most specific. The
+        pattern <literal>'%'</literal> means <quote>any host</quote> and
+        is least specific. Rows with the same <literal>Host</literal>
         value are ordered with the most-specific <literal>User</literal>
         values first (a blank <literal>User</literal> value means
         <quote>any user</quote> and is least specific). For the
@@ -12385,9 +12407,9 @@
 
       <para>
         When a client attempts to connect, the server looks through the
-        sorted entries and uses the first match found. For a connection
+        sorted rows and uses the first match found. For a connection
         from <literal>localhost</literal> by <literal>jeffrey</literal>,
-        two of the entries in the table match: the one with
+        two of the rows from the table match: the one with
         <literal>Host</literal> and <literal>User</literal> values of
         <literal>'localhost'</literal> and <literal>''</literal>, and
         the one with values of <literal>'%'</literal> and
@@ -12432,16 +12454,16 @@
 
       <para>
         It is a common misconception to think that, for a given
-        username, all entries that explicitly name that user are used
-        first when the server attempts to find a match for the
-        connection. This is simply not true. The previous example
-        illustrates this, where a connection from
-        <literal>thomas.loc.gov</literal> by <literal>jeffrey</literal>
-        is first matched not by the row containing
-        <literal>'jeffrey'</literal> as the <literal>User</literal>
-        column value, but by the row with no username. As a result,
-        <literal>jeffrey</literal> is authenticated as an anonymous
-        user, even though he specified a username when connecting.
+        username, all rows that explicitly name that user are used first
+        when the server attempts to find a match for the connection.
+        This is simply not true. The previous example illustrates this,
+        where a connection from <literal>thomas.loc.gov</literal> by
+        <literal>jeffrey</literal> is first matched not by the row
+        containing <literal>'jeffrey'</literal> as the
+        <literal>User</literal> column value, but by the row with no
+        username. As a result, <literal>jeffrey</literal> is
+        authenticated as an anonymous user, even though he specified a
+        username when connecting.
       </para>
 
       <para>
@@ -12449,7 +12471,8 @@
         are not what you expect, you probably are being authenticated as
         some other account. To find out what account the server used to
         authenticate you, use the <literal>CURRENT_USER()</literal>
-        function. It returns a value in
+        function. (See <xref linkend="information-functions"/>.) It
+        returns a value in
         <literal><replaceable>user_name</replaceable>@<replaceable>host_name</replaceable></literal>
         format that indicates the <literal>User</literal> and
         <literal>Host</literal> values from the matching
@@ -12489,8 +12512,8 @@
       <title>&title-request-access;</title>
 
       <para>
-        Once you establish a connection, the server enters Stage 2 of
-        access control. For each request that comes in on the
+        After you establish a connection, the server enters Stage 2 of
+        access control. For each request that you issue via that
         connection, the server determines what operation you want to
         perform, then checks whether you have sufficient privileges to
         do so. This is where the privilege columns in the grant tables
@@ -12512,7 +12535,7 @@
         <literal>user</literal> table privileges are superuser
         privileges. It is wise to grant privileges in the
         <literal>user</literal> table only to superusers such as
-        database administrators. For other users, you should leave the
+        database administrators. For other users, you should leave all
         privileges in the <literal>user</literal> table set to
         <literal>'N'</literal> and grant privileges at more specific
         levels only. You can grant privileges for particular databases,
@@ -12615,10 +12638,10 @@
       </indexterm>
 
       <para>
-        The server reads in and sorts the <literal>db</literal> and
-        <literal>host</literal> tables at the same time that it reads
-        the <literal>user</literal> table. The server sorts the
-        <literal>db</literal> table based on the
+        The server reads the <literal>db</literal> and
+        <literal>host</literal> tables into memory and sorts them at the
+        same time that it reads the <literal>user</literal> table. The
+        server sorts the <literal>db</literal> table based on the
         <literal>Host</literal>, <literal>Db</literal>, and
         <literal>User</literal> scope columns, and sorts the
         <literal>host</literal> table based on the
@@ -12639,11 +12662,16 @@
         <secondary>in <literal>mysql.columns_priv</literal> table</secondary>
       </indexterm>
 
+      <indexterm>
+        <primary>wildcards</primary>
+        <secondary>in <literal>mysql.procs_priv</literal> table</secondary>
+      </indexterm>
+
       <para>
         The <literal>tables_priv</literal> and
         <literal>columns_priv</literal> tables grant table-specific and
         column-specific privileges. Values in the scope columns of these
-        tables can take the following form:
+        tables can take the following forms:
       </para>
 
       <itemizedlist>
@@ -12652,16 +12680,16 @@
           <para>
             The wildcard characters &lsquo;<literal>%</literal>&rsquo;
             and &lsquo;<literal>_</literal>&rsquo; can be used in the
-            <literal>Host</literal> column of either table. These have
-            the same meaning as for pattern-matching operations
-            performed with the <literal>LIKE</literal> operator.
+            <literal>Host</literal> column. These have the same meaning
+            as for pattern-matching operations performed with the
+            <literal>LIKE</literal> operator.
           </para>
         </listitem>
 
         <listitem>
           <para>
             A <literal>'%'</literal> or blank <literal>Host</literal>
-            value in either table means <quote>any host.</quote>
+            value means <quote>any host.</quote>
           </para>
         </listitem>
 
@@ -12669,7 +12697,7 @@
           <para>
             The <literal>Db</literal>, <literal>Table_name</literal>,
             and <literal>Column_name</literal> columns cannot contain
-            wildcards or be blank in either table.
+            wildcards or be blank.
           </para>
         </listitem>
 
@@ -12685,20 +12713,14 @@
       </para>
 
       <para>
-        The request verification process is described here. (If you are
-        familiar with the access-checking source code, you may notice
-        that the description here differs slightly from the algorithm
-        used in the code. The description is equivalent to what the code
-        actually does; it differs only to make the explanation simpler.)
-      </para>
-
-      <para>
-        For requests that require administrative privileges such as
-        <literal>SHUTDOWN</literal> or <literal>RELOAD</literal>, the
-        server checks only the <literal>user</literal> table row because
-        that is the only table that specifies administrative privileges.
-        Access is granted if the row allows the requested operation and
-        denied otherwise. For example, if you want to execute
+        The server uses the sorted tables to verify each request that it
+        receives. For requests that require administrative privileges
+        such as <literal>SHUTDOWN</literal> or
+        <literal>RELOAD</literal>, the server checks only the
+        <literal>user</literal> table row because that is the only table
+        that specifies administrative privileges. The server grants
+        access if the row allows the requested operation and denies
+        access otherwise. For example, if you want to execute
         <command>mysqladmin shutdown</command> but your
         <literal>user</literal> table row does not grant the
         <literal>SHUTDOWN</literal> privilege to you, the server denies
@@ -12868,10 +12890,10 @@
       </indexterm>
 
       <para>
-        Naturally, you should always test your entries in the grant
-        tables (for example, by using <literal>SHOW GRANTS</literal> or
-        <command>mysqlaccess</command>) to make sure that your access
-        privileges are actually set up the way you think they are.
+        Naturally, you should always test your changes to the grant
+        tables (for example, by using <literal>SHOW GRANTS</literal>) to
+        make sure that your access privileges are actually set up the
+        way you think they are.
       </para>
 
     </section>

Modified: trunk/refman-5.0/database-administration.xml
===================================================================
--- trunk/refman-5.0/database-administration.xml	2006-01-28 23:41:44 UTC (rev 1087)
+++ trunk/refman-5.0/database-administration.xml	2006-01-28 23:42:15 UTC (rev 1088)
@@ -14135,8 +14135,8 @@
         accepts or rejects the connection based on your identity and
         whether you can verify your identity by supplying the correct
         password. If not, the server denies access to you completely.
-        Otherwise, the server accepts the connection, then enters Stage
-        2 and waits for requests.
+        Otherwise, the server accepts the connection, and then enters
+        Stage 2 and waits for requests.
       </para>
 
       <para>
@@ -14166,7 +14166,7 @@
         <literal>Password</literal>). The server accepts the connection
         only if the <literal>Host</literal> and <literal>User</literal>
         columns in some <literal>user</literal> table row match the
-        client hostname and username, and the client supplies the
+        client hostname and username and the client supplies the
         password specified in that row.
       </para>
 
@@ -14243,25 +14243,47 @@
 
           <para>
             IP numbers that satisfy this condition and can connect to
-            the MySQL server are those that lie in the range from
+            the MySQL server are those in the range from
             <literal>192.58.197.0</literal> to
             <literal>192.58.197.255</literal>.
           </para>
-        </listitem>
 
-        <listitem>
           <para>
             Note: The netmask can only be used to tell the server to use
-            8, 16, 24, or 32 bits of the address, for example:
+            8, 16, 24, or 32 bits of the address. Examples:
           </para>
 
-<programlisting>
-192.0.0.0/255.0.0.0 (anything on the 192 class A network)
-192.168.0.0/255.255.0.0 (anything on the 192.168 class B network)
-192.168.1.0/255.255.255.0 (anything on the 192.168.1 class C network)
-192.168.1.1 (only this specific IP) 
-</programlisting>
+          <itemizedlist>
 
+            <listitem>
+              <para>
+                <literal>192.0.0.0/255.0.0.0</literal>: anything on the
+                192 class A network
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>192.168.0.0/255.255.0.0</literal>: anything on
+                the 192.168 class B network
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>192.168.1.0/255.255.255.0</literal>: anything
+                on the 192.168.1 class C network
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>192.168.1.1</literal>: only this specific IP
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
           <para>
             The following netmask (28 bits) will not work:
           </para>
@@ -14278,9 +14300,9 @@
             should be combined with those in the row in the
             <literal>host</literal> table that matches the client
             hostname. The privileges are combined using an AND
-            (intersection) operation, not OR (union). You can find more
-            information about the <literal>host</literal> table in
-            <xref linkend="request-access"/>.
+            (intersection) operation, not OR (union).
+            <xref linkend="request-access"/>, discusses use of the
+            <literal>host</literal> table further.
           </para>
 
           <para>
@@ -14339,10 +14361,10 @@
         connection process when checking whether the password is
         correct. (This is done without the encrypted password ever
         traveling over the connection.) From MySQL's point of view, the
-        encrypted password is the REAL password, so you should not give
-        anyone access to it! In particular, don't give
-        non-administrative users read access to the tables in the
-        <literal>mysql</literal> database!
+        encrypted password is the <emphasis>real</emphasis> password, so
+        you should never give anyone access to it. In particular,
+        <emphasis>do not give non-administrative users read access to
+        tables in the <literal>mysql</literal> database</emphasis>.
       </para>
 
       <para>
@@ -14356,9 +14378,9 @@
       </para>
 
       <para>
-        The following examples show how various combinations of
+        The following table shows how various combinations of
         <literal>Host</literal> and <literal>User</literal> values in
-        the <literal>user</literal> table apply to incoming connections:
+        the <literal>user</literal> table apply to incoming connections.
       </para>
 
       <informaltable>
@@ -14370,7 +14392,7 @@
             <row>
               <entry><literal>Host</literal> <emphasis role="bold">Value</emphasis></entry>
               <entry><literal>User</literal> <emphasis role="bold">Value</emphasis></entry>
-              <entry><emphasis role="bold">Connections Matched by Entry</emphasis></entry>
+              <entry><emphasis role="bold">Allowable Connections</emphasis></entry>
             </row>
             <row>
               <entry><literal>'thomas.loc.gov'</literal></entry>
@@ -14404,7 +14426,7 @@
               <entry><literal>'fred'</literal></entry>
               <entry><literal>fred</literal>, connecting from <literal>x.y.net</literal>,
                 <literal>x.y.com</literal>, <literal>x.y.edu</literal>,
-                and so on. (this is probably not useful)</entry>
+                and so on (this is probably not useful)</entry>
             </row>
             <row>
               <entry><literal>'144.155.166.177'</literal></entry>
@@ -14446,14 +14468,14 @@
         <listitem>
           <para>
             Whenever the server reads the <literal>user</literal> table
-            into memory, it sorts the entries.
+            into memory, it sorts the rows.
           </para>
         </listitem>
 
         <listitem>
           <para>
             When a client attempts to connect, the server looks through
-            the entries in sorted order.
+            the rows in sorted order.
           </para>
         </listitem>
 
@@ -14483,11 +14505,11 @@
 </programlisting>
 
       <para>
-        When the server reads in the table, it orders the entries with
-        the most-specific <literal>Host</literal> values first. Literal
-        hostnames and IP numbers are the most specific. The pattern
-        <literal>'%'</literal> means <quote>any host</quote> and is
-        least specific. Entries with the same <literal>Host</literal>
+        When the server reads the table into memory, it orders the rows
+        with the most-specific <literal>Host</literal> values first.
+        Literal hostnames and IP numbers are the most specific. The
+        pattern <literal>'%'</literal> means <quote>any host</quote> and
+        is least specific. Rows with the same <literal>Host</literal>
         value are ordered with the most-specific <literal>User</literal>
         values first (a blank <literal>User</literal> value means
         <quote>any user</quote> and is least specific). For the
@@ -14523,9 +14545,9 @@
 
       <para>
         When a client attempts to connect, the server looks through the
-        sorted entries and uses the first match found. For a connection
+        sorted rows and uses the first match found. For a connection
         from <literal>localhost</literal> by <literal>jeffrey</literal>,
-        two of the entries in the table match: the one with
+        two of the rows from the table match: the one with
         <literal>Host</literal> and <literal>User</literal> values of
         <literal>'localhost'</literal> and <literal>''</literal>, and
         the one with values of <literal>'%'</literal> and
@@ -14570,16 +14592,16 @@
 
       <para>
         It is a common misconception to think that, for a given
-        username, all entries that explicitly name that user are used
-        first when the server attempts to find a match for the
-        connection. This is simply not true. The previous example
-        illustrates this, where a connection from
-        <literal>thomas.loc.gov</literal> by <literal>jeffrey</literal>
-        is first matched not by the row containing
-        <literal>'jeffrey'</literal> as the <literal>User</literal>
-        column value, but by the row with no username. As a result,
-        <literal>jeffrey</literal> is authenticated as an anonymous
-        user, even though he specified a username when connecting.
+        username, all rows that explicitly name that user are used first
+        when the server attempts to find a match for the connection.
+        This is simply not true. The previous example illustrates this,
+        where a connection from <literal>thomas.loc.gov</literal> by
+        <literal>jeffrey</literal> is first matched not by the row
+        containing <literal>'jeffrey'</literal> as the
+        <literal>User</literal> column value, but by the row with no
+        username. As a result, <literal>jeffrey</literal> is
+        authenticated as an anonymous user, even though he specified a
+        username when connecting.
       </para>
 
       <para>
@@ -14587,7 +14609,8 @@
         are not what you expect, you probably are being authenticated as
         some other account. To find out what account the server used to
         authenticate you, use the <literal>CURRENT_USER()</literal>
-        function. It returns a value in
+        function. (See <xref linkend="information-functions"/>.) It
+        returns a value in
         <literal><replaceable>user_name</replaceable>@<replaceable>host_name</replaceable></literal>
         format that indicates the <literal>User</literal> and
         <literal>Host</literal> values from the matching
@@ -14615,8 +14638,7 @@
       <para>
         Another thing you can do to diagnose authentication problems is
         to print out the <literal>user</literal> table and sort it by
-        hand to see where the first match is being made. See also
-        <xref linkend="information-functions"/>.
+        hand to see where the first match is being made.
       </para>
 
     </section>
@@ -14626,8 +14648,8 @@
       <title>&title-request-access;</title>
 
       <para>
-        Once you establish a connection, the server enters Stage 2 of
-        access control. For each request that comes in on the
+        After you establish a connection, the server enters Stage 2 of
+        access control. For each request that you issue via that
         connection, the server determines what operation you want to
         perform, then checks whether you have sufficient privileges to
         do so. This is where the privilege columns in the grant tables
@@ -14650,7 +14672,7 @@
         <literal>user</literal> table privileges are superuser
         privileges. It is wise to grant privileges in the
         <literal>user</literal> table only to superusers such as
-        database administrators. For other users, you should leave the
+        database administrators. For other users, you should leave all
         privileges in the <literal>user</literal> table set to
         <literal>'N'</literal> and grant privileges at more specific
         levels only. You can grant privileges for particular databases,
@@ -14753,10 +14775,10 @@
       </indexterm>
 
       <para>
-        The server reads in and sorts the <literal>db</literal> and
-        <literal>host</literal> tables at the same time that it reads
-        the <literal>user</literal> table. The server sorts the
-        <literal>db</literal> table based on the
+        The server reads the <literal>db</literal> and
+        <literal>host</literal> tables into memory and sorts them at the
+        same time that it reads the <literal>user</literal> table. The
+        server sorts the <literal>db</literal> table based on the
         <literal>Host</literal>, <literal>Db</literal>, and
         <literal>User</literal> scope columns, and sorts the
         <literal>host</literal> table based on the
@@ -14777,6 +14799,11 @@
         <secondary>in <literal>mysql.columns_priv</literal> table</secondary>
       </indexterm>
 
+      <indexterm>
+        <primary>wildcards</primary>
+        <secondary>in <literal>mysql.procs_priv</literal> table</secondary>
+      </indexterm>
+
       <para>
         The <literal>tables_priv</literal>
         <literal>columns_priv</literal>, and
@@ -14791,16 +14818,16 @@
           <para>
             The wildcard characters &lsquo;<literal>%</literal>&rsquo;
             and &lsquo;<literal>_</literal>&rsquo; can be used in the
-            <literal>Host</literal> column of either table. These have
-            the same meaning as for pattern-matching operations
-            performed with the <literal>LIKE</literal> operator.
+            <literal>Host</literal> column. These have the same meaning
+            as for pattern-matching operations performed with the
+            <literal>LIKE</literal> operator.
           </para>
         </listitem>
 
         <listitem>
           <para>
             A <literal>'%'</literal> or blank <literal>Host</literal>
-            value in either table means <quote>any host.</quote>
+            value means <quote>any host.</quote>
           </para>
         </listitem>
 
@@ -14808,7 +14835,7 @@
           <para>
             The <literal>Db</literal>, <literal>Table_name</literal>,
             and <literal>Column_name</literal> columns cannot contain
-            wildcards or be blank in either table.
+            wildcards or be blank.
           </para>
         </listitem>
 
@@ -14825,20 +14852,14 @@
       </para>
 
       <para>
-        The request verification process is described here. (If you are
-        familiar with the access-checking source code, you may notice
-        that the description here differs slightly from the algorithm
-        used in the code. The description is equivalent to what the code
-        actually does; it differs only to make the explanation simpler.)
-      </para>
-
-      <para>
-        For requests that require administrative privileges such as
-        <literal>SHUTDOWN</literal> or <literal>RELOAD</literal>, the
-        server checks only the <literal>user</literal> table row because
-        that is the only table that specifies administrative privileges.
-        Access is granted if the row allows the requested operation and
-        denied otherwise. For example, if you want to execute
+        The server uses the sorted tables to verify each request that it
+        receives. For requests that require administrative privileges
+        such as <literal>SHUTDOWN</literal> or
+        <literal>RELOAD</literal>, the server checks only the
+        <literal>user</literal> table row because that is the only table
+        that specifies administrative privileges. The server grants
+        access if the row allows the requested operation and denies
+        access otherwise. For example, if you want to execute
         <command>mysqladmin shutdown</command> but your
         <literal>user</literal> table row doesn't grant the
         <literal>SHUTDOWN</literal> privilege to you, the server denies
@@ -14917,7 +14938,11 @@
         successively checks the user's table and column privileges in
         the <literal>tables_priv</literal> and
         <literal>columns_priv</literal> tables, adds those to the user's
-        privileges, and allows or denies access based on the result.
+        privileges, and allows or denies access based on the result. For
+        stored routine operations, the server uses the
+        <literal>procs_priv</literal> table rather than
+        <literal>tables_priv</literal> and
+        <literal>columns_priv</literal>.
       </para>
 
       <para>
@@ -14930,6 +14955,7 @@
 OR (database privileges AND host privileges)
 OR table privileges
 OR column privileges
+OR routine privileges
 </programlisting>
 
       <para>
@@ -15008,7 +15034,7 @@
       </indexterm>
 
       <para>
-        Naturally, you should always test your entries in the grant
+        Naturally, you should always test your changes to the grant
         tables (for example, by using <literal>SHOW GRANTS</literal>) to
         make sure that your access privileges are actually set up the
         way you think they are.

Modified: trunk/refman-5.1/database-administration.xml
===================================================================
--- trunk/refman-5.1/database-administration.xml	2006-01-28 23:41:44 UTC (rev 1087)
+++ trunk/refman-5.1/database-administration.xml	2006-01-28 23:42:15 UTC (rev 1088)
@@ -14149,8 +14149,8 @@
         accepts or rejects the connection based on your identity and
         whether you can verify your identity by supplying the correct
         password. If not, the server denies access to you completely.
-        Otherwise, the server accepts the connection, then enters Stage
-        2 and waits for requests.
+        Otherwise, the server accepts the connection, and then enters
+        Stage 2 and waits for requests.
       </para>
 
       <para>
@@ -14180,7 +14180,7 @@
         <literal>Password</literal>). The server accepts the connection
         only if the <literal>Host</literal> and <literal>User</literal>
         columns in some <literal>user</literal> table row match the
-        client hostname and username, and the client supplies the
+        client hostname and username and the client supplies the
         password specified in that row.
       </para>
 
@@ -14257,25 +14257,47 @@
 
           <para>
             IP numbers that satisfy this condition and can connect to
-            the MySQL server are those that lie in the range from
+            the MySQL server are those in the range from
             <literal>192.58.197.0</literal> to
             <literal>192.58.197.255</literal>.
           </para>
-        </listitem>
 
-        <listitem>
           <para>
             Note: The netmask can only be used to tell the server to use
-            8, 16, 24, or 32 bits of the address, for example:
+            8, 16, 24, or 32 bits of the address. Examples:
           </para>
 
-<programlisting>
-192.0.0.0/255.0.0.0 (anything on the 192 class A network)
-192.168.0.0/255.255.0.0 (anything on the 192.168 class B network)
-192.168.1.0/255.255.255.0 (anything on the 192.168.1 class C network)
-192.168.1.1 (only this specific IP) 
-</programlisting>
+          <itemizedlist>
 
+            <listitem>
+              <para>
+                <literal>192.0.0.0/255.0.0.0</literal>: anything on the
+                192 class A network
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>192.168.0.0/255.255.0.0</literal>: anything on
+                the 192.168 class B network
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>192.168.1.0/255.255.255.0</literal>: anything
+                on the 192.168.1 class C network
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>192.168.1.1</literal>: only this specific IP
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
           <para>
             The following netmask (28 bits) will not work:
           </para>
@@ -14292,9 +14314,9 @@
             should be combined with those in the row in the
             <literal>host</literal> table that matches the client
             hostname. The privileges are combined using an AND
-            (intersection) operation, not OR (union). You can find more
-            information about the <literal>host</literal> table in
-            <xref linkend="request-access"/>.
+            (intersection) operation, not OR (union).
+            <xref linkend="request-access"/>, discusses use of the
+            <literal>host</literal> table further.
           </para>
 
           <para>
@@ -14353,10 +14375,10 @@
         connection process when checking whether the password is
         correct. (This is done without the encrypted password ever
         traveling over the connection.) From MySQL's point of view, the
-        encrypted password is the REAL password, so you should not give
-        anyone access to it! In particular, don't give
-        non-administrative users read access to the tables in the
-        <literal>mysql</literal> database!
+        encrypted password is the <emphasis>real</emphasis> password, so
+        you should never give anyone access to it. In particular,
+        <emphasis>do not give non-administrative users read access to
+        tables in the <literal>mysql</literal> database</emphasis>.
       </para>
 
       <para>
@@ -14370,9 +14392,9 @@
       </para>
 
       <para>
-        The following examples show how various combinations of
+        The following table shows how various combinations of
         <literal>Host</literal> and <literal>User</literal> values in
-        the <literal>user</literal> table apply to incoming connections:
+        the <literal>user</literal> table apply to incoming connections.
       </para>
 
       <informaltable>
@@ -14384,7 +14406,7 @@
             <row>
               <entry><literal>Host</literal> <emphasis role="bold">Value</emphasis></entry>
               <entry><literal>User</literal> <emphasis role="bold">Value</emphasis></entry>
-              <entry><emphasis role="bold">Connections Matched by Entry</emphasis></entry>
+              <entry><emphasis role="bold">Allowable Connections</emphasis></entry>
             </row>
             <row>
               <entry><literal>'thomas.loc.gov'</literal></entry>
@@ -14418,7 +14440,7 @@
               <entry><literal>'fred'</literal></entry>
               <entry><literal>fred</literal>, connecting from <literal>x.y.net</literal>,
                 <literal>x.y.com</literal>, <literal>x.y.edu</literal>,
-                and so on. (this is probably not useful)</entry>
+                and so on (this is probably not useful)</entry>
             </row>
             <row>
               <entry><literal>'144.155.166.177'</literal></entry>
@@ -14460,14 +14482,14 @@
         <listitem>
           <para>
             Whenever the server reads the <literal>user</literal> table
-            into memory, it sorts the entries.
+            into memory, it sorts the rows.
           </para>
         </listitem>
 
         <listitem>
           <para>
             When a client attempts to connect, the server looks through
-            the entries in sorted order.
+            the rows in sorted order.
           </para>
         </listitem>
 
@@ -14497,11 +14519,11 @@
 </programlisting>
 
       <para>
-        When the server reads in the table, it orders the entries with
-        the most-specific <literal>Host</literal> values first. Literal
-        hostnames and IP numbers are the most specific. The pattern
-        <literal>'%'</literal> means <quote>any host</quote> and is
-        least specific. Entries with the same <literal>Host</literal>
+        When the server reads the table into memory, it orders the rows
+        with the most-specific <literal>Host</literal> values first.
+        Literal hostnames and IP numbers are the most specific. The
+        pattern <literal>'%'</literal> means <quote>any host</quote> and
+        is least specific. Rows with the same <literal>Host</literal>
         value are ordered with the most-specific <literal>User</literal>
         values first (a blank <literal>User</literal> value means
         <quote>any user</quote> and is least specific). For the
@@ -14537,9 +14559,9 @@
 
       <para>
         When a client attempts to connect, the server looks through the
-        sorted entries and uses the first match found. For a connection
+        sorted rows and uses the first match found. For a connection
         from <literal>localhost</literal> by <literal>jeffrey</literal>,
-        two of the entries in the table match: the one with
+        two of the rows from the table match: the one with
         <literal>Host</literal> and <literal>User</literal> values of
         <literal>'localhost'</literal> and <literal>''</literal>, and
         the one with values of <literal>'%'</literal> and
@@ -14584,16 +14606,16 @@
 
       <para>
         It is a common misconception to think that, for a given
-        username, all entries that explicitly name that user are used
-        first when the server attempts to find a match for the
-        connection. This is simply not true. The previous example
-        illustrates this, where a connection from
-        <literal>thomas.loc.gov</literal> by <literal>jeffrey</literal>
-        is first matched not by the row containing
-        <literal>'jeffrey'</literal> as the <literal>User</literal>
-        column value, but by the row with no username. As a result,
-        <literal>jeffrey</literal> is authenticated as an anonymous
-        user, even though he specified a username when connecting.
+        username, all rows that explicitly name that user are used first
+        when the server attempts to find a match for the connection.
+        This is simply not true. The previous example illustrates this,
+        where a connection from <literal>thomas.loc.gov</literal> by
+        <literal>jeffrey</literal> is first matched not by the row
+        containing <literal>'jeffrey'</literal> as the
+        <literal>User</literal> column value, but by the row with no
+        username. As a result, <literal>jeffrey</literal> is
+        authenticated as an anonymous user, even though he specified a
+        username when connecting.
       </para>
 
       <para>
@@ -14601,7 +14623,8 @@
         are not what you expect, you probably are being authenticated as
         some other account. To find out what account the server used to
         authenticate you, use the <literal>CURRENT_USER()</literal>
-        function. It returns a value in
+        function. (See <xref linkend="information-functions"/>.) It
+        returns a value in
         <literal><replaceable>user_name</replaceable>@<replaceable>host_name</replaceable></literal>
         format that indicates the <literal>User</literal> and
         <literal>Host</literal> values from the matching
@@ -14629,8 +14652,7 @@
       <para>
         Another thing you can do to diagnose authentication problems is
         to print out the <literal>user</literal> table and sort it by
-        hand to see where the first match is being made. See also
-        <xref linkend="information-functions"/>.
+        hand to see where the first match is being made.
       </para>
 
     </section>
@@ -14640,8 +14662,8 @@
       <title>&title-request-access;</title>
 
       <para>
-        Once you establish a connection, the server enters Stage 2 of
-        access control. For each request that comes in on the
+        After you establish a connection, the server enters Stage 2 of
+        access control. For each request that you issue via that
         connection, the server determines what operation you want to
         perform, then checks whether you have sufficient privileges to
         do so. This is where the privilege columns in the grant tables
@@ -14664,7 +14686,7 @@
         <literal>user</literal> table privileges are superuser
         privileges. It is wise to grant privileges in the
         <literal>user</literal> table only to superusers such as
-        database administrators. For other users, you should leave the
+        database administrators. For other users, you should leave all
         privileges in the <literal>user</literal> table set to
         <literal>'N'</literal> and grant privileges at more specific
         levels only. You can grant privileges for particular databases,
@@ -14767,10 +14789,10 @@
       </indexterm>
 
       <para>
-        The server reads in and sorts the <literal>db</literal> and
-        <literal>host</literal> tables at the same time that it reads
-        the <literal>user</literal> table. The server sorts the
-        <literal>db</literal> table based on the
+        The server reads the <literal>db</literal> and
+        <literal>host</literal> tables into memory and sorts them at the
+        same time that it reads the <literal>user</literal> table. The
+        server sorts the <literal>db</literal> table based on the
         <literal>Host</literal>, <literal>Db</literal>, and
         <literal>User</literal> scope columns, and sorts the
         <literal>host</literal> table based on the
@@ -14791,6 +14813,11 @@
         <secondary>in <literal>mysql.columns_priv</literal> table</secondary>
       </indexterm>
 
+      <indexterm>
+        <primary>wildcards</primary>
+        <secondary>in <literal>mysql.procs_priv</literal> table</secondary>
+      </indexterm>
+
       <para>
         The <literal>tables_priv</literal>
         <literal>columns_priv</literal>, and
@@ -14805,16 +14832,16 @@
           <para>
             The wildcard characters &lsquo;<literal>%</literal>&rsquo;
             and &lsquo;<literal>_</literal>&rsquo; can be used in the
-            <literal>Host</literal> column of either table. These have
-            the same meaning as for pattern-matching operations
-            performed with the <literal>LIKE</literal> operator.
+            <literal>Host</literal> column. These have the same meaning
+            as for pattern-matching operations performed with the
+            <literal>LIKE</literal> operator.
           </para>
         </listitem>
 
         <listitem>
           <para>
             A <literal>'%'</literal> or blank <literal>Host</literal>
-            value in either table means <quote>any host.</quote>
+            value means <quote>any host.</quote>
           </para>
         </listitem>
 
@@ -14822,7 +14849,7 @@
           <para>
             The <literal>Db</literal>, <literal>Table_name</literal>,
             and <literal>Column_name</literal> columns cannot contain
-            wildcards or be blank in either table.
+            wildcards or be blank.
           </para>
         </listitem>
 
@@ -14839,20 +14866,14 @@
       </para>
 
       <para>
-        The request verification process is described here. (If you are
-        familiar with the access-checking source code, you may notice
-        that the description here differs slightly from the algorithm
-        used in the code. The description is equivalent to what the code
-        actually does; it differs only to make the explanation simpler.)
-      </para>
-
-      <para>
-        For requests that require administrative privileges such as
-        <literal>SHUTDOWN</literal> or <literal>RELOAD</literal>, the
-        server checks only the <literal>user</literal> table row because
-        that is the only table that specifies administrative privileges.
-        Access is granted if the row allows the requested operation and
-        denied otherwise. For example, if you want to execute
+        The server uses the sorted tables to verify each request that it
+        receives. For requests that require administrative privileges
+        such as <literal>SHUTDOWN</literal> or
+        <literal>RELOAD</literal>, the server checks only the
+        <literal>user</literal> table row because that is the only table
+        that specifies administrative privileges. The server grants
+        access if the row allows the requested operation and denies
+        access otherwise. For example, if you want to execute
         <command>mysqladmin shutdown</command> but your
         <literal>user</literal> table row doesn't grant the
         <literal>SHUTDOWN</literal> privilege to you, the server denies
@@ -14931,7 +14952,11 @@
         successively checks the user's table and column privileges in
         the <literal>tables_priv</literal> and
         <literal>columns_priv</literal> tables, adds those to the user's
-        privileges, and allows or denies access based on the result.
+        privileges, and allows or denies access based on the result. For
+        stored routine operations, the server uses the
+        <literal>procs_priv</literal> table rather than
+        <literal>tables_priv</literal> and
+        <literal>columns_priv</literal>.
       </para>
 
       <para>
@@ -14944,6 +14969,7 @@
 OR (database privileges AND host privileges)
 OR table privileges
 OR column privileges
+OR routine privileges
 </programlisting>
 
       <para>
@@ -15022,7 +15048,7 @@
       </indexterm>
 
       <para>
-        Naturally, you should always test your entries in the grant
+        Naturally, you should always test your changes to the grant
         tables (for example, by using <literal>SHOW GRANTS</literal>) to
         make sure that your access privileges are actually set up the
         way you think they are.

Thread
svn commit - mysqldoc@docsrva: r1088 - in trunk: . refman-4.1 refman-5.0 refman-5.1paul29 Jan