bsd/man/man2/clonefile.2

   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. 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
  67
  68 .
  69 .It
  70 setuid and setgid bits are turned off in the mode bits for regular files.
  71 .El
  72 .Pp
  73 Subsequent writes to either the original or cloned file are private to the file being modified (copy-on-write).
  74 The named file
  75 .Fa dst
  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
  78 return ENOSPC.  If
  79 .Fa src
  80 names a directory, the directory hierarchy is cloned as if each item was cloned individually.  However, the use of
  81 .Xr copyfile 3
  82 is more appropriate for copying large directory hierarchies instead of
  83 .Xr clonefile 2
  84 .Pp
  85 The
  86 .Fn clonefileat
  87 function is equivalent to
  88 .Fn clonefile
  89 except in the case where either
  90 .Fa src
  91 or
  92 .Fa dst
  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
  95 .Fa src_dirfd
  96 instead of the current working directory. If
  97 .Fa dst
  98 is a relative path, the same happens only relative to the directory associated with
  99 .Fa dst_dirfd .
 100 If
 101 .Fn clonefileat
 102 is passed the special value
 103 .Dv AT_FDCWD
 104 in either the
 105 .Fa src_dirfd
 106 or
 107 .Fa dst_dirfd
 108 parameters, the current working directory is used in the determination of the file for
 109 the respective path parameter.
 110 .Pp
 111 The
 112 .Fn fclonefileat
 113 function is similar to
 114 .Fn clonefileat
 115 except that the source is identified by file descriptor
 116 .Fa srcfd
 117 rather than a path (as in
 118 .Fn clonefile
 119 or
 120 .Fn clonefileat )
 121 .Pp
 122 The
 123 .Fa flags
 124 parameter specifies the options that can be passed. Options are specified in the
 125 .Fa flags
 126 argument by or'ing the following values:
 127 .
 128 .Bl -tag -width CLONE_NOFOLLOW
 129 .
 130 .It 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
 133 .Fa src
 134 names a symbolic link.
 135 .
 136 .El
 137 .Pp
 138 .Bl -tag -width CLONE_NOOWNERCOPY
 139 .
 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
 143 .Fa src
 144 names a symbolic link.
 145 .
 146 .El
 147 .Pp
 148 The
 149 The
 150 .Fn clonefile ,
 151 .Fn clonefileat
 152 and
 153 .Fn fclonefileat
 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
 156 .Fn clonefile .
 157 .
 158 .Sh RETURN VALUES
 159 Upon successful completion,
 160 .Fn clonefile
 161 returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.
 162 .Pp
 163 .Sh COMPATIBILITY
 164 Not all volumes support
 165 .Fn clonefile .
 166 A volume can be tested for
 167 .Fn clonefile
 168 support by using
 169 .Xr getattrlist 2
 170 to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_INT_CLONE flag.
 171 .Pp
 172 .Sh ERRORS
 173 The
 174 .Fn clonefile
 175 function will fail if:
 176 .Bl -tag -width Er
 177 .
 178 .It Bq Er EACCES
 179 Read permissions are denied on the source or write permissions are on the destination parent.
 180 .
 181 .It Bq Er ENOTSUP
 182 The underlying filesystem does not support this call.
 183 .
 184 .It Bq Er EEXIST
 185 The named file
 186 .Fa dst
 187 exists.
 188 .
 189 .It Bq Er EXDEV
 190 .Fa src
 191 and
 192 .Fa dst
 193 are not on the same filesystem.
 194 .
 195 .It Bq Er EINVAL
 196 The value of the
 197 .Fa flags
 198 parameter is invalid.
 199 .
 200 .It Bq Er ENOSPC
 201 There is no free space remaining on the file system containing the file.
 202 .
 203 .It Bq Er EIO
 204 An I/O error occurred while reading from or writing to the file system.
 205 .
 206 .It Bq Er EPERM
 207 The calling process does not have appropriate privileges.
 208 .
 209 .It Bq Er EPERM
 210 .Fa src
 211 is the root of the Filesystem.
 212 .
 213 .It Bq Er ELOOP
 214 A loop exists in symbolic links encountered during in resolution
 215 of the
 216 .Fa src
 217 or
 218 .Fa dst
 219 path arguments.
 220 .
 221 .It Bq Er EROFS
 222 The requested operation requires writing in a directory on a read-only file system.
 223 .
 224 .It Bq Er ENAMETOOLONG
 225 The length of a component of a pathname is longer than {NAME_MAX}.
 226 .
 227 .It Bq Er ENOENT
 228 A component of path
 229 .Fa src
 230 or the path
 231 .Fa dst
 232 does not name an existing file or path is an empty string.
 233 .
 234 .It Bq Er ENOTDIR
 235 A component of path prefix of either
 236 .Fa src
 237 or
 238 .Fa dst
 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.
 243 .El
 244 .Pp
 245 In addition, the
 246 .Fn clonefileat
 247 or
 248 .Fn fclonefileat
 249 functions may fail with the following errors
 250 .Bl -tag -width Er
 251 .It Bq Er EBADF
 252 The
 253 .Fa src
 254 or
 255 .Fa dst
 256 argument does not specify an absolute path and the
 257 .Fa src_dirfd
 258 or
 259 .Fa dst_dirfd
 260 argument is neither
 261 .Dv AT_FDCWD
 262 nor a valid file descriptor open for searching.
 263 .
 264 .It Bq Er ENOTDIR
 265 The
 266 .Fa src
 267 or
 268 .Fa dst
 269 argument is not an absolute path and
 270 .Fa src_dirfd
 271 or
 272 .Fa dst_dirfd
 273 is neither
 274 .Dv AT_FDCWD
 275 nor a file descriptor associated with a directory.
 276 .El
 277 .
 278 .Pp
 279 .
 280 .Sh SEE ALSO
 281 .
 282 .Xr copyfile 3
 283 .Xr chown 2
 284 .
 285 .Sh HISTORY
 286 The
 287 .Fn clonefile ,
 288 .Fn clonefileat
 289 and
 290 .Fn fclonefileat
 291 function calls appeared in OS X version 10.12
 292 .