man2/sync.2

   1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   2 .\" and Copyright (c) 2011 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified by Michael Haardt <michael@moria.de>
   7 .\" Modified Sat Jul 24 12:02:47 1993 by Rik Faith <faith@cs.unc.edu>
   8 .\" Modified 15 Apr 1995 by Michael Chastain <mec@shell.portal.com>:
   9 .\"   Added reference to `bdflush(2)'.
  10 .\" Modified 960414 by Andries Brouwer <aeb@cwi.nl>:
  11 .\"   Added the fact that since 1.3.20 sync actually waits.
  12 .\" Modified Tue Oct 22 22:27:07 1996 by Eric S. Raymond <esr@thyrsus.com>
  13 .\" Modified 2001-10-10 by aeb, following Michael Kerrisk.
  14 .\" 2011-09-07, mtk, Added syncfs() documentation,
  15 .\"
  16 .TH SYNC 2 2021-03-22 "Linux man-pages (unreleased)"
  17 .SH NAME
  18 sync, syncfs \- commit filesystem caches to disk
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <unistd.h>
  25 .PP
  26 .B void sync(void);
  27 .PP
  28 .BI "int syncfs(int " fd );
  29 .fi
  30 .PP
  31 .RS -4
  32 Feature Test Macro Requirements for glibc (see
  33 .BR feature_test_macros (7)):
  34 .RE
  35 .PP
  36 .BR sync ():
  37 .nf
  38     _XOPEN_SOURCE >= 500
  39 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  40         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  41         || /* Glibc <= 2.19: */ _BSD_SOURCE
  42 .fi
  43 .PP
  44 .BR syncfs ():
  45 .nf
  46     _GNU_SOURCE
  47 .fi
  48 .SH DESCRIPTION
  49 .BR sync ()
  50 causes all pending modifications to filesystem metadata and cached file
  51 data to be written to the underlying filesystems.
  52 .PP
  53 .BR syncfs ()
  54 is like
  55 .BR sync (),
  56 but synchronizes just the filesystem containing file
  57 referred to by the open file descriptor
  58 .IR fd .
  59 .SH RETURN VALUE
  60 .BR syncfs ()
  61 returns 0 on success;
  62 on error, it returns \-1 and sets
  63 .I errno
  64 to indicate the error.
  65 .SH ERRORS
  66 .BR sync ()
  67 is always successful.
  68 .PP
  69 .BR syncfs ()
  70 can fail for at least the following reasons:
  71 .TP
  72 .B EBADF
  73 .I fd
  74 is not a valid file descriptor.
  75 .TP
  76 .B EIO
  77 An error occurred during synchronization.
  78 This error may relate to data written to any file on the filesystem, or on
  79 metadata related to the filesystem itself.
  80 .TP
  81 .B ENOSPC
  82 Disk space was exhausted while synchronizing.
  83 .TP
  84 .BR ENOSPC ", " EDQUOT
  85 Data was written to a file on NFS or another filesystem which does not
  86 allocate space at the time of a
  87 .BR write (2)
  88 system call, and some previous write failed due to insufficient
  89 storage space.
  90 .SH VERSIONS
  91 .BR syncfs ()
  92 first appeared in Linux 2.6.39;
  93 library support was added to glibc in version 2.14.
  94 .SH STANDARDS
  95 .BR sync ():
  96 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
  97 .PP
  98 .BR syncfs ()
  99 is Linux-specific.
 100 .SH NOTES
 101 Since glibc 2.2.2, the Linux prototype for
 102 .BR sync ()
 103 is as listed above,
 104 following the various standards.
 105 In glibc 2.2.1 and earlier,
 106 it was "int sync(void)", and
 107 .BR sync ()
 108 always returned 0.
 109 .PP
 110 According to the standard specification (e.g., POSIX.1-2001),
 111 .BR sync ()
 112 schedules the writes, but may return before the actual
 113 writing is done.
 114 However Linux waits for I/O completions,
 115 and thus
 116 .BR sync ()
 117 or
 118 .BR syncfs ()
 119 provide the same guarantees as
 120 .BR fsync ()
 121 called on every file in
 122 the system or filesystem respectively.
 123 .PP
 124 In mainline kernel versions prior to 5.8,
 125 .BR syncfs ()
 126 will fail only when passed a bad file descriptor
 127 .RB ( EBADF ).
 128 Since Linux 5.8,
 129 .\" commit 735e4ae5ba28c886d249ad04d3c8cc097dad6336
 130 .BR syncfs ()
 131 will also report an error if one or more inodes failed
 132 to be written back since the last
 133 .BR syncfs ()
 134 call.
 135 .SH BUGS
 136 Before version 1.3.20 Linux did not wait for I/O to complete
 137 before returning.
 138 .SH SEE ALSO
 139 .BR sync (1),
 140 .BR fdatasync (2),
 141 .BR fsync (2)