From f6a363a50d024e3805145de1e7c7b79f1886c5c8 Mon Sep 17 00:00:00 2001
From: Alan Somers <asomers@FreeBSD.org>
Date: Fri, 22 Mar 2019 18:42:34 +0000
Subject: [PATCH] Add man page for VOP_FDATASYNC(9)

Reviewed by:	kib
MFC after:	2 weeks
Sponsored by:	The FreeBSD Foundation
Differential Revision:	https://reviews.freebsd.org/D19678
---
 share/man/man9/Makefile    |  1 +
 share/man/man9/VOP_FSYNC.9 | 27 +++++++++++++++++++++++----
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index bd816bf519fa..6eb5ee9e7983 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -2233,6 +2233,7 @@ MLINKS+=VOP_ATTRIB.9 VOP_GETATTR.9 \
 MLINKS+=VOP_CREATE.9 VOP_MKDIR.9 \
 	VOP_CREATE.9 VOP_MKNOD.9 \
 	VOP_CREATE.9 VOP_SYMLINK.9
+MLINKS+=VOP_FSYNC.9 VOP_FDATASYNC.9
 MLINKS+=VOP_GETPAGES.9 VOP_PUTPAGES.9
 MLINKS+=VOP_INACTIVE.9 VOP_RECLAIM.9
 MLINKS+=VOP_LOCK.9 vn_lock.9 \
diff --git a/share/man/man9/VOP_FSYNC.9 b/share/man/man9/VOP_FSYNC.9
index 76e114ff6099..f59312a0d7cb 100644
--- a/share/man/man9/VOP_FSYNC.9
+++ b/share/man/man9/VOP_FSYNC.9
@@ -28,20 +28,27 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 24, 1996
+.Dd March 22, 2019
 .Dt VOP_FSYNC 9
 .Os
 .Sh NAME
+.Nm VOP_FDATASYNC ,
 .Nm VOP_FSYNC
 .Nd flush file system buffers for a file
 .Sh SYNOPSIS
 .In sys/param.h
 .In sys/vnode.h
 .Ft int
+.Fn VOP_FDATASYNC "struct vnode *vp" "struct thread *td"
+.Ft int
 .Fn VOP_FSYNC "struct vnode *vp" "int waitfor" "struct thread *td"
 .Sh DESCRIPTION
-This call flushes any dirty file system buffers for the file.
-It is used to implement the
+.Fn VOP_FSYNC
+ensures that a file can be recovered to its current state following a crash.
+That typically requires flushing the file's dirty buffers, its inode, and
+possibly other filesystem metadata to persistent media.
+.Fn VOP_FSYNC
+is used to implement the
 .Xr sync 2
 and
 .Xr fsync 2
@@ -65,8 +72,20 @@ Push data not written by file system syncer.
 .It Fa td
 The calling thread.
 .El
+.Pp
+.Fn VOP_FDATASYNC
+is similar, but it does not require that all of the file's metadata be flushed.
+It only requires that the file's data be recoverable after a crash.
+That implies that the data itself must be flushed to disk, as well as some
+metadata such as the file's size but not necessarily its attributes.
+.Fn VOP_FDATASYNC
+should always wait for I/O to complete, as if called with
+.Dv MNT_WAIT .
+.Fn VOP_FDATASYNC
+is used to implement
+.Xr fdatasync 2 .
 .Sh LOCKS
-The file should be locked on entry.
+The vnode should be exclusively locked on entry, and stays locked on return.
 .Sh RETURN VALUES
 Zero is returned if the call is successful, otherwise an appropriate
 error code is returned.