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 ‘<literal>=</literal>’ 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
‘<literal>#</literal>’ 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> <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
‘<literal>\b</literal>’,
@@ -958,18 +1001,21 @@
</para>
<para>
- On Windows, if an option value represents a pathname, you should
+ Because the ‘<literal>\\</literal>’ escape sequence
+ represents a single backslash, you must write each
+ ‘<literal>\</literal>’ as
+ ‘<literal>\\</literal>’. Alternatively, you can
specify the value using ‘<literal>/</literal>’
rather than ‘<literal>\</literal>’ as the pathname
- separator. If you use ‘<literal>\</literal>’, you
- must double it as ‘<literal>\\</literal>’, because
- ‘<literal>\</literal>’ 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 ‘<literal>=</literal>’ 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
‘<literal>#</literal>’ 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
- ‘<literal>=</literal>’ 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> <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 ‘<literal>\\</literal>’ escape sequence
+ represents a single backslash, you must write each
+ ‘<literal>\</literal>’ as
+ ‘<literal>\\</literal>’. Alternatively, you can
specify the value using ‘<literal>/</literal>’
rather than ‘<literal>\</literal>’ as the pathname
- separator. If you use ‘<literal>\</literal>’, you
- must double it as ‘<literal>\\</literal>’, because
- ‘<literal>\</literal>’ 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-¤t-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 ‘<literal>=</literal>’ 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
‘<literal>#</literal>’ 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
- ‘<literal>=</literal>’ 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> <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 ‘<literal>\\</literal>’ escape sequence
+ represents a single backslash, you must write each
+ ‘<literal>\</literal>’ as
+ ‘<literal>\\</literal>’. Alternatively, you can
specify the value using ‘<literal>/</literal>’
rather than ‘<literal>\</literal>’ as the pathname
- separator. If you use ‘<literal>\</literal>’, you
- must double it as ‘<literal>\\</literal>’, because
- ‘<literal>\</literal>’ 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-¤t-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.1 | paul | 6 Jan |
