svn commit: r304287 - head/lib/libc/sys

[Konstantin Belousov]

Author: kib
Date: Wed Aug 17 10:16:42 2016
New Revision: 304287
URL: https://svnweb.freebsd.org/changeset/base/304287

Log:
  Add fdatasync(2) man page, combined with fsync(2).
  
  Reviewed by:	emaste, rpokala, wblock
  Sponsored by:	The FreeBSD Foundation
  MFC after:	2 weeks
  Differential revision:	https://reviews.freebsd.org/D7522

Modified:
  head/lib/libc/sys/Makefile.inc
  head/lib/libc/sys/fsync.2

Modified: head/lib/libc/sys/Makefile.inc
==============================================================================
--- head/lib/libc/sys/Makefile.inc	Wed Aug 17 10:14:22 2016	(r304286)
+++ head/lib/libc/sys/Makefile.inc	Wed Aug 17 10:16:42 2016	(r304287)
@@ -366,6 +366,7 @@ MLINKS+=ffclock.2 ffclock_getcounter.2 \
 	ffclock.2 ffclock_getestimate.2 \
 	ffclock.2 ffclock_setestimate.2
 MLINKS+=fhopen.2 fhstat.2 fhopen.2 fhstatfs.2
+MLINKS+=fsync.2 fdatasync.2
 MLINKS+=getdirentries.2 getdents.2
 MLINKS+=getfh.2 lgetfh.2
 MLINKS+=getgid.2 getegid.2

Modified: head/lib/libc/sys/fsync.2
==============================================================================
--- head/lib/libc/sys/fsync.2	Wed Aug 17 10:14:22 2016	(r304286)
+++ head/lib/libc/sys/fsync.2	Wed Aug 17 10:16:42 2016	(r304287)
@@ -1,5 +1,11 @@
 .\" Copyright (c) 1983, 1993
 .\"	The Regents of the University of California.  All rights reserved.
+.\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" Parts of this documentation were written by
+.\" Konstantin Belousov <kib at FreeBSD.org> under sponsorship
+.\" from the FreeBSD Foundation.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -28,40 +34,65 @@
 .\"     @(#)fsync.2	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd June 4, 1993
+.Dd August 17, 2016
 .Dt FSYNC 2
 .Os
 .Sh NAME
-.Nm fsync
+.Nm fdatasync, fsync
 .Nd "synchronise changes to a file"
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In unistd.h
 .Ft int
+.Fn fdatasync "int fd"
+.Ft int
 .Fn fsync "int fd"
 .Sh DESCRIPTION
 The
 .Fn fsync
 system call
-causes all modified data and attributes of
+causes all modified data and attributes of the file referenced by
+the file descriptor
 .Fa fd
 to be moved to a permanent storage device.
 This normally results in all in-core modified copies
 of buffers for the associated file to be written to a disk.
 .Pp
 The
+.Fn fdatasync
+system call causes all modified data of
+.Fa fd
+to be moved to a permanent storage device.
+Unlike
+.Fn fsync ,
+the system call does not guarantee that file attributes or
+metadata necessary to access the file are committed to the permanent storage.
+.Pp
+The
 .Fn fsync
 system call
 should be used by programs that require a file to be
 in a known state, for example, in building a simple transaction
 facility.
+If the file metadata has already been committed, using
+.Fn fdatasync
+can be more efficient than
+.Fn fsync .
+.Pp
+Both
+.Fn fdatasync
+and
+.Fn fsync
+calls are cancellation points.
 .Sh RETURN VALUES
 .Rv -std fsync
 .Sh ERRORS
 The
 .Fn fsync
-fails if:
+and
+.Fn fdatasync
+calls fail if:
 .Bl -tag -width Er
 .It Bq Er EBADF
 The
@@ -85,3 +116,15 @@ The
 .Fn fsync
 system call appeared in
 .Bx 4.2 .
+The
+.Fn fdatasync
+system call appeared in
+.Fx 12.0
+.Sh BUGS
+The
+.Fn fdatasync
+system call currently does not guarantee that enqueued
+.Xr aio 4
+requests for the file referenced by
+.Fa fd
+are completed before the syscall returns.