Implement copy_file_range()

[ArniDagur]

This closes #941 (see issue for context).

I've decided that it is better for API forwards-compatibility to implement an empty CopyFileRangeFlags enum. I'm not sure how to do this in a good way, however, so please see the commit diff (48c9e6b) and advise me how to do this in a good way, if you'd like. I've also allowed edits from maintainers, so you can make a commit yourself.

[asomers]

This needs a CHANGELOG entry. Also, it needs a test and better documentation. Perhaps a doctest?

[asomers]

How about documenting the rest of the function too, not just flags?

[ArniDagur]

I've been struggling with the testing, so I'm wondering if you could lend a hand.

This code (using explicit file names /tmp/test.txt and /tmp/test2.txt for debugging purposes) works:

        let mut reader = File::open("/tmp/test.txt").unwrap();
        let mut writer = OpenOptions::new().read(true).write(true).truncate(true)
                            .open("/tmp/test2.txt").unwrap();

        let res = copy_file_range(reader.as_raw_fd(), None,
                                  writer.as_raw_fd(), None,
                                  2, CopyFileRangeFlags::empty())
                                  .unwrap();
        assert_eq!(2, res);

As seen here:

[arni@arni-pc][~/OpenSource/nix]% cat /tmp/test.txt
hello world
[arni@arni-pc][~/OpenSource/nix]% cat /tmp/test2.txt
he%      

But when trying to read the contents of /tmp/test2.txt after the copy, no bytes seem to be returned. I tried various methods.

[asomers]

I'm not very familiar with copy_file_range. Does it update the target's seek pointer? If so, that would explain your problem. Try seeking back to zero before reading test2.txt. Also, you'll need to rebase due to some changes to our CI setup.

[ArniDagur]

Superseded by #1069.