]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright (c) 2015 Apple Computer, Inc. All rights reserved. | |
2 | .\" | |
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. | |
8 | .\" | |
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. | |
16 | .\" | |
17 | .\" @(#)clonefile.2 | |
18 | . | |
19 | .Dd December 04, 2015 | |
20 | .Dt CLONEFILE 2 | |
21 | .Os Darwin | |
22 | .Sh NAME | |
23 | .Nm clonefile | |
24 | .Nd create copy on write clones of files | |
25 | .Sh SYNOPSIS | |
26 | .Fd #include <sys/attr.h> | |
27 | .Fd #include <sys/clonefile.h> | |
28 | .Pp | |
29 | .Ft int | |
30 | .Fn clonefile "const char * src" "const char * dst" "int flags" | |
31 | . | |
32 | .Fn clonefileat "int src_dirfd" "const char * src" "int dst_dirfd" "const char * dst" "int flags" | |
33 | . | |
34 | .Fn fclonefileat "int srcfd" "int dst_dirfd" "const char * dst" "int flags" | |
35 | . | |
36 | .Sh DESCRIPTION | |
37 | The | |
38 | .Fn clonefile | |
39 | function causes the named file | |
40 | .Fa src | |
41 | to be cloned to the named file | |
42 | .Fa dst . | |
43 | The cloned file | |
44 | .Fa dst | |
45 | shares its data blocks with the | |
46 | .Fa src | |
47 | file but has its own copy of attributes, extended attributes and ACL's which are identical to | |
48 | those of the named file | |
49 | .Fa src | |
50 | with the exceptions listed below | |
51 | .Pp | |
52 | . | |
53 | .Bl -enum | |
54 | . | |
55 | .It | |
56 | ownership information is set as it would be if | |
57 | .Fa dst | |
58 | was created by | |
59 | .Xr openat 2 | |
60 | or | |
61 | .Xr mkdirat 2 | |
62 | or | |
63 | .Xr symlinkat 2 | |
64 | if the current user does not have privileges to change ownership. | |
65 | ||
66 | . | |
67 | .It | |
68 | setuid and setgid bits are turned off in the mode bits for regular files. | |
69 | .El | |
70 | .Pp | |
71 | Subsequent writes to either the original or cloned file are private to the file being modified (copy-on-write). | |
72 | The named file | |
73 | .Fa dst | |
74 | must not exist for the call to be successful. Since the clonefile() system call might not | |
75 | allocate new storage for data blocks, it is possible for a subsequent overwrite of an existing data block to | |
76 | return ENOSPC. If | |
77 | .Fa src | |
78 | names a directory, the directory hierarchy is cloned as if each item was cloned individually. However, the use of | |
79 | .Xr copyfile 3 | |
80 | is more appropriate for copying large directory hierarchies instead of | |
81 | .Xr clonefile 2 | |
82 | .Pp | |
83 | The | |
84 | .Fn clonefileat | |
85 | function is equivalent to | |
86 | .Fn clonefile | |
87 | except in the case where either | |
88 | .Fa src | |
89 | or | |
90 | .Fa dst | |
91 | specifies a relative path. If src is a relative path, the file to be cloned is located relative to the directory associated | |
92 | with the file descriptor | |
93 | .Fa src_dirfd | |
94 | instead of the current working directory. If | |
95 | .Fa dst | |
96 | is a relative path, the same happens only relative to the directory associated with | |
97 | .Fa dst_dirfd . | |
98 | If | |
99 | .Fn clonefileat | |
100 | is passed the special value | |
101 | .Dv AT_FDCWD | |
102 | in either the | |
103 | .Fa src_dirfd | |
104 | or | |
105 | .Fa dst_dirfd | |
106 | parameters, the current working directory is used in the determination of the file for | |
107 | the respective path parameter. | |
108 | .Pp | |
109 | The | |
110 | .Fn fclonefileat | |
111 | function is similar to | |
112 | .Fn clonefileat | |
113 | except that the source is identified by file descriptor | |
114 | .Fa srcfd | |
115 | rather than a path (as in | |
116 | .Fn clonefile | |
117 | or | |
118 | .Fn clonefileat ) | |
119 | .Pp | |
120 | The | |
121 | .Fa flags | |
122 | parameter specifies the options that can be passed. Options are specified in the | |
123 | .Fa flags | |
124 | argument by or'ing the following values: | |
125 | . | |
126 | .Bl -tag -width CLONE_NOFOLLOW | |
127 | . | |
128 | .It CLONE_NOFOLLOW | |
129 | Don't follow the src file if it is a symbolic link (applicable only if the source is not a directory). | |
130 | The symbolic link is itself cloned if | |
131 | .Fa src | |
132 | names a symbolic link. | |
133 | . | |
134 | .El | |
135 | .Pp | |
136 | The | |
137 | .Fn clonefile , | |
138 | .Fn clonefileat | |
139 | and | |
140 | .Fn fclonefileat | |
141 | functions are expected to be atomic i.e. the system call will result all new objects being created | |
142 | successfully or no new objects will be created. POSIX conforming applications cannot use | |
143 | .Fn clonefile . | |
144 | . | |
145 | .Sh RETURN VALUES | |
146 | Upon successful completion, | |
147 | .Fn clonefile | |
148 | returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error. | |
149 | .Pp | |
150 | .Sh COMPATIBILITY | |
151 | Not all volumes support | |
152 | .Fn clonefile . | |
153 | A volume can be tested for | |
154 | .Fn clonefile | |
155 | support by using | |
156 | .Xr getattrlist 2 | |
157 | to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_INT_CLONE flag. | |
158 | .Pp | |
159 | .Sh ERRORS | |
160 | The | |
161 | .Fn clonefile | |
162 | function will fail if: | |
163 | .Bl -tag -width Er | |
164 | . | |
165 | .It Bq Er EACCES | |
166 | Read permissions are denied on the source or write permissions are on the destination parent. | |
167 | . | |
168 | .It Bq Er ENOTSUP | |
169 | The underlying filesystem does not support this call. | |
170 | . | |
171 | .It Bq Er EEXIST | |
172 | The named file | |
173 | .Fa dst | |
174 | exists. | |
175 | . | |
176 | .It Bq Er EXDEV | |
177 | .Fa src | |
178 | and | |
179 | .Fa dst | |
180 | are not on the same filesystem. | |
181 | . | |
182 | .It Bq Er EINVAL | |
183 | The value of the | |
184 | .Fa flags | |
185 | parameter is invalid. | |
186 | . | |
187 | .It Bq Er ENOSPC | |
188 | There is no free space remaining on the file system containing the file. | |
189 | . | |
190 | .It Bq Er EIO | |
191 | An I/O error occurred while reading from or writing to the file system. | |
192 | . | |
193 | .It Bq Er EPERM | |
194 | The calling process does not have appropriate privileges. | |
195 | . | |
196 | .It Bq Er EPERM | |
197 | .Fa src | |
198 | is the root of the Filesystem. | |
199 | . | |
200 | .It Bq Er ELOOP | |
201 | A loop exists in symbolic links encountered during in resolution | |
202 | of the | |
203 | .Fa src | |
204 | or | |
205 | .Fa dst | |
206 | path arguments. | |
207 | . | |
208 | .It Bq Er EROFS | |
209 | The requested operation requires writing in a directory on a read-only file system. | |
210 | . | |
211 | .It Bq Er ENAMETOOLONG | |
212 | The length of a component of a pathname is longer than {NAME_MAX}. | |
213 | . | |
214 | .It Bq Er ENOENT | |
215 | A component of path | |
216 | .Fa src | |
217 | or the path | |
218 | .Fa dst | |
219 | does not name an existing file or path is an empty string. | |
220 | . | |
221 | .It Bq Er ENOTDIR | |
222 | A component of path prefix of either | |
223 | .Fa src | |
224 | or | |
225 | .Fa dst | |
226 | names an existing file that is neither a directory nor a symbolic link to a directory, | |
227 | or the path argument contains at least one non <slash> character and ends with one or | |
228 | more trailing <slash> characters and the last pathname component names an existing file that | |
229 | is neither a directory nor a symbolic link to a directory. | |
230 | .El | |
231 | .Pp | |
232 | In addition, the | |
233 | .Fn clonefileat | |
234 | or | |
235 | .Fn fclonefileat | |
236 | functions may fail with the following errors | |
237 | .Bl -tag -width Er | |
238 | .It Bq Er EBADF | |
239 | The | |
240 | .Fa src | |
241 | or | |
242 | .Fa dst | |
243 | argument does not specify an absolute path and the | |
244 | .Fa src_dirfd | |
245 | or | |
246 | .Fa dst_dirfd | |
247 | argument is neither | |
248 | .Dv AT_FDCWD | |
249 | nor a valid file descriptor open for searching. | |
250 | . | |
251 | .It Bq Er ENOTDIR | |
252 | The | |
253 | .Fa src | |
254 | or | |
255 | .Fa dst | |
256 | argument is not an absolute path and | |
257 | .Fa src_dirfd | |
258 | or | |
259 | .Fa dst_dirfd | |
260 | is neither | |
261 | .Dv AT_FDCWD | |
262 | nor a file descriptor associated with a directory. | |
263 | .El | |
264 | . | |
265 | .Pp | |
266 | . | |
267 | .Sh SEE ALSO | |
268 | . | |
269 | .Xr copyfile 3 | |
270 | .Xr chown 2 | |
271 | . | |
272 | .Sh HISTORY | |
273 | The | |
274 | .Fn clonefile , | |
275 | .Fn clonefileat | |
276 | and | |
277 | .Fn fclonefileat | |
278 | function calls appeared in OS X version 10.12 | |
279 | . |