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