Open Radar

 
The copyfile.h header has the following disclaimer:

/*
 * this is an API to faciliatate copying of files and their
 * associated metadata.  There are several open source projects that
 * need modifications to support preserving extended attributes and
 * acls and this API collapses several hundred lines of modifications
 * into one or two calls.
 *
 * This implementation is incomplete and the interface may change in a 
 * future release.
 */

which seems to indicate it's not safe to rely on. It's also marked as /* version 0.1 */ which also seems to indicate it's incompleteness.

However the FSCopyObjectAsync API Reference recommends using copyfile(): "At the POSIX/BSD layer, use copyfile(3) OS X Developer Tools Manual Page instead."

The man page doesn't make any reference to the API being incomplete.

Using copyfile(), it seems functional and, from what I understand, NSFileManager is built on top of it, so my best guess is that this header is just out of date.

If it is incomplete, the man page should say so and it shouldn't be recommended as an FS API replacement.

Notes:
copyfile.h from the 10.8 SDK: http://cl.ly/code/1e2y2g1b0p3Q
FSCopyObjectAsync API Reference: https://developer.apple.com/library/mac/#documentation/Carbon/Reference/File_Manager/DeprecationAppendix/AppendixADeprecatedAPI.html#//apple_ref/c/func/FSCopyObjectAsync