.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2024 Oxide Computer Company
.\"
.Dd July 13, 2024
.Dt SYNCFS 3C
.Os
.Sh NAME
.Nm syncfs
.Nd synchronize file system to disk
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fo syncfs
.Fa "int fd"
.Fc
.Sh DESCRIPTION
The
.Fn syncfs
function instructs the file system associated with the file descriptor,
.Fa fd ,
to ensure that all pending data and metadata updates that are still
in-memory are synchronized back to the file system's underlying storage
devices.
This function will block until all such writes are completed.
.Pp
Not all file systems support this request.
This may happen either because the file system has not been enhanced yet
to support this request or because the file system does not support the
idea of synchronizing data to a backing store such as the underlying
socket file system or the read-only
.Xr bootfs 4FS
file system.
.Pp
If an application only cares about the state of a single file and its
metadata, then it should use the
.Xr fsync 3C
function instead.
The traditional
.Xr sync 2
function has two primary differences from the
.Fn syncfs function:
.Xr sync 2
instructs the system to schedule all I/O across all file
systems to be synchronized and it does not guarantee that all that
I/O is completed prior to returning.
There is no non-blocking way to force I/O to be synchronized to a
specific file system.
.Sh RETURN VALUES
Upon successful completion, the
.Fn syncfs
function returns
.Sy 0
and ensures that the file system data and metadata synchronization has
already completed.
Otherwise
.Sy -1
is returned
and
.Va errno
is set to indicate the error and outstanding file system data and
metadata is not guaranteed to have been synchronized.
.Sh ERRORS
The
.Fn syncfs
functions will fail if:
.Bl -tag -width Er
.It Er EBADF
The
.Fa fd
argument is not a valid open file descriptor in the calling process.
.It Er EDQUOT, ENOSPC
There was no free space remaining on the file system's backing store or
a quota was hit.
.It Er EIO
An I/O error occurred while reading or writing.
.It Er ENOSYS
The file system backing the file descriptor,
.Fa fd ,
does not support file system-wide synchronization.
.El
.Pp
It is possible that a remote file system
.Pq e.g. NFS
may fail with additional errors that are unique to the network based
nature of the file system.
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy Safe
.Sh SEE ALSO
.Xr sync 2 ,
.Xr fsync 3C