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, syncfs 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
-         for more information about using
-        syncfs().
+        file systems that may be reachable through symbolic links).  This may
+        be a lot faster than the fsync 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
+        PostgreSQL, and relevant error messages may
+        appear only in kernel logs.
        
        
         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 @@
 
 
 
-
 
 
 

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;
 
  

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, syncfs 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
-        syncfs"/> for more information about using
-        syncfs()>.
+        guc-recovery-init-sync-method"/> for information about
+        the caveats to be aware of when using syncfs>.
        
        
         This option has no effect when --no-sync 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,
         pg_basebackup will also synchronize the file systems
         that contain the WAL files and each tablespace.  See
-        syncfs"/> for more information about using
-        syncfs()>.
+        guc-recovery-init-sync-method"/> for information about
+        the caveats to be aware of when using syncfs>.
        
        
         This option has no effect when --no-sync 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, syncfs 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
-        syncfs"/> for more information about using
-        syncfs()>.
+        guc-recovery-init-sync-method"/> for information about
+        the caveats to be aware of when using syncfs>.
        
        
         This option has no effect when --no-sync 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,
         pg_combinebackup will also synchronize the file systems
         that contain the WAL files and each tablespace.  See
-        syncfs"/> for more information about using
-        syncfs()>.
+        guc-recovery-init-sync-method"/> for information about
+        the caveats to be aware of when using syncfs>.
        
        
         This option has no effect when --no-sync 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
        
         On Linux, syncfs may be used instead to ask the
         operating system to synchronize the whole file system that contains the
-        archive directory.  See  for more information
-        about using syncfs().
+        archive directory.  See 
+        for information about the caveats to be aware of when using
+        syncfs.
        
        
         This option has no effect when --no-sync 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, syncfs 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
-        syncfs"/> for more information about using
-        syncfs()>.
+        guc-recovery-init-sync-method"/> for information about
+        the caveats to be aware of when using syncfs>.
        
        
         This option has no effect when --no-sync 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, syncfs 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 syncfs"/> for more information about using
-        syncfs()>.
+        See guc-recovery-init-sync-method"/> for information
+        about the caveats to be aware of when using syncfs>.
        
        
         This option has no effect when --no-sync 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 @@
-
-
-
- <function>syncfs()</function> Caveats
-
- 
-  syncfs
- 
-
- 
-  On Linux syncfs() may be specified for some
-  configuration parameters (e.g.,
-  ), server applications (e.g.,
-  pg_upgrade), and client applications (e.g.,
-  pg_basebackup) that involve synchronizing many
-  files to disk.  syncfs() is advantageous in many cases,
-  but there are some trade-offs to keep in mind.
- 
-
- 
-  Since syncfs() instructs the operating system to
-  synchronize a whole file system, it typically requires many fewer system
-  calls than using fsync() to synchronize each file one by
-  one.  Therefore, using syncfs() may be a lot faster than
-  using fsync().  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.
- 
-
- 
-  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.
- 
-
-