1 .\" Copyright (c) 2015 Apple Computer, Inc. All rights reserved.
3 .\" The contents of this file constitute Original Code as defined in and
4 .\" are subject to the Apple Public Source License Version 1.1 (the
5 .\" "License"). You may not use this file except in compliance with the
6 .\" License. Please obtain a copy of the License at
7 .\" http://www.apple.com/publicsource and read it before using this file.
9 .\" This Original Code and all software distributed under the License are
10 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
11 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
12 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
13 .\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
14 .\" License for the specific language governing rights and limitations
15 .\" under the License.
24 .Nd create copy on write clones of files
26 .Fd #include <sys/attr.h>
27 .Fd #include <sys/clonefile.h>
30 .Fn clonefile "const char * src" "const char * dst" "int flags"
32 .Fn clonefileat "int src_dirfd" "const char * src" "int dst_dirfd" "const char * dst" "int flags"
34 .Fn fclonefileat "int srcfd" "int dst_dirfd" "const char * dst" "int flags"
39 function causes the named file
41 to be cloned to the named file
45 shares its data blocks with the
47 file but has its own copy of attributes and extended attributes which are identical to
48 those of the named file
50 with the exceptions listed below
56 ownership information is set as it would be if
64 if the current user does not have privileges to change ownership. If the optional
65 flag CLONE_NOOWNERCOPY is passed, the ownership information is the same as if the
66 the current user does not have privileges to change ownership
70 setuid and setgid bits are turned off in the mode bits for regular files.
73 Subsequent writes to either the original or cloned file are private to the file being modified (copy-on-write).
76 must not exist for the call to be successful. Since the clonefile() system call might not
77 allocate new storage for data blocks, it is possible for a subsequent overwrite of an existing data block to
80 names a directory, the directory hierarchy is cloned as if each item was cloned individually. However, the use of
82 is more appropriate for copying large directory hierarchies instead of
87 function is equivalent to
89 except in the case where either
93 specifies a relative path. If src is a relative path, the file to be cloned is located relative to the directory associated
94 with the file descriptor
96 instead of the current working directory. If
98 is a relative path, the same happens only relative to the directory associated with
102 is passed the special value
108 parameters, the current working directory is used in the determination of the file for
109 the respective path parameter.
113 function is similar to
115 except that the source is identified by file descriptor
117 rather than a path (as in
124 parameter specifies the options that can be passed. Options are specified in the
126 argument by or'ing the following values:
128 .Bl -tag -width CLONE_NOFOLLOW
131 Don't follow the src file if it is a symbolic link (applicable only if the source is not a directory).
132 The symbolic link is itself cloned if
134 names a symbolic link.
138 .Bl -tag -width CLONE_NOOWNERCOPY
140 .It CLONE_NOOWNERCOPY
141 Don't copy ownership information from the source when run called with superuser privileges.
142 The symbolic link is itself cloned if
144 names a symbolic link.
154 functions are expected to be atomic i.e. the system call will result all new objects being created
155 successfully or no new objects will be created. POSIX conforming applications cannot use
159 Upon successful completion,
161 returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.
164 Not all volumes support
166 A volume can be tested for
170 to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_INT_CLONE flag.
175 function will fail if:
179 Read permissions are denied on the source or write permissions are on the destination parent.
182 The underlying filesystem does not support this call.
193 are not on the same filesystem.
198 parameter is invalid.
201 There is no free space remaining on the file system containing the file.
204 An I/O error occurred while reading from or writing to the file system.
207 The calling process does not have appropriate privileges.
211 is the root of the Filesystem.
214 A loop exists in symbolic links encountered during in resolution
222 The requested operation requires writing in a directory on a read-only file system.
224 .It Bq Er ENAMETOOLONG
225 The length of a component of a pathname is longer than {NAME_MAX}.
232 does not name an existing file or path is an empty string.
235 A component of path prefix of either
239 names an existing file that is neither a directory nor a symbolic link to a directory,
240 or the path argument contains at least one non <slash> character and ends with one or
241 more trailing <slash> characters and the last pathname component names an existing file that
242 is neither a directory nor a symbolic link to a directory.
249 functions may fail with the following errors
256 argument does not specify an absolute path and the
262 nor a valid file descriptor open for searching.
269 argument is not an absolute path and
275 nor a file descriptor associated with a directory.
291 function calls appeared in OS X version 10.12
projects / apple / xnu.git / blob