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.
  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 .