doc: document fs.fdatasync(Sync)

[ronkorving]

Pull Request check-list

Please make sure to review and check all of these items:

• Does make -j8 test (UNIX) or vcbuild test nosign (Windows) pass with
  this change (including linting)?
• Is the commit message formatted according to CONTRIBUTING.md?
• If this change fixes a bug (or a performance problem), is a regression
  test (or a benchmark) included?
• Is a documentation update included (if this change modifies
  existing APIs, or introduces new ones)?

NOTE: these things are not required to open a PR and can be done
afterwards / while the PR is open.

Affected core subsystem(s)

fs

Description of change

The fs.fdatasync and fs.fdatasyncSync APIs are implemented,
but are currently not documented. This adds the documentation.

[rvagg]

Perhaps there's a reason they are not documented? @bnoordhuis@indutny@saghul any ideas? Is there any platform variability in this API that may be worth documenting?

[Fishrock123]

What exactly is this? My Mac doesn't appear to have it. (well, no man page.)

[rvagg]

implemented using fcntl on OSX using F_FULLFSYNC:

 F_FULLFSYNC Does the same thing as fsync(2) then asks the drive to flush all buffered data to the permanent storage device (arg is ignored). This is currently implemented on HFS, MS-DOS (FAT), and Universal Disk Format (UDF) file systems. The operation may take quite a while to complete. Certain FireWire drives have also been known to ignore the request to flush their buffered data. 

fdatasync(2) is:

 fsync() transfers ("flushes") all modified in-core data of (i.e., modified buffer cache pages for) the file referred to by the file descriptor fd to the disk device (or other perma‐ nent storage device) so that all changed information can be retrieved even after the system crashed or was rebooted. This includes writing through or flushing a disk cache if present. The call blocks until the device reports that the transfer has completed. It also flushes metadata information associated with the file (see stat(2)). 

See http://linux.die.net/man/2/fdatasync

Implemented using FlushFileBuffers() on Windows https://msdn.microsoft.com/en-us/library/windows/desktop/aa364439%28v=vs.85%29.aspx

Flushes the buffers of a specified file and causes all buffered data to be written to a file. 

They all seem equivalent to me but perhaps there's some variability that would impact on publicising it.

[ronkorving]

There's a possibility I actually want to use this on a project, so I hope we can make these public.

[saghul]

IIRC they are all equivalent except for the OSX implementation, which is "stronger". Btw, should fdatasync(2) be a link to some online man page?

[ronkorving]

I pretty much copied the fs.fsync(Sync) documentation. So if we want to link, we should probably do that across the board in a separate PR.

As far as I understand it, fdatasync turns into fsync if filesize or file meta data has changed. Or perhaps these days it really is the same. But as long as the syscalls are there, and it's supported by libuv, why not expose it? It's in the OS, and I'm guessing it's not likely to go anywhere.

In any case, are you considering removing it from libuv? If not, I think we can document it for Node.

[bnoordhuis]

Perhaps there's a reason they are not documented?

Don't think so, probably just an oversight. It's been around since at least node.js v0.4.

In any case, are you considering removing it from libuv?

Nope, it's supported and documented.

As far as I understand it, fdatasync turns into fsync if filesize or file meta data has changed.

fdatasync() just flushes data (what you've written), not metadata (access time, modify time, etc.) Changed metadata that has an effect on data (e.g. file size) is flushed, however.

Apropos F_FULLFSYNC, we use that because OS X 10.5 didn't have a fdatasync() system call. We don't support 10.5 anymore so I think we can just switch it over to the real fdatasync().

[bnoordhuis]

Style nit: I think this line is just over 80 columns.

[ronkorving]

81, you're right :)
Will fix. There are more lines in this file beyond 80 chars btw, but that's for another PR.

[bnoordhuis]

LGTM with nit.

[saghul]

Apropos F_FULLFSYNC, we use that because OS X 10.5 didn't have a fdatasync() system call. We don't support 10.5 anymore so I think we can just switch it over to the real fdatasync().

AFAIS there is still no fdatasync in OSX:

$ grep -R fdatasync /usr/include/ /usr/include//python2.6/pyconfig.h:/* Define if you have the 'fdatasync' function. */ /usr/include//python2.6/pyport.h:extern int fdatasync(int); /usr/include//python2.7/pyconfig.h:/* Define if you have the 'fdatasync' function. */ /usr/include//python2.7/pyport.h:extern int fdatasync(int); /usr/include//sys/syscall.h:#define SYS_fdatasync 187 

[bnoordhuis]

There's no libc wrapper, only the system call (i.e. syscall(SYS_fdatasync, fd)).

[saghul]

Yep, I saw that; I guess we can just use the syscall straight.

[rvagg]

well in that case, this lgtm, the details of how it's called on osx are a matter for libuv

[ronkorving]

Nit addressed.

[rvagg]

lgtm

[bnoordhuis]

Thanks Ron, landed in 4578902. I did a git commit --amend --author=... on the commit, you were showing up as Author: ronkorving <...>.

[ronkorving]

Thanks for merging and thanks for the notice. I've changed my git name to "Ron Korving" so this shouldn't happen again.

[MylesBorins]

Is it safe to assume this should be backported?

[rvagg]

yep, please do @thealphanerd