List:Commits« Previous MessageNext Message »
From:paul Date:January 6 2006 8:26pm
Subject:svn commit - mysqldoc@docsrva: r708 - in trunk: . refman-4.1 refman-5.0 refman-5.1
View as plain text  
Author: paul
Date: 2006-01-06 21:26:18 +0100 (Fri, 06 Jan 2006)
New Revision: 708

Log:
 r1992@kite-hub:  paul | 2006-01-06 13:59:38 -0600
 General revisions.


Modified:
   trunk/
   trunk/refman-4.1/using-mysql-programs.xml
   trunk/refman-5.0/using-mysql-programs.xml
   trunk/refman-5.1/using-mysql-programs.xml


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

Modified: trunk/refman-4.1/using-mysql-programs.xml
===================================================================
--- trunk/refman-4.1/using-mysql-programs.xml	2006-01-06 20:26:00 UTC (rev 707)
+++ trunk/refman-4.1/using-mysql-programs.xml	2006-01-06 20:26:18 UTC (rev 708)
@@ -667,6 +667,10 @@
         <secondary>default</secondary>
       </indexterm>
 
+      <indexterm type="type">
+        <primary>.my.cnf file</primary>
+      </indexterm>
+
       <para>
         Most MySQL programs can read startup options from option files
         (also sometimes called configuration files). Option files
@@ -795,32 +799,58 @@
       </para>
 
       <para>
-        If <literal>MYSQL_HOME</literal> is not set and there is a
-        <literal>my.cnf</literal> file in
-        <replaceable>DATADIR</replaceable> and there is no
-        <literal>my.cnf</literal> file in
-        <replaceable>BASEDIR</replaceable>,
-        <literal>mysqld_safe</literal> sets
-        <literal>MYSQL_HOME</literal> to
-        <replaceable>DATADIR</replaceable>. Otherwise, if
-        <literal>MYSQL_HOME</literal> is not set and there is no
-        <filename>my.cnf</filename> in
-        <replaceable>DATADIR</replaceable>,
-        <literal>mysqld_safe</literal> sets
-        <literal>MYSQL_HOME</literal> to
-        <replaceable>BASEDIR</replaceable>.
+        If <literal>MYSQL_HOME</literal> is not set and you start the
+        server using the <command>mysqld_safe</command> program,
+        <command>mysqld_safe</command> attempts to set
+        <literal>MYSQL_HOME</literal> as follows:
       </para>
 
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Let <replaceable>BASEDIR</replaceable> and
+            <replaceable>DATADIR</replaceable> represent the pathnames
+            of the MySQL base directory and data directory,
+            respectively.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            If there is a <filename>my.cnf</filename> file in
+            <replaceable>DATADIR</replaceable> but not in
+            <replaceable>BASEDIR</replaceable>,
+            <command>mysqld_safe</command> sets
+            <literal>MYSQL_HOME</literal> to
+            <replaceable>DATADIR</replaceable>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Otherwise, if <literal>MYSQL_HOME</literal> is not set and
+            there is no <filename>my.cnf</filename> file in
+            <replaceable>DATADIR</replaceable>,
+            <command>mysqld_safe</command> sets
+            <literal>MYSQL_HOME</literal> to
+            <replaceable>BASEDIR</replaceable>.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
       <para>
-        Typically this is <filename>/usr/local/mysql/data</filename> for
-        a binary installation or <filename>/usr/local/var</filename> for
-        a source installation. Note that this is the data directory
-        location that was specified at configuration time, not the one
-        specified with <option>--datadir</option> when
+        Typically, <replaceable>DATADIR</replaceable> is
+        <filename>/usr/local/mysql/data</filename> for a binary
+        installation or <filename>/usr/local/var</filename> for a source
+        installation. Note that this is the data directory location that
+        was specified at configuration time, not the one specified with
+        the <option>--datadir</option> option when
         <command>mysqld</command> starts. Use of
         <option>--datadir</option> at runtime has no effect on where the
         server looks for option files, because it looks for them before
-        processing any command-line arguments.
+        processing any options.
       </para>
 
       <para>
@@ -887,10 +917,9 @@
           <para>
             <replaceable>group</replaceable> is the name of the program
             or group for which you want to set options. After a group
-            line, any <replaceable>opt_name</replaceable> or
-            <literal>set-variable</literal> lines apply to the named
-            group until the end of the option file or another group line
-            is given.
+            line, any option-setting lines apply to the named group
+            until the end of the option file or another group line is
+            given.
           </para>
         </listitem>
 
@@ -917,8 +946,8 @@
             on the command line. In an option file, you can have spaces
             around the &lsquo;<literal>=</literal>&rsquo; character,
             something that is not true on the command line. As of MySQL
-            4.0.16, you can quote the value with double quotes or single
-            quotes. This is useful if the value contains a
+            4.0.16, you can enclose the value within double quotes or
+            single quotes. This is useful if the value contains a
             &lsquo;<literal>#</literal>&rsquo; comment character or
             whitespace.
           </para>
@@ -945,6 +974,20 @@
       </itemizedlist>
 
       <para>
+        For options that take a numeric value, the value can be given
+        with a suffix of <literal>K</literal>, <literal>M</literal>, or
+        <literal>G</literal> (either uppercase or lowercase) to indicate
+        a multiplier of 1024, 1024<superscript>2</superscript> or
+        1024<superscript>3</superscript>. For example, the following
+        command tells <command>mysqladmin</command> to ping the server
+        1024 times, sleeping 10 seconds between each ping:
+      </para>
+
+<programlisting>
+mysql&gt; <userinput>mysqladmin --count=1K --sleep=10 ping</userinput>
+</programlisting>
+
+      <para>
         Leading and trailing blanks are automatically deleted from
         option names and values. You may use the escape sequences
         &lsquo;<literal>\b</literal>&rsquo;,
@@ -958,18 +1001,21 @@
       </para>
 
       <para>
-        On Windows, if an option value represents a pathname, you should
+        Because the &lsquo;<literal>\\</literal>&rsquo; escape sequence
+        represents a single backslash, you must write each
+        &lsquo;<literal>\</literal>&rsquo; as
+        &lsquo;<literal>\\</literal>&rsquo;. Alternatively, you can
         specify the value using &lsquo;<literal>/</literal>&rsquo;
         rather than &lsquo;<literal>\</literal>&rsquo; as the pathname
-        separator. If you use &lsquo;<literal>\</literal>&rsquo;, you
-        must double it as &lsquo;<literal>\\</literal>&rsquo;, because
-        &lsquo;<literal>\</literal>&rsquo; is the escape character in
-        MySQL.
+        separator.
       </para>
 
       <para>
         If an option group name is the same as a program name, options
-        in the group apply specifically to that program.
+        in the group apply specifically to that program. For example,
+        the <literal>[mysqld]</literal> and <literal>[mysql]</literal>
+        groups apply to the <command>mysqld</command> server and the
+        <command>mysql</command> client program, respectively.
       </para>
 
       <para>
@@ -989,86 +1035,6 @@
       </para>
 
       <para>
-        Beginning with MySQL 4.1.11 in the 4.1 series and MySQL 5.0.4 in
-        the 5.0 series, it is possible to use
-        <literal>!include</literal> directives in option files to
-        include specific files and <literal>!includedir</literal> to
-        search specific directories for option files. For example, to
-        include the file <filename>/home/mydir/myopt.cnf</filename>, you
-        can use the following:
-      </para>
-
-<programlisting>
-!include /home/me/myopt.cnf
-</programlisting>
-
-      <para>
-        To search the directory <filename>/home/mydir</filename> for all
-        files ending in <filename>.cnf</filename> and to read these as
-        option files, you would use:
-      </para>
-
-<programlisting>
-!includedir /home/mydir
-</programlisting>
-
-      <para>
-        Note that these options are section-specific. For example,
-        suppose that you were to use something in
-        <filename>my.cnf</filename> such as the following:
-      </para>
-
-<programlisting>
-[mysqld]
-!include /home/mydir/myopt.cnf
-</programlisting>
-
-      <para>
-        In such a case, the file <filename>myopt.cnf</filename> would be
-        processed only for the server, and the
-        <literal>!include</literal> directive would be ignored by any
-        client applications. However, if you were to use the following:
-      </para>
-
-<programlisting>
-[mysqldump]
-!includedir /home/mydir/my-dump-options
-</programlisting>
-
-      <para>
-        then the directory
-        <filename>/home/mydir/my-dump-options</filename> would be
-        checked for option files ending in <filename>.cnf</filename> by
-        <command>mysqldump</command> only, and not by the server or by
-        any other client applications.
-      </para>
-
-      <para>
-        <emphasis role="bold">Note</emphasis>: Currently, any files to
-        be found and included using the <literal>!includedir</literal>
-        directive on Unix operating systems <emphasis>must</emphasis>
-        have filenames ending in <filename>.cnf</filename>. On Windows,
-        this directive also checks for files with a
-        <filename>.ini</filename> extension (in addition to
-        <filename>.cnf</filename>).
-      </para>
-
-      <para>
-        As of MySQL 4.0.14, if you want to create option groups that
-        should be read only by one specific <command>mysqld</command>
-        server release series only, you can do this by using groups with
-        names of <literal>[mysqld-4.0]</literal>,
-        <literal>[mysqld-4.1]</literal>, and so forth. The following
-        group indicates that the <option>--new</option> option should be
-        used only by MySQL servers with 4.0.x version numbers:
-      </para>
-
-<programlisting>
-[mysqld-4.0]
-new
-</programlisting>
-
-      <para>
         Here is a typical global option file:
       </para>
 
@@ -1112,7 +1078,6 @@
 
 [mysqlhotcopy]
 interactive-timeout
-
 </programlisting>
 
       <para>
@@ -1122,27 +1087,101 @@
         <literal>connect_timeout=2</literal>.
       </para>
 
-      <indexterm type="type">
-        <primary>.my.cnf file</primary>
-      </indexterm>
+      <para>
+        As of MySQL 4.0.14, if you want to create option groups that
+        should be read only by <command>mysqld</command> servers from a
+        specific MySQL release series only, you can do this by using
+        groups with names of <literal>[mysqld-4.0]</literal>,
+        <literal>[mysqld-4.1]</literal>, and so forth. The following
+        group indicates that the <option>--new</option> option should be
+        used only by MySQL servers with 4.0.x version numbers:
+      </para>
 
+<programlisting>
+[mysqld-4.0]
+new
+</programlisting>
+
       <para>
+        Beginning with MySQL 4.1.11 in the 4.1 series and MySQL 5.0.4 in
+        the 5.0 series, it is possible to use
+        <literal>!include</literal> directives in option files to
+        include other option files and <literal>!includedir</literal> to
+        search specific directories for option files. For example, to
+        include the <filename>/home/mydir/myopt.cnf</filename> file, you
+        can use the following directive:
+      </para>
+
+<programlisting>
+!include /home/me/myopt.cnf
+</programlisting>
+
+      <para>
+        To search the <filename>/home/mydir</filename> directory and
+        read option files found there, you would use this directive:
+      </para>
+
+<programlisting>
+!includedir /home/mydir
+</programlisting>
+
+      <para>
+        <emphasis role="bold">Note</emphasis>: Currently, any files to
+        be found and included using the <literal>!includedir</literal>
+        directive on Unix operating systems <emphasis>must</emphasis>
+        have filenames ending in <filename>.cnf</filename>. On Windows,
+        this directive checks for files with the
+        <filename>.ini</filename> or <filename>.cnf</filename>
+        extension.
+      </para>
+
+      <para>
+        Note that options read from included files are applied in the
+        context of the current option group. Suppose that you were to
+        write the following lines in <filename>my.cnf</filename>:
+      </para>
+
+<programlisting>
+[mysqld]
+!include /home/mydir/myopt.cnf
+</programlisting>
+
+      <para>
+        In this case, the <filename>myopt.cnf</filename> file is
+        processed only for the server, and the
+        <literal>!include</literal> directive is ignored by any client
+        applications. However, if you were to use the following lines,
+        the directory <filename>/home/mydir/my-dump-options</filename>
+        is checked for option files by <command>mysqldump</command>
+        only, and not by the server or by any other client applications:
+      </para>
+
+<programlisting>
+[mysqldump]
+!includedir /home/mydir/my-dump-options
+</programlisting>
+
+      <para>
         If you have a source distribution, you can find sample option
         files named
         <filename>my-<replaceable>xxxx</replaceable>.cnf</filename> in
         the <filename>support-files</filename> directory. If you have a
         binary distribution, look in the
         <filename>support-files</filename> directory under your MySQL
-        installation directory. On Windows the sample option files may
-        also be located in the MySQL installation directory (see earlier
-        in this section or <xref linkend="installing"/>, if you do not
-        know where this is). Currently there are sample option files for
+        installation directory. On Windows, the sample option files may
+        be located in the MySQL installation directory (see earlier in
+        this section or <xref linkend="installing"/>, if you do not know
+        where this is). Currently, there are sample option files for
         small, medium, large, and very large systems. To experiment with
         one of these files, copy it to <filename>C:\my.cnf</filename> on
         Windows or to <filename>.my.cnf</filename> in your home
         directory on Unix.
       </para>
 
+      <remark role="todo">
+        Is that true for .ini as well?
+      </remark>
+
       <para>
         <emphasis role="bold">Note</emphasis>: On Windows, the
         <filename>.cnf</filename> option file extension might not be
@@ -1151,7 +1190,13 @@
 
       <para>
         All MySQL programs that support option files handle the
-        following command-line options:
+        following options. They affect option-file handling, so they
+        must be given on the command line and not in an option file. To
+        work properly, each of these options must immediately follow the
+        command name, with the exception that
+        <option>--print-defaults</option> may be used immediately after
+        <option>--defaults-file</option> or
+        <option>--defaults-extra-file</option>.
       </para>
 
       <itemizedlist>
@@ -1195,8 +1240,8 @@
           </para>
 
           <para>
-            Read this option file after the global option file but
-            before the user option file.
+            Read this option file after the global option file but (on
+            Unix) before the user option file.
             <replaceable>path_name</replaceable> is the full pathname to
             the file.
           </para>
@@ -1204,14 +1249,6 @@
 
       </itemizedlist>
 
-      <para>
-        To work properly, each of these options must immediately follow
-        the command name on the command line, with the exception that
-        <option>--print-defaults</option> may be used immediately after
-        <option>--defaults-file</option> or
-        <option>--defaults-extra-file</option>.
-      </para>
-
       <remark role="todo">
         The next few paragraphs probably should go into the API chapter.
       </remark>

Modified: trunk/refman-5.0/using-mysql-programs.xml
===================================================================
--- trunk/refman-5.0/using-mysql-programs.xml	2006-01-06 20:26:00 UTC (rev 707)
+++ trunk/refman-5.0/using-mysql-programs.xml	2006-01-06 20:26:18 UTC (rev 708)
@@ -674,6 +674,10 @@
         <secondary>default</secondary>
       </indexterm>
 
+      <indexterm type="type">
+        <primary>.my.cnf file</primary>
+      </indexterm>
+
       <para>
         Most MySQL programs can read startup options from option files
         (also sometimes called configuration files). Option files
@@ -807,32 +811,58 @@
       </para>
 
       <para>
-        If <literal>MYSQL_HOME</literal> is not set and there is a
-        <literal>my.cnf</literal> file in
-        <replaceable>DATADIR</replaceable> and there is no
-        <literal>my.cnf</literal> file in
-        <replaceable>BASEDIR</replaceable>,
-        <literal>mysqld_safe</literal> sets
-        <literal>MYSQL_HOME</literal> to
-        <replaceable>DATADIR</replaceable>. Otherwise, if
-        <literal>MYSQL_HOME</literal> is not set and there is no
-        <filename>my.cnf</filename> in
-        <replaceable>DATADIR</replaceable>,
-        <literal>mysqld_safe</literal> sets
-        <literal>MYSQL_HOME</literal> to
-        <replaceable>BASEDIR</replaceable>.
+        If <literal>MYSQL_HOME</literal> is not set and you start the
+        server using the <command>mysqld_safe</command> program,
+        <command>mysqld_safe</command> attempts to set
+        <literal>MYSQL_HOME</literal> as follows:
       </para>
 
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Let <replaceable>BASEDIR</replaceable> and
+            <replaceable>DATADIR</replaceable> represent the pathnames
+            of the MySQL base directory and data directory,
+            respectively.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            If there is a <filename>my.cnf</filename> file in
+            <replaceable>DATADIR</replaceable> but not in
+            <replaceable>BASEDIR</replaceable>,
+            <command>mysqld_safe</command> sets
+            <literal>MYSQL_HOME</literal> to
+            <replaceable>DATADIR</replaceable>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Otherwise, if <literal>MYSQL_HOME</literal> is not set and
+            there is no <filename>my.cnf</filename> file in
+            <replaceable>DATADIR</replaceable>,
+            <command>mysqld_safe</command> sets
+            <literal>MYSQL_HOME</literal> to
+            <replaceable>BASEDIR</replaceable>.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
       <para>
-        Typically this is <filename>/usr/local/mysql/data</filename> for
-        a binary installation or <filename>/usr/local/var</filename> for
-        a source installation. Note that this is the data directory
-        location that was specified at configuration time, not the one
-        specified with <option>--datadir</option> when
+        Typically, <replaceable>DATADIR</replaceable> is
+        <filename>/usr/local/mysql/data</filename> for a binary
+        installation or <filename>/usr/local/var</filename> for a source
+        installation. Note that this is the data directory location that
+        was specified at configuration time, not the one specified with
+        the <option>--datadir</option> option when
         <command>mysqld</command> starts. Use of
         <option>--datadir</option> at runtime has no effect on where the
         server looks for option files, because it looks for them before
-        processing any command-line arguments.
+        processing any options.
       </para>
 
       <para>
@@ -899,10 +929,9 @@
           <para>
             <replaceable>group</replaceable> is the name of the program
             or group for which you want to set options. After a group
-            line, any <replaceable>opt_name</replaceable> or
-            <literal>set-variable</literal> lines apply to the named
-            group until the end of the option file or another group line
-            is given.
+            line, any option-setting lines apply to the named group
+            until the end of the option file or another group line is
+            given.
           </para>
         </listitem>
 
@@ -929,36 +958,28 @@
             on the command line. In an option file, you can have spaces
             around the &lsquo;<literal>=</literal>&rsquo; character,
             something that is not true on the command line. You can
-            quote the value with single quotes or double quotes. This is
-            useful if the value contains a
+            enclose the value within single quotes or double quotes,
+            which is useful if the value contains a
             &lsquo;<literal>#</literal>&rsquo; comment character or
             whitespace.
           </para>
         </listitem>
 
-<!--
-    <listitem>
-<remark role="note">Commented out. Probably should just be dropped? 
-            /JS 2005-07-18</remark>
-          
-    <para>
-     <literal>set-variable =
-     <replaceable>var_name</replaceable>=<replaceable>value</replaceable></literal>
-    </para>
+      </itemizedlist>
 
-    <para>
-     Set the program variable <replaceable>var_name</replaceable> to the
-     given value. This is equivalent to
-     <option>- -set-variable=<replaceable>var_name</replaceable>=<replaceable>value</replaceable></option>
-     on the command line. Spaces are allowed around the first
-     &lsquo;<literal>=</literal>&rsquo; character but not around the second. This
-     syntax is deprecated as of MySQL 4.0. See
-     <xref linkend="program-variables"/>, for more information on setting
-     program variables.
-    </para></listitem>
--->
+      <para>
+        For options that take a numeric value, the value can be given
+        with a suffix of <literal>K</literal>, <literal>M</literal>, or
+        <literal>G</literal> (either uppercase or lowercase) to indicate
+        a multiplier of 1024, 1024<superscript>2</superscript> or
+        1024<superscript>3</superscript>. For example, the following
+        command tells <command>mysqladmin</command> to ping the server
+        1024 times, sleeping 10 seconds between each ping:
+      </para>
 
-      </itemizedlist>
+<programlisting>
+mysql&gt; <userinput>mysqladmin --count=1K --sleep=10 ping</userinput>
+</programlisting>
 
       <para>
         Leading and trailing blanks are automatically deleted from
@@ -974,18 +995,21 @@
       </para>
 
       <para>
-        On Windows, if an option value represents a pathname, you should
+        Because the &lsquo;<literal>\\</literal>&rsquo; escape sequence
+        represents a single backslash, you must write each
+        &lsquo;<literal>\</literal>&rsquo; as
+        &lsquo;<literal>\\</literal>&rsquo;. Alternatively, you can
         specify the value using &lsquo;<literal>/</literal>&rsquo;
         rather than &lsquo;<literal>\</literal>&rsquo; as the pathname
-        separator. If you use &lsquo;<literal>\</literal>&rsquo;, you
-        must double it as &lsquo;<literal>\\</literal>&rsquo;, because
-        &lsquo;<literal>\</literal>&rsquo; is the escape character in
-        MySQL.
+        separator.
       </para>
 
       <para>
         If an option group name is the same as a program name, options
-        in the group apply specifically to that program.
+        in the group apply specifically to that program. For example,
+        the <literal>[mysqld]</literal> and <literal>[mysql]</literal>
+        groups apply to the <command>mysqld</command> server and the
+        <command>mysql</command> client program, respectively.
       </para>
 
       <para>
@@ -1005,73 +1029,53 @@
       </para>
 
       <para>
-        Beginning MySQL 5.0.4 in the 5.0 series, it is possible to use
-        <literal>!include</literal> directives in option files to
-        include specific files and <literal>!includedir</literal> to
-        search specific directories for option files. For example, to
-        include the file <filename>/home/mydir/myopt.cnf</filename>, you
-        can use the following:
+        Here is a typical global option file:
       </para>
 
 <programlisting>
-!include /home/me/myopt.cnf
-</programlisting>
+[client]
+port=3306
+socket=/tmp/mysql.sock
 
-      <para>
-        To search the directory <filename>/home/mydir</filename> for all
-        files ending in <filename>.cnf</filename> and to read these as
-        option files, you would use:
-      </para>
+[mysqld]
+port=3306
+socket=/tmp/mysql.sock
+key_buffer_size=16M
+max_allowed_packet=8M
 
-<programlisting>
-!includedir /home/mydir
+[mysqldump]
+quick
 </programlisting>
 
       <para>
-        Note that these options are section-specific. For example,
-        suppose that you were to use something in
-        <filename>my.cnf</filename> such as the following:
+        The preceding option file uses
+        <literal><replaceable>var_name</replaceable>=<replaceable>value</replaceable></literal>
+        syntax for the lines that set the
+        <literal>key_buffer_size</literal> and
+        <literal>max_allowed_packet</literal> variables.
       </para>
 
-<programlisting>
-[mysqld]
-!include /home/mydir/myopt.cnf
-</programlisting>
-
       <para>
-        In such a case, the file <filename>myopt.cnf</filename> would be
-        processed only for the server, and the
-        <literal>!include</literal> directive would be ignored by any
-        client applications. However, if you were to use the following:
+        Here is a typical user option file:
       </para>
 
 <programlisting>
-[mysqldump]
-!includedir /home/mydir/my-dump-options
-</programlisting>
+[client]
+# The following password will be sent to all standard MySQL clients
+password="my_password"
 
-      <para>
-        then the directory
-        <filename>/home/mydir/my-dump-options</filename> would be
-        checked for option files ending in <filename>.cnf</filename> by
-        <command>mysqldump</command> only, and not by the server or by
-        any other client applications.
-      </para>
+[mysql]
+no-auto-rehash
+connect_timeout=2
 
-      <para>
-        <emphasis role="bold">Note</emphasis>: Currently, any files to
-        be found and included using the <literal>!includedir</literal>
-        directive on Unix operating systems <emphasis>must</emphasis>
-        have filenames ending in <filename>.cnf</filename>. On Windows,
-        this directive also checks for files with a
-        <filename>.ini</filename> extension (in addition to
-        <filename>.cnf</filename>).
-      </para>
+[mysqlhotcopy]
+interactive-timeout
+</programlisting>
 
       <para>
-        If you want to create option groups that should be read by one
-        specific <command>mysqld</command> server release series only,
-        you can do this by using groups with names of
+        If you want to create option groups that should be read by
+        <command>mysqld</command> servers from a specific MySQL release
+        series only, you can do this by using groups with names of
         <literal>[mysqld-&previous-series;]</literal>,
         <literal>[mysqld-&current-series;]</literal>, and so forth. The
         following group indicates that the <option>--new</option> option
@@ -1085,54 +1089,63 @@
 </programlisting>
 
       <para>
-        Here is a typical global option file:
+        Beginning with MySQL 5.0.4, it is possible to use
+        <literal>!include</literal> directives in option files to
+        include other option files and <literal>!includedir</literal> to
+        search specific directories for option files. For example, to
+        include the <filename>/home/mydir/myopt.cnf</filename> file, you
+        can use the following directive:
       </para>
 
 <programlisting>
-[client]
-port=3306
-socket=/tmp/mysql.sock
+!include /home/me/myopt.cnf
+</programlisting>
 
-[mysqld]
-port=3306
-socket=/tmp/mysql.sock
-key_buffer_size=16M
-max_allowed_packet=8M
+      <para>
+        To search the <filename>/home/mydir</filename> directory and
+        read option files found there, you would use this directive:
+      </para>
 
-[mysqldump]
-quick
+<programlisting>
+!includedir /home/mydir
 </programlisting>
 
       <para>
-        The preceding option file uses
-        <literal><replaceable>var_name</replaceable>=<replaceable>value</replaceable></literal>
-        syntax for the lines that set the
-        <literal>key_buffer_size</literal> and
-        <literal>max_allowed_packet</literal> variables.
+        <emphasis role="bold">Note</emphasis>: Currently, any files to
+        be found and included using the <literal>!includedir</literal>
+        directive on Unix operating systems <emphasis>must</emphasis>
+        have filenames ending in <filename>.cnf</filename>. On Windows,
+        this directive checks for files with the
+        <filename>.ini</filename> or <filename>.cnf</filename>
+        extension.
       </para>
 
       <para>
-        Here is a typical user option file:
+        Note that options read from included files are applied in the
+        context of the current option group. Suppose that you were to
+        write the following lines in <filename>my.cnf</filename>:
       </para>
 
 <programlisting>
-[client]
-# The following password will be sent to all standard MySQL clients
-password="my_password"
+[mysqld]
+!include /home/mydir/myopt.cnf
+</programlisting>
 
-[mysql]
-no-auto-rehash
-connect_timeout=2
+      <para>
+        In this case, the <filename>myopt.cnf</filename> file is
+        processed only for the server, and the
+        <literal>!include</literal> directive is ignored by any client
+        applications. However, if you were to use the following lines,
+        the directory <filename>/home/mydir/my-dump-options</filename>
+        is checked for option files by <command>mysqldump</command>
+        only, and not by the server or by any other client applications:
+      </para>
 
-[mysqlhotcopy]
-interactive-timeout
-
+<programlisting>
+[mysqldump]
+!includedir /home/mydir/my-dump-options
 </programlisting>
 
-      <indexterm type="type">
-        <primary>.my.cnf file</primary>
-      </indexterm>
-
       <para>
         If you have a source distribution, you can find sample option
         files named
@@ -1140,16 +1153,20 @@
         the <filename>support-files</filename> directory. If you have a
         binary distribution, look in the
         <filename>support-files</filename> directory under your MySQL
-        installation directory. On Windows the sample option files may
-        also be located in the MySQL installation directory (see earlier
-        in this section or <xref linkend="installing"/>, if you do not
-        know where this is). Currently there are sample option files for
+        installation directory. On Windows, the sample option files may
+        be located in the MySQL installation directory (see earlier in
+        this section or <xref linkend="installing"/>, if you do not know
+        where this is). Currently, there are sample option files for
         small, medium, large, and very large systems. To experiment with
         one of these files, copy it to <filename>C:\my.cnf</filename> on
         Windows or to <filename>.my.cnf</filename> in your home
         directory on Unix.
       </para>
 
+      <remark role="todo">
+        Is that true for .ini as well?
+      </remark>
+
       <para>
         <emphasis role="bold">Note</emphasis>: On Windows, the
         <filename>.cnf</filename> option file extension might not be
@@ -1158,7 +1175,13 @@
 
       <para>
         All MySQL programs that support option files handle the
-        following command-line options:
+        following options. They affect option-file handling, so they
+        must be given on the command line and not in an option file. To
+        work properly, each of these options must immediately follow the
+        command name, with the exception that
+        <option>--print-defaults</option> may be used immediately after
+        <option>--defaults-file</option> or
+        <option>--defaults-extra-file</option>.
       </para>
 
       <itemizedlist>
@@ -1202,8 +1225,8 @@
           </para>
 
           <para>
-            Read this option file after the global option file but
-            before the user option file.
+            Read this option file after the global option file but (on
+            Unix) before the user option file.
             <replaceable>path_name</replaceable> is the full pathname to
             the file.
           </para>
@@ -1211,14 +1234,6 @@
 
       </itemizedlist>
 
-      <para>
-        To work properly, each of these options must immediately follow
-        the command name on the command line, with the exception that
-        <option>--print-defaults</option> may be used immediately after
-        <option>--defaults-file</option> or
-        <option>--defaults-extra-file</option>.
-      </para>
-
       <remark role="todo">
         The next few paragraphs probably should go into the API chapter.
       </remark>

Modified: trunk/refman-5.1/using-mysql-programs.xml
===================================================================
--- trunk/refman-5.1/using-mysql-programs.xml	2006-01-06 20:26:00 UTC (rev 707)
+++ trunk/refman-5.1/using-mysql-programs.xml	2006-01-06 20:26:18 UTC (rev 708)
@@ -674,6 +674,10 @@
         <secondary>default</secondary>
       </indexterm>
 
+      <indexterm type="type">
+        <primary>.my.cnf file</primary>
+      </indexterm>
+
       <para>
         Most MySQL programs can read startup options from option files
         (also sometimes called configuration files). Option files
@@ -806,32 +810,58 @@
       </para>
 
       <para>
-        If <literal>MYSQL_HOME</literal> is not set and there is a
-        <literal>my.cnf</literal> file in
-        <replaceable>DATADIR</replaceable> and there is no
-        <literal>my.cnf</literal> file in
-        <replaceable>BASEDIR</replaceable>,
-        <literal>mysqld_safe</literal> sets
-        <literal>MYSQL_HOME</literal> to
-        <replaceable>DATADIR</replaceable>. Otherwise, if
-        <literal>MYSQL_HOME</literal> is not set and there is no
-        <filename>my.cnf</filename> in
-        <replaceable>DATADIR</replaceable>,
-        <literal>mysqld_safe</literal> sets
-        <literal>MYSQL_HOME</literal> to
-        <replaceable>BASEDIR</replaceable>.
+        If <literal>MYSQL_HOME</literal> is not set and you start the
+        server using the <command>mysqld_safe</command> program,
+        <command>mysqld_safe</command> attempts to set
+        <literal>MYSQL_HOME</literal> as follows:
       </para>
 
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Let <replaceable>BASEDIR</replaceable> and
+            <replaceable>DATADIR</replaceable> represent the pathnames
+            of the MySQL base directory and data directory,
+            respectively.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            If there is a <filename>my.cnf</filename> file in
+            <replaceable>DATADIR</replaceable> but not in
+            <replaceable>BASEDIR</replaceable>,
+            <command>mysqld_safe</command> sets
+            <literal>MYSQL_HOME</literal> to
+            <replaceable>DATADIR</replaceable>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Otherwise, if <literal>MYSQL_HOME</literal> is not set and
+            there is no <filename>my.cnf</filename> file in
+            <replaceable>DATADIR</replaceable>,
+            <command>mysqld_safe</command> sets
+            <literal>MYSQL_HOME</literal> to
+            <replaceable>BASEDIR</replaceable>.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
       <para>
-        Typically this is <filename>/usr/local/mysql/data</filename> for
-        a binary installation or <filename>/usr/local/var</filename> for
-        a source installation. Note that this is the data directory
-        location that was specified at configuration time, not the one
-        specified with <option>--datadir</option> when
+        Typically, <replaceable>DATADIR</replaceable> is
+        <filename>/usr/local/mysql/data</filename> for a binary
+        installation or <filename>/usr/local/var</filename> for a source
+        installation. Note that this is the data directory location that
+        was specified at configuration time, not the one specified with
+        the <option>--datadir</option> option when
         <command>mysqld</command> starts. Use of
         <option>--datadir</option> at runtime has no effect on where the
         server looks for option files, because it looks for them before
-        processing any command-line arguments.
+        processing any options.
       </para>
 
       <para>
@@ -898,10 +928,9 @@
           <para>
             <replaceable>group</replaceable> is the name of the program
             or group for which you want to set options. After a group
-            line, any <replaceable>opt_name</replaceable> or
-            <literal>set-variable</literal> lines apply to the named
-            group until the end of the option file or another group line
-            is given.
+            line, any option-setting lines apply to the named group
+            until the end of the option file or another group line is
+            given.
           </para>
         </listitem>
 
@@ -928,36 +957,28 @@
             on the command line. In an option file, you can have spaces
             around the &lsquo;<literal>=</literal>&rsquo; character,
             something that is not true on the command line. You can
-            quote the value with single quotes or double quotes. This is
-            useful if the value contains a
+            enclose the value within single quotes or double quotes,
+            which is useful if the value contains a
             &lsquo;<literal>#</literal>&rsquo; comment character or
             whitespace.
           </para>
         </listitem>
 
-<!--
-    <listitem>
-<remark role="note">Commented out. Probably should just be dropped? 
-            /JS 2005-07-18</remark>
-          
-    <para>
-     <literal>set-variable =
-     <replaceable>var_name</replaceable>=<replaceable>value</replaceable></literal>
-    </para>
+      </itemizedlist>
 
-    <para>
-     Set the program variable <replaceable>var_name</replaceable> to the
-     given value. This is equivalent to
-     <option>- -set-variable=<replaceable>var_name</replaceable>=<replaceable>value</replaceable></option>
-     on the command line. Spaces are allowed around the first
-     &lsquo;<literal>=</literal>&rsquo; character but not around the second. This
-     syntax is deprecated as of MySQL 4.0. See
-     <xref linkend="program-variables"/>, for more information on setting
-     program variables.
-    </para></listitem>
--->
+      <para>
+        For options that take a numeric value, the value can be given
+        with a suffix of <literal>K</literal>, <literal>M</literal>, or
+        <literal>G</literal> (either uppercase or lowercase) to indicate
+        a multiplier of 1024, 1024<superscript>2</superscript> or
+        1024<superscript>3</superscript>. For example, the following
+        command tells <command>mysqladmin</command> to ping the server
+        1024 times, sleeping 10 seconds between each ping:
+      </para>
 
-      </itemizedlist>
+<programlisting>
+mysql&gt; <userinput>mysqladmin --count=1K --sleep=10 ping</userinput>
+</programlisting>
 
       <para>
         Leading and trailing blanks are automatically deleted from
@@ -973,18 +994,21 @@
       </para>
 
       <para>
-        On Windows, if an option value represents a pathname, you should
+        Because the &lsquo;<literal>\\</literal>&rsquo; escape sequence
+        represents a single backslash, you must write each
+        &lsquo;<literal>\</literal>&rsquo; as
+        &lsquo;<literal>\\</literal>&rsquo;. Alternatively, you can
         specify the value using &lsquo;<literal>/</literal>&rsquo;
         rather than &lsquo;<literal>\</literal>&rsquo; as the pathname
-        separator. If you use &lsquo;<literal>\</literal>&rsquo;, you
-        must double it as &lsquo;<literal>\\</literal>&rsquo;, because
-        &lsquo;<literal>\</literal>&rsquo; is the escape character in
-        MySQL.
+        separator.
       </para>
 
       <para>
         If an option group name is the same as a program name, options
-        in the group apply specifically to that program.
+        in the group apply specifically to that program. For example,
+        the <literal>[mysqld]</literal> and <literal>[mysql]</literal>
+        groups apply to the <command>mysqld</command> server and the
+        <command>mysql</command> client program, respectively.
       </para>
 
       <para>
@@ -1004,73 +1028,53 @@
       </para>
 
       <para>
-        Beginning MySQL 5.0.4 in the 5.0 series, it is possible to use
-        <literal>!include</literal> directives in option files to
-        include specific files and <literal>!includedir</literal> to
-        search specific directories for option files. For example, to
-        include the file <filename>/home/mydir/myopt.cnf</filename>, you
-        can use the following:
+        Here is a typical global option file:
       </para>
 
 <programlisting>
-!include /home/me/myopt.cnf
-</programlisting>
+[client]
+port=3306
+socket=/tmp/mysql.sock
 
-      <para>
-        To search the directory <filename>/home/mydir</filename> for all
-        files ending in <filename>.cnf</filename> and to read these as
-        option files, you would use:
-      </para>
+[mysqld]
+port=3306
+socket=/tmp/mysql.sock
+key_buffer_size=16M
+max_allowed_packet=8M
 
-<programlisting>
-!includedir /home/mydir
+[mysqldump]
+quick
 </programlisting>
 
       <para>
-        Note that these options are section-specific. For example,
-        suppose that you were to use something in
-        <filename>my.cnf</filename> such as the following:
+        The preceding option file uses
+        <literal><replaceable>var_name</replaceable>=<replaceable>value</replaceable></literal>
+        syntax for the lines that set the
+        <literal>key_buffer_size</literal> and
+        <literal>max_allowed_packet</literal> variables.
       </para>
 
-<programlisting>
-[mysqld]
-!include /home/mydir/myopt.cnf
-</programlisting>
-
       <para>
-        In such a case, the file <filename>myopt.cnf</filename> would be
-        processed only for the server, and the
-        <literal>!include</literal> directive would be ignored by any
-        client applications. However, if you were to use the following:
+        Here is a typical user option file:
       </para>
 
 <programlisting>
-[mysqldump]
-!includedir /home/mydir/my-dump-options
-</programlisting>
+[client]
+# The following password will be sent to all standard MySQL clients
+password="my_password"
 
-      <para>
-        then the directory
-        <filename>/home/mydir/my-dump-options</filename> would be
-        checked for option files ending in <filename>.cnf</filename> by
-        <command>mysqldump</command> only, and not by the server or by
-        any other client applications.
-      </para>
+[mysql]
+no-auto-rehash
+connect_timeout=2
 
-      <para>
-        <emphasis role="bold">Note</emphasis>: Currently, any files to
-        be found and included using the <literal>!includedir</literal>
-        directive on Unix operating systems <emphasis>must</emphasis>
-        have filenames ending in <filename>.cnf</filename>. On Windows,
-        this directive also checks for files with a
-        <filename>.ini</filename> extension (in addition to
-        <filename>.cnf</filename>).
-      </para>
+[mysqlhotcopy]
+interactive-timeout
+</programlisting>
 
       <para>
-        If you want to create option groups that should be read by one
-        specific <command>mysqld</command> server release series only,
-        you can do this by using groups with names of
+        If you want to create option groups that should be read by
+        <command>mysqld</command> servers from a specific MySQL release
+        series only, you can do this by using groups with names of
         <literal>[mysqld-&previous-series;]</literal>,
         <literal>[mysqld-&current-series;]</literal>, and so forth. The
         following group indicates that the <option>--new</option> option
@@ -1084,54 +1088,63 @@
 </programlisting>
 
       <para>
-        Here is a typical global option file:
+        Beginning with MySQL 5.0.4, it is possible to use
+        <literal>!include</literal> directives in option files to
+        include other option files and <literal>!includedir</literal> to
+        search specific directories for option files. For example, to
+        include the <filename>/home/mydir/myopt.cnf</filename> file, you
+        can use the following directive:
       </para>
 
 <programlisting>
-[client]
-port=3306
-socket=/tmp/mysql.sock
+!include /home/me/myopt.cnf
+</programlisting>
 
-[mysqld]
-port=3306
-socket=/tmp/mysql.sock
-key_buffer_size=16M
-max_allowed_packet=8M
+      <para>
+        To search the <filename>/home/mydir</filename> directory and
+        read option files found there, you would use this directive:
+      </para>
 
-[mysqldump]
-quick
+<programlisting>
+!includedir /home/mydir
 </programlisting>
 
       <para>
-        The preceding option file uses
-        <literal><replaceable>var_name</replaceable>=<replaceable>value</replaceable></literal>
-        syntax for the lines that set the
-        <literal>key_buffer_size</literal> and
-        <literal>max_allowed_packet</literal> variables.
+        <emphasis role="bold">Note</emphasis>: Currently, any files to
+        be found and included using the <literal>!includedir</literal>
+        directive on Unix operating systems <emphasis>must</emphasis>
+        have filenames ending in <filename>.cnf</filename>. On Windows,
+        this directive checks for files with the
+        <filename>.ini</filename> or <filename>.cnf</filename>
+        extension.
       </para>
 
       <para>
-        Here is a typical user option file:
+        Note that options read from included files are applied in the
+        context of the current option group. Suppose that you were to
+        write the following lines in <filename>my.cnf</filename>:
       </para>
 
 <programlisting>
-[client]
-# The following password will be sent to all standard MySQL clients
-password="my_password"
+[mysqld]
+!include /home/mydir/myopt.cnf
+</programlisting>
 
-[mysql]
-no-auto-rehash
-connect_timeout=2
+      <para>
+        In this case, the <filename>myopt.cnf</filename> file is
+        processed only for the server, and the
+        <literal>!include</literal> directive is ignored by any client
+        applications. However, if you were to use the following lines,
+        the directory <filename>/home/mydir/my-dump-options</filename>
+        is checked for option files by <command>mysqldump</command>
+        only, and not by the server or by any other client applications:
+      </para>
 
-[mysqlhotcopy]
-interactive-timeout
-
+<programlisting>
+[mysqldump]
+!includedir /home/mydir/my-dump-options
 </programlisting>
 
-      <indexterm type="type">
-        <primary>.my.cnf file</primary>
-      </indexterm>
-
       <para>
         If you have a source distribution, you can find sample option
         files named
@@ -1139,16 +1152,20 @@
         the <filename>support-files</filename> directory. If you have a
         binary distribution, look in the
         <filename>support-files</filename> directory under your MySQL
-        installation directory. On Windows the sample option files may
-        also be located in the MySQL installation directory (see earlier
-        in this section or <xref linkend="installing"/>, if you do not
-        know where this is). Currently there are sample option files for
+        installation directory. On Windows, the sample option files may
+        be located in the MySQL installation directory (see earlier in
+        this section or <xref linkend="installing"/>, if you do not know
+        where this is). Currently, there are sample option files for
         small, medium, large, and very large systems. To experiment with
         one of these files, copy it to <filename>C:\my.cnf</filename> on
         Windows or to <filename>.my.cnf</filename> in your home
         directory on Unix.
       </para>
 
+      <remark role="todo">
+        Is that true for .ini as well?
+      </remark>
+
       <para>
         <emphasis role="bold">Note</emphasis>: On Windows, the
         <filename>.cnf</filename> option file extension might not be
@@ -1157,7 +1174,13 @@
 
       <para>
         All MySQL programs that support option files handle the
-        following command-line options:
+        following options. They affect option-file handling, so they
+        must be given on the command line and not in an option file. To
+        work properly, each of these options must immediately follow the
+        command name, with the exception that
+        <option>--print-defaults</option> may be used immediately after
+        <option>--defaults-file</option> or
+        <option>--defaults-extra-file</option>.
       </para>
 
       <itemizedlist>
@@ -1201,8 +1224,8 @@
           </para>
 
           <para>
-            Read this option file after the global option file but
-            before the user option file.
+            Read this option file after the global option file but (on
+            Unix) before the user option file.
             <replaceable>path_name</replaceable> is the full pathname to
             the file.
           </para>
@@ -1210,14 +1233,6 @@
 
       </itemizedlist>
 
-      <para>
-        To work properly, each of these options must immediately follow
-        the command name on the command line, with the exception that
-        <option>--print-defaults</option> may be used immediately after
-        <option>--defaults-file</option> or
-        <option>--defaults-extra-file</option>.
-      </para>
-
       <remark role="todo">
         The next few paragraphs probably should go into the API chapter.
       </remark>

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