1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2024 Oxide Computer Company 13.\" 14.Dd July 13, 2024 15.Dt SYNCFS 3C 16.Os 17.Sh NAME 18.Nm syncfs 19.Nd synchronize file system to disk 20.Sh LIBRARY 21.Lb libc 22.Sh SYNOPSIS 23.In unistd.h 24.Ft int 25.Fo syncfs 26.Fa "int fd" 27.Fc 28.Sh DESCRIPTION 29The 30.Fn syncfs 31function instructs the file system associated with the file descriptor, 32.Fa fd , 33to ensure that all pending data and metadata updates that are still 34in-memory are synchronized back to the file system's underlying storage 35devices. 36This function will block until all such writes are completed. 37.Pp 38Not all file systems support this request. 39This may happen either because the file system has not been enhanced yet 40to support this request or because the file system does not support the 41idea of synchronizing data to a backing store such as the underlying 42socket file system or the read-only 43.Xr bootfs 4FS 44file system. 45.Pp 46If an application only cares about the state of a single file and its 47metadata, then it should use the 48.Xr fsync 3C 49function instead. 50The traditional 51.Xr sync 2 52function has two primary differences from the 53.Fn syncfs function: 54.Xr sync 2 55instructs the system to schedule all I/O across all file 56systems to be synchronized and it does not guarantee that all that 57I/O is completed prior to returning. 58There is no non-blocking way to force I/O to be synchronized to a 59specific file system. 60.Sh RETURN VALUES 61Upon successful completion, the 62.Fn syncfs 63function returns 64.Sy 0 65and ensures that the file system data and metadata synchronization has 66already completed. 67Otherwise 68.Sy -1 69is returned 70and 71.Va errno 72is set to indicate the error and outstanding file system data and 73metadata is not guaranteed to have been synchronized. 74.Sh ERRORS 75The 76.Fn syncfs 77functions will fail if: 78.Bl -tag -width Er 79.It Er EBADF 80The 81.Fa fd 82argument is not a valid open file descriptor in the calling process. 83.It Er EDQUOT, ENOSPC 84There was no free space remaining on the file system's backing store or 85a quota was hit. 86.It Er EIO 87An I/O error occurred while reading or writing. 88.It Er ENOSYS 89The file system backing the file descriptor, 90.Fa fd , 91does not support file system-wide synchronization. 92.El 93.Pp 94It is possible that a remote file system 95.Pq e.g. NFS 96may fail with additional errors that are unique to the network based 97nature of the file system. 98.Sh INTERFACE STABILITY 99.Sy Committed 100.Sh MT-LEVEL 101.Sy Safe 102.Sh SEE ALSO 103.Xr sync 2 , 104.Xr fsync 3C 105