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