<!-- 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>
