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