Docs: clarify availability of fdatasync

- fdatasync is apparently an undocumented system call on OS X. It is not
  exposed in the headers, resulting in an implicit function declaration
  warning. It links, however, and there are no complaints about it being
  broken, so I am leaving it alone for now.
- fdatasync is available on Linux and apparently FreeBSD. This leaves
  Windows as the only major platform supported by Lwt that does not have
  fdatasync.

As a side note, fsync on OS X seems not to guarantee that data has
actually reached disk. We may need to add a call fnctl(fd, F_FULLSYNC)
to the implementation of Lwt_unix.fsync on OS X.

src/unix/lwt_unix.ml

@@ -693,6 +693,10 @@ let ftruncate ch offset =
    | File system synchronisation                                     |
    +-----------------------------------------------------------------+ *)
 
+(* fdatasync appears to be an undocumented system call on OS X. It is detected
+   during configuration of Lwt, and seems to work for now. However, it may break
+   if we make implicit function declaration an error, or in other
+   circumstances. *)
 let fdatasync ch =
   check_descriptor ch;
   run_job (Jobs.fdatasync_job ch.fd)

src/unix/lwt_unix.mli

@@ -419,7 +419,7 @@ val fdatasync : file_descr -> unit Lwt.t
   (** Synchronise all data (but not metadata) of the file descriptor
       with the disk.
 
-      Note that [fdatasync] is not available on all platforms. *)
+      Note that [fdatasync] is not available on Windows. *)
 
 (** {2 File status} *)
 

tests/unix/test_lwt_unix.ml

@@ -60,4 +60,16 @@ let suite = suite "lwt_unix" [
         | Unix.Unix_error (Unix.ENOENT, "utimes", _) -> Lwt.return_unit
         | e -> Lwt.fail e) >>= fun () ->
       Lwt.return_true);
+
+  (* Test that fdatasync remains available on OS X when it is detected. See
+     comment by implementation of Lwt_unix.fdatasync. *)
+  test ~only_if:(fun () -> Lwt_sys.have `fdatasync) "fdatasync: basic"
+    (fun () ->
+      let temporary_file = temp_file () in
+
+      Lwt_unix.(openfile temporary_file [O_WRONLY] 0) >>= fun fd ->
+      Lwt.finalize
+        (fun () -> Lwt_unix.fdatasync fd)
+        (fun () -> Lwt_unix.close fd) >>= fun () ->
+      Lwt.return_true);
 ]