WT-2200 Edit wording of direct_io docs, don't allow write_through on read-only checkpoints.

3 files changed, 39 insertions, 44 deletions

diff --git a/dist/api_data.py b/dist/api_data.py
index 87c66ec161b..9afff74ca71 100644
--- a/dist/api_data.py
+++ b/dist/api_data.py
@@ -594,17 +594,16 @@ wiredtiger_open_common = connection_runtime_config + [
         checkpoints''',
         type='boolean'),
     Config('direct_io', '', r'''
-        Use \c O_DIRECT on Posix systems, and FILE_FLAG_NO_BUFFERING on Windows
-        to access files.  Options are given as a list,
-        such as <code>"direct_io=[data]"</code>.  Configuring
-        \c direct_io requires care, see @ref
-        tuning_system_buffer_cache_direct_io for important warnings.
-        Including \c "data" will cause WiredTiger data files to use
-        \c O_DIRECT, including \c "log" will cause WiredTiger log files
-        to use \c O_DIRECT, and including \c "checkpoint" will cause
-        WiredTiger data files opened at a checkpoint (i.e: read only) to
-        use \c O_DIRECT. It should be combined with write_through to get the
-        equivalent of O_DIRECT on Windows.''',
+        Use \c O_DIRECT on POSIX systems, and \c FILE_FLAG_NO_BUFFERING on
+        Windows to access files.  Options are given as a list, such as
+        <code>"direct_io=[data]"</code>.  Configuring \c direct_io requires
+        care, see @ref tuning_system_buffer_cache_direct_io for important
+        warnings.  Including \c "data" will cause WiredTiger data files to use
+        direct I/O, including \c "log" will cause WiredTiger log files to use
+        direct I/O, and including \c "checkpoint" will cause WiredTiger data
+        files opened at a checkpoint (i.e: read only) to use direct I/O.
+        \c direct_io should be combined with \c write_through to get the
+        equivalent of \c O_DIRECT on Windows.''',
         type='list', choices=['checkpoint', 'data', 'log']),
     Config('encryption', '', r'''
         configure an encryptor for system wide metadata and logs.
@@ -677,18 +676,16 @@ wiredtiger_open_common = connection_runtime_config + [
             choices=['dsync', 'fsync', 'none']),
         ]),
     Config('write_through', '', r'''
-        Use \c FILE_FLAG_WRITE_THROUGH on Windows to write to files.
-        Options are given as a list,
-        such as <code>"write_through=[data]"</code>.  Configuring
-        \c write_through requires care, see @ref
-        tuning_system_buffer_cache_direct_io for important warnings.
-        Including \c "data" will cause WiredTiger data files to use
-        \c FILE_FLAG_WRITE_THROUGH, including \c "log" will cause WiredTiger log
-        files to use \c FILE_FLAG_WRITE_THROUGH, and including \c "checkpoint"
-        will cause WiredTiger data files opened at a checkpoint (i.e: read only)
-        to use \c FILE_FLAG_WRITE_THROUGH. It should be combined with
-        direct_io to get the equivalent of O_DIRECT on Windows.''',
-        type='list', choices=['checkpoint', 'data', 'log']),
+        Use \c FILE_FLAG_WRITE_THROUGH on Windows to write to files.  Ignored
+        on non-Windows systems.  Options are given as a list, such as
+        <code>"write_through=[data]"</code>.  Configuring \c write_through
+        requires care, see @ref tuning_system_buffer_cache_direct_io for
+        important warnings.  Including \c "data" will cause WiredTiger data
+        files to write through cache, including \c "log" will cause WiredTiger
+        log files to write through cache. \c write_through should be combined
+        with \c direct_io to get the equivalent of POSIX \c O_DIRECT on
+        Windows.''',
+        type='list', choices=['data', 'log']),
 ]
 
 wiredtiger_open = wiredtiger_open_common + [
diff --git a/src/config/config_def.c b/src/config/config_def.c
index 15cc99ea7af..311ddd56b7a 100644
--- a/src/config/config_def.c
+++ b/src/config/config_def.c
@@ -553,7 +553,7 @@ static const WT_CONFIG_CHECK confchk_wiredtiger_open[] = {
 	    "\"write\"]",
 	    NULL, 0 },
 	{ "write_through", "list",
-	    NULL, "choices=[\"checkpoint\",\"data\",\"log\"]",
+	    NULL, "choices=[\"data\",\"log\"]",
 	    NULL, 0 },
 	{ NULL, NULL, NULL, NULL, NULL, 0 }
 };
@@ -633,7 +633,7 @@ static const WT_CONFIG_CHECK confchk_wiredtiger_open_all[] = {
 	    NULL, 0 },
 	{ "version", "string", NULL, NULL, NULL, 0 },
 	{ "write_through", "list",
-	    NULL, "choices=[\"checkpoint\",\"data\",\"log\"]",
+	    NULL, "choices=[\"data\",\"log\"]",
 	    NULL, 0 },
 	{ NULL, NULL, NULL, NULL, NULL, 0 }
 };
@@ -708,7 +708,7 @@ static const WT_CONFIG_CHECK confchk_wiredtiger_open_basecfg[] = {
 	    NULL, 0 },
 	{ "version", "string", NULL, NULL, NULL, 0 },
 	{ "write_through", "list",
-	    NULL, "choices=[\"checkpoint\",\"data\",\"log\"]",
+	    NULL, "choices=[\"data\",\"log\"]",
 	    NULL, 0 },
 	{ NULL, NULL, NULL, NULL, NULL, 0 }
 };
@@ -782,7 +782,7 @@ static const WT_CONFIG_CHECK confchk_wiredtiger_open_usercfg[] = {
 	    "\"write\"]",
 	    NULL, 0 },
 	{ "write_through", "list",
-	    NULL, "choices=[\"checkpoint\",\"data\",\"log\"]",
+	    NULL, "choices=[\"data\",\"log\"]",
 	    NULL, 0 },
 	{ NULL, NULL, NULL, NULL, NULL, 0 }
 };
diff --git a/src/include/wiredtiger.in b/src/include/wiredtiger.in
index f954ebe1967..3e975a0c05a 100644
--- a/src/include/wiredtiger.in
+++ b/src/include/wiredtiger.in
@@ -2130,17 +2130,17 @@ struct __wt_connection {
  * true.}
  * @config{create, create the database if it does not exist., a boolean flag;
  * default \c false.}
- * @config{direct_io, Use \c O_DIRECT on Posix systems\, and
+ * @config{direct_io, Use \c O_DIRECT on POSIX systems\, and \c
  * FILE_FLAG_NO_BUFFERING on Windows to access files.  Options are given as a
  * list\, such as <code>"direct_io=[data]"</code>. Configuring \c direct_io
  * requires care\, see @ref tuning_system_buffer_cache_direct_io for important
- * warnings.  Including \c "data" will cause WiredTiger data files to use \c
- * O_DIRECT\, including \c "log" will cause WiredTiger log files to use \c
- * O_DIRECT\, and including \c "checkpoint" will cause WiredTiger data files
- * opened at a checkpoint (i.e: read only) to use \c O_DIRECT. It should be
- * combined with write_through to get the equivalent of O_DIRECT on Windows., a
- * list\, with values chosen from the following options: \c "checkpoint"\, \c
- * "data"\, \c "log"; default empty.}
+ * warnings.  Including \c "data" will cause WiredTiger data files to use direct
+ * I/O\, including \c "log" will cause WiredTiger log files to use direct I/O\,
+ * and including \c "checkpoint" will cause WiredTiger data files opened at a
+ * checkpoint (i.e: read only) to use direct I/O. \c direct_io should be
+ * combined with \c write_through to get the equivalent of \c O_DIRECT on
+ * Windows., a list\, with values chosen from the following options: \c
+ * "checkpoint"\, \c "data"\, \c "log"; default empty.}
  * @config{encryption = (, configure an encryptor for system wide metadata and
  * logs.  If a system wide encryptor is set\, it is also used for encrypting
  * data files and tables\, unless encryption configuration is explicitly set for
@@ -2342,16 +2342,14 @@ struct __wt_connection {
  * "shared_cache"\, \c "split"\, \c "temporary"\, \c "transaction"\, \c
  * "verify"\, \c "version"\, \c "write"; default empty.}
  * @config{write_through, Use \c FILE_FLAG_WRITE_THROUGH on Windows to write to
- * files.  Options are given as a list\, such as
- * <code>"write_through=[data]"</code>. Configuring \c write_through requires
+ * files.  Ignored on non-Windows systems.  Options are given as a list\, such
+ * as <code>"write_through=[data]"</code>. Configuring \c write_through requires
  * care\, see @ref tuning_system_buffer_cache_direct_io for important warnings.
- * Including \c "data" will cause WiredTiger data files to use \c
- * FILE_FLAG_WRITE_THROUGH\, including \c "log" will cause WiredTiger log files
- * to use \c FILE_FLAG_WRITE_THROUGH\, and including \c "checkpoint" will cause
- * WiredTiger data files opened at a checkpoint (i.e: read only) to use \c
- * FILE_FLAG_WRITE_THROUGH. It should be combined with direct_io to get the
- * equivalent of O_DIRECT on Windows., a list\, with values chosen from the
- * following options: \c "checkpoint"\, \c "data"\, \c "log"; default empty.}
+ * Including \c "data" will cause WiredTiger data files to write through cache\,
+ * including \c "log" will cause WiredTiger log files to write through cache It
+ * should be combined with direct_io to get the equivalent of POSIX \c O_DIRECT
+ * on Windows., a list\, with values chosen from the following options: \c
+ * "data"\, \c "log"; default empty.}
  * @configend
  * Additionally, if files named \c WiredTiger.config or \c WiredTiger.basecfg
  * appear in the WiredTiger home directory, they are read for configuration