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 54function: 55.Xr sync 2 56instructs the system to schedule all I/O across all file 57systems to be synchronized and it does not guarantee that all that 58I/O is completed prior to returning. 59There is no non-blocking way to force I/O to be synchronized to a 60specific file system. 61.Sh RETURN VALUES 62Upon successful completion, the 63.Fn syncfs 64function returns 65.Sy 0 66and ensures that the file system data and metadata synchronization has 67already completed. 68Otherwise 69.Sy -1 70is returned 71and 72.Va errno 73is set to indicate the error and outstanding file system data and 74metadata is not guaranteed to have been synchronized. 75.Sh ERRORS 76The 77.Fn syncfs 78functions will fail if: 79.Bl -tag -width Er 80.It Er EBADF 81The 82.Fa fd 83argument is not a valid open file descriptor in the calling process. 84.It Er EDQUOT, ENOSPC 85There was no free space remaining on the file system's backing store or 86a quota was hit. 87.It Er EIO 88An I/O error occurred while reading or writing. 89.It Er ENOSYS 90The file system backing the file descriptor, 91.Fa fd , 92does not support file system-wide synchronization. 93.El 94.Pp 95It is possible that a remote file system 96.Pq e.g. NFS 97may fail with additional errors that are unique to the network based 98nature of the file system. 99.Sh INTERFACE STABILITY 100.Sy Committed 101.Sh MT-LEVEL 102.Sy Safe 103.Sh SEE ALSO 104.Xr sync 2 , 105.Xr fsync 3C 106