Adjust documentation for syncfs().

Commit 8c16ad3b43 created a new appendix for syncfs(), which is
excessive for such a small amount of content.  This commit moves
the description of the caveats to be aware of when using syncfs()
back to the documentation for recovery_init_sync_method.  The
documentation for the other utilities with syncfs() support now
directs readers to recovery_init_sync_method for information about
these caveats.

Reported-by: Peter Eisentraut, Robert Haas
Suggested-by: Robert Haas
Reviewed-by: Robert Haas
Discussion: https://postgr.es/m/42804669-7063-1320-ed37-3226d5f1067d%40eisentraut.org
Discussion: https://postgr.es/m/CA%2BTgmobUiqKr%2BZMCLc5Qap-sXBnjfGUU%2BZBmzYEjUuWyjsGr1g%40mail.gmail.com

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 65a6e6c4086c00095f14285ec64bdc8113959cd4..5468637e2ef3dbcca5cfaf539c881714f707f0e0 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -10870,9 +10870,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
         On Linux, <literal>syncfs</literal> may be used instead, to ask the
         operating system to synchronize the file systems that contain the
         data directory, the WAL files and each tablespace (but not any other
-        file systems that may be reachable through symbolic links).  See
-        <xref linkend="syncfs"/> for more information about using
-        <function>syncfs()</function>.
+        file systems that may be reachable through symbolic links).  This may
+        be a lot faster than the <literal>fsync</literal> setting, because it
+        doesn't need to open each file one by one.  On the other hand, it may
+        be slower if a file system is shared by other applications that
+        modify a lot of files, since those files will also be written to disk.
+        Furthermore, on versions of Linux before 5.8, I/O errors encountered
+        while writing data to disk may not be reported to
+        <productname>PostgreSQL</productname>, and relevant error messages may
+        appear only in kernel logs.
        </para>
        <para>
         This parameter can only be set in the

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index e0dca81cb2e39c81a3a0907aa9be032d39af20f0..c92a16c7ac724f828ee35e9f2ab854045bda73d1 100644 (file)
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -182,7 +182,6 @@
 <!ENTITY acronyms   SYSTEM "acronyms.sgml">
 <!ENTITY glossary   SYSTEM "glossary.sgml">
 <!ENTITY color      SYSTEM "color.sgml">
-<!ENTITY syncfs     SYSTEM "syncfs.sgml">
 
 <!ENTITY features-supported   SYSTEM "features-supported.sgml">
 <!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 2c107199d306391f9558e976888506b3d8d2312e..381af69be287395df23bbce16e59fd0abb2fdbc5 100644 (file)
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -289,7 +289,6 @@ break is not needed in a wider output rendering.
   &acronyms;
   &glossary;
   &color;
-  &syncfs;
   &obsolete;
 
  </part>

diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 377c3cb20aa156f49342243da63ddefe7fe966c6..dc9011b40ed3e977fe195fa0a8bb311ef9802a58 100644 (file)
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -394,8 +394,8 @@ PostgreSQL documentation
         On Linux, <literal>syncfs</literal> may be used instead to ask the
         operating system to synchronize the whole file systems that contain the
         data directory, the WAL files, and each tablespace.  See
-        <xref linkend="syncfs"/> for more information about using
-        <function>syncfs()</function>.
+        <xref linkend="guc-recovery-init-sync-method"/> for information about
+        the caveats to be aware of when using <literal>syncfs</literal>.
        </para>
        <para>
         This option has no effect when <option>--no-sync</option> is used.

diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 208530f393ab6ce2d445747d144e670559a43084..82d0c8e0088d2441e9622e180c7e001acd39c628 100644 (file)
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -642,8 +642,8 @@ PostgreSQL documentation
         backup directory.  When the plain format is used,
         <command>pg_basebackup</command> will also synchronize the file systems
         that contain the WAL files and each tablespace.  See
-        <xref linkend="syncfs"/> for more information about using
-        <function>syncfs()</function>.
+        <xref linkend="guc-recovery-init-sync-method"/> for information about
+        the caveats to be aware of when using <literal>syncfs</literal>.
        </para>
        <para>
         This option has no effect when <option>--no-sync</option> is used.

diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml
index db5b29505cd39d40513a7cdc4622c2cdf339840e..95043aa329c020937936851500c95dd0ad97639c 100644 (file)
--- a/doc/src/sgml/ref/pg_checksums.sgml
+++ b/doc/src/sgml/ref/pg_checksums.sgml
@@ -152,8 +152,8 @@ PostgreSQL documentation
         On Linux, <literal>syncfs</literal> may be used instead to ask the
         operating system to synchronize the whole file systems that contain the
         data directory, the WAL files, and each tablespace.  See
-        <xref linkend="syncfs"/> for more information about using
-        <function>syncfs()</function>.
+        <xref linkend="guc-recovery-init-sync-method"/> for information about
+        the caveats to be aware of when using <literal>syncfs</literal>.
        </para>
        <para>
         This option has no effect when <option>--no-sync</option> is used.

diff --git a/doc/src/sgml/ref/pg_combinebackup.sgml b/doc/src/sgml/ref/pg_combinebackup.sgml
index 8a0a600c2b2685b966a44e6bf033b2db2bcf637c..6f90dba281ffd60e868bf2bb63d6f46eaaa1b4c8 100644 (file)
--- a/doc/src/sgml/ref/pg_combinebackup.sgml
+++ b/doc/src/sgml/ref/pg_combinebackup.sgml
@@ -176,8 +176,8 @@ PostgreSQL documentation
         backup directory.  When the plain format is used,
         <command>pg_combinebackup</command> will also synchronize the file systems
         that contain the WAL files and each tablespace.  See
-        <xref linkend="syncfs"/> for more information about using
-        <function>syncfs()</function>.
+        <xref linkend="guc-recovery-init-sync-method"/> for information about
+        the caveats to be aware of when using <literal>syncfs</literal>.
        </para>
        <para>
         This option has no effect when <option>--no-sync</option> is used.

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 8edf03a03df3876f2bc60fdf4419d585c7307477..b99793e414885455012c9883e6d0e17c2d5abbed 100644 (file)
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1319,8 +1319,9 @@ PostgreSQL documentation
        <para>
         On Linux, <literal>syncfs</literal> may be used instead to ask the
         operating system to synchronize the whole file system that contains the
-        archive directory.  See <xref linkend="syncfs"/> for more information
-        about using <function>syncfs()</function>.
+        archive directory.  See <xref linkend="guc-recovery-init-sync-method"/>
+        for information about the caveats to be aware of when using
+        <literal>syncfs</literal>.
        </para>
        <para>
         This option has no effect when <option>--no-sync</option> is used or

diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index 841bd49fc748190eea30bb7f7dc260040a120e12..dc039d875665a9c0a8b4c19bc6a6e28e96aef7b6 100644 (file)
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -297,8 +297,8 @@ PostgreSQL documentation
         On Linux, <literal>syncfs</literal> may be used instead to ask the
         operating system to synchronize the whole file systems that contain the
         data directory, the WAL files, and each tablespace.  See
-        <xref linkend="syncfs"/> for more information about using
-        <function>syncfs()</function>.
+        <xref linkend="guc-recovery-init-sync-method"/> for information about
+        the caveats to be aware of when using <literal>syncfs</literal>.
        </para>
        <para>
         This option has no effect when <option>--no-sync</option> is used.

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 8de52bf752738c50f3ed5443241bf61c1ea1a297..80a50377b1d9be42897bb1130e2f5525f74d3498 100644 (file)
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -204,8 +204,8 @@ PostgreSQL documentation
         On Linux, <literal>syncfs</literal> may be used instead to ask the
         operating system to synchronize the whole file systems that contain the
         upgraded cluster's data directory, its WAL files, and each tablespace.
-        See <xref linkend="syncfs"/> for more information about using
-        <function>syncfs()</function>.
+        See <xref linkend="guc-recovery-init-sync-method"/> for information
+        about the caveats to be aware of when using <literal>syncfs</literal>.
        </para>
        <para>
         This option has no effect when <option>--no-sync</option> is used.

diff --git a/doc/src/sgml/syncfs.sgml b/doc/src/sgml/syncfs.sgml
deleted file mode 100644 (file)
index 00457d2..0000000
--- a/doc/src/sgml/syncfs.sgml
+++ /dev/null
@@ -1,36 +0,0 @@
-<!-- doc/src/sgml/syncfs.sgml -->
-
-<appendix id="syncfs">
- <title><function>syncfs()</function> Caveats</title>
-
- <indexterm zone="syncfs">
-  <primary>syncfs</primary>
- </indexterm>
-
- <para>
-  On Linux <function>syncfs()</function> may be specified for some
-  configuration parameters (e.g.,
-  <xref linkend="guc-recovery-init-sync-method"/>), server applications (e.g.,
-  <application>pg_upgrade</application>), and client applications (e.g.,
-  <application>pg_basebackup</application>) that involve synchronizing many
-  files to disk.  <function>syncfs()</function> is advantageous in many cases,
-  but there are some trade-offs to keep in mind.
- </para>
-
- <para>
-  Since <function>syncfs()</function> instructs the operating system to
-  synchronize a whole file system, it typically requires many fewer system
-  calls than using <function>fsync()</function> to synchronize each file one by
-  one.  Therefore, using <function>syncfs()</function> may be a lot faster than
-  using <function>fsync()</function>.  However, it may be slower if a file
-  system is shared by other applications that modify a lot of files, since
-  those files will also be written to disk.
- </para>
-
- <para>
-  Furthermore, on versions of Linux before 5.8, I/O errors encountered while
-  writing data to disk may not be reported to the calling program, and relevant
-  error messages may appear only in kernel logs.
- </para>
-
-</appendix>