327 lines
8.9 KiB
Groff
327 lines
8.9 KiB
Groff
.\" Copyright (c) 2015 Apple Computer, Inc. All rights reserved.
|
|
.\"
|
|
.\" The contents of this file constitute Original Code as defined in and
|
|
.\" are subject to the Apple Public Source License Version 1.1 (the
|
|
.\" "License"). You may not use this file except in compliance with the
|
|
.\" License. Please obtain a copy of the License at
|
|
.\" http://www.apple.com/publicsource and read it before using this file.
|
|
.\"
|
|
.\" This Original Code and all software distributed under the License are
|
|
.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
|
|
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
|
|
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
|
|
.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
|
|
.\" License for the specific language governing rights and limitations
|
|
.\" under the License.
|
|
.\"
|
|
.\" @(#)clonefile.2
|
|
.
|
|
.Dd June 3, 2021
|
|
.Dt CLONEFILE 2
|
|
.Os Darwin
|
|
.Sh NAME
|
|
.Nm clonefile
|
|
.Nd create copy on write clones of files
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/attr.h>
|
|
.Fd #include <sys/clonefile.h>
|
|
.Pp
|
|
.Ft int
|
|
.Fn clonefile "const char * src" "const char * dst" "int flags"
|
|
.
|
|
.Fn clonefileat "int src_dirfd" "const char * src" "int dst_dirfd" "const char * dst" "int flags"
|
|
.
|
|
.Fn fclonefileat "int srcfd" "int dst_dirfd" "const char * dst" "int flags"
|
|
.
|
|
.Sh LIMITATIONS
|
|
Cloning directories with these functions is strongly discouraged. Use
|
|
.Xr copyfile 3
|
|
to clone directories instead.
|
|
.
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn clonefile
|
|
function causes the named file
|
|
.Fa src
|
|
to be cloned to the named file
|
|
.Fa dst .
|
|
The cloned file
|
|
.Fa dst
|
|
shares its data blocks with the
|
|
.Fa src
|
|
file but has its own copy of attributes and extended attributes which are identical to
|
|
those of the named file
|
|
.Fa src
|
|
with the exceptions listed below:
|
|
.Pp
|
|
.
|
|
.Bl -enum
|
|
.
|
|
.It
|
|
ownership information is set as it would be if
|
|
.Fa dst
|
|
was created by
|
|
.Xr openat 2
|
|
or
|
|
.Xr mkdirat 2
|
|
or
|
|
.Xr symlinkat 2
|
|
if the current user does not have privileges to change ownership. If the optional
|
|
flag CLONE_NOOWNERCOPY is passed, the ownership information is the same as if the
|
|
the current user does not have privileges to change ownership.
|
|
.
|
|
.It
|
|
setuid and setgid bits are turned off in the mode bits for regular files.
|
|
.It
|
|
inherit target directory's access control lists. If the optional flag CLONE_ACL is passed, it will additionally
|
|
copy the ACLs from the source file and also apply the inherited ACLs from the target directory.
|
|
.El
|
|
.Pp
|
|
Subsequent writes to either the original or cloned file are private to the file being modified (copy-on-write).
|
|
The named file
|
|
.Fa dst
|
|
must not exist for the call to be successful. Since the clonefile() system call might not
|
|
allocate new storage for data blocks, it is possible for a subsequent overwrite of an existing data block to
|
|
return ENOSPC. If
|
|
.Fa src
|
|
names a directory, the directory hierarchy is cloned as if each item was cloned individually. However, the use of
|
|
.Xr clonefile 2
|
|
to clone directory hierarchies is strongly discouraged. Use
|
|
.Xr copyfile 3
|
|
instead for copying directories.
|
|
.Pp
|
|
The
|
|
.Fn clonefileat
|
|
function is equivalent to
|
|
.Fn clonefile
|
|
except in the case where either
|
|
.Fa src
|
|
or
|
|
.Fa dst
|
|
specifies a relative path. If src is a relative path, the file to be cloned is located relative to the directory associated
|
|
with the file descriptor
|
|
.Fa src_dirfd
|
|
instead of the current working directory. If
|
|
.Fa dst
|
|
is a relative path, the same happens only relative to the directory associated with
|
|
.Fa dst_dirfd .
|
|
If
|
|
.Fn clonefileat
|
|
is passed the special value
|
|
.Dv AT_FDCWD
|
|
in either the
|
|
.Fa src_dirfd
|
|
or
|
|
.Fa dst_dirfd
|
|
parameters, the current working directory is used in the determination of the file for
|
|
the respective path parameter.
|
|
.Pp
|
|
The
|
|
.Fn fclonefileat
|
|
function is similar to
|
|
.Fn clonefileat
|
|
except that the source is identified by file descriptor
|
|
.Fa srcfd
|
|
rather than a path (as in
|
|
.Fn clonefile
|
|
or
|
|
.Fn clonefileat
|
|
).
|
|
.Pp
|
|
The
|
|
.Fa flags
|
|
parameter specifies the options that can be passed. Options are specified in the
|
|
.Fa flags
|
|
argument by or'ing the following values:
|
|
.
|
|
.Bl -tag -width CLONE_NOFOLLOW
|
|
.
|
|
.It CLONE_NOFOLLOW
|
|
Don't follow the src file if it is a symbolic link (applicable only if the source is not a directory).
|
|
The symbolic link is itself cloned if
|
|
.Fa src
|
|
names a symbolic link.
|
|
.
|
|
.El
|
|
.Pp
|
|
.Bl -tag -width CLONE_NOOWNERCOPY
|
|
.
|
|
.It CLONE_NOOWNERCOPY
|
|
Don't copy ownership information from the source when run called with superuser privileges.
|
|
The symbolic link is itself cloned if
|
|
.Fa src
|
|
names a symbolic link.
|
|
.
|
|
.El
|
|
.Pp
|
|
.Bl -tag -width CLONE_ACL
|
|
.
|
|
.It CLONE_ACL
|
|
Copy ACLs from the source file.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn clonefile ,
|
|
.Fn clonefileat
|
|
and
|
|
.Fn fclonefileat
|
|
functions are expected to be atomic i.e. the system call will result all new objects being created
|
|
successfully or no new objects will be created. POSIX conforming applications cannot use
|
|
.Fn clonefile .
|
|
.
|
|
.Sh RETURN VALUES
|
|
Upon successful completion,
|
|
.Fn clonefile
|
|
returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.
|
|
.Pp
|
|
.Sh COMPATIBILITY
|
|
Not all volumes support
|
|
.Fn clonefile .
|
|
A volume can be tested for
|
|
.Fn clonefile
|
|
support by using
|
|
.Xr getattrlist 2
|
|
to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_INT_CLONE flag.
|
|
.Pp
|
|
.Sh ERRORS
|
|
The
|
|
.Fn clonefile
|
|
function will fail if:
|
|
.Bl -tag -width Er
|
|
.
|
|
.It Bq Er EACCES
|
|
Read permissions are denied on the source or write permissions are on the destination parent.
|
|
.
|
|
.It Bq Er ENOTSUP
|
|
The underlying filesystem does not support this call.
|
|
.
|
|
.It Bq Er EEXIST
|
|
The named file
|
|
.Fa dst
|
|
exists.
|
|
.
|
|
.It Bq Er EXDEV
|
|
.Fa src
|
|
and
|
|
.Fa dst
|
|
are not on the same filesystem.
|
|
.
|
|
.It Bq Er EINVAL
|
|
The value of the
|
|
.Fa flags
|
|
parameter is invalid.
|
|
.
|
|
.It Bq Er ENOSPC
|
|
There is no free space remaining on the file system containing the file.
|
|
.
|
|
.It Bq Er EIO
|
|
An I/O error occurred while reading from or writing to the file system.
|
|
.
|
|
.It Bq Er EPERM
|
|
The calling process does not have appropriate privileges.
|
|
.
|
|
.It Bq Er EPERM
|
|
.Fa src
|
|
is the root of the Filesystem.
|
|
.
|
|
.It Bq Er ELOOP
|
|
A loop exists in symbolic links encountered during in resolution
|
|
of the
|
|
.Fa src
|
|
or
|
|
.Fa dst
|
|
path arguments.
|
|
.
|
|
.It Bq Er EROFS
|
|
The requested operation requires writing in a directory on a read-only file system.
|
|
.
|
|
.It Bq Er ENAMETOOLONG
|
|
The length of a component of a pathname is longer than {NAME_MAX}.
|
|
.
|
|
.It Bq Er ENOENT
|
|
A component of path
|
|
.Fa src
|
|
or the path
|
|
.Fa dst
|
|
does not name an existing file or path is an empty string.
|
|
.
|
|
.It Bq Er ENOTDIR
|
|
A component of path prefix of either
|
|
.Fa src
|
|
or
|
|
.Fa dst
|
|
names an existing file that is neither a directory nor a symbolic link to a directory,
|
|
or the path argument contains at least one non <slash> character and ends with one or
|
|
more trailing <slash> characters and the last pathname component names an existing file that
|
|
is neither a directory nor a symbolic link to a directory.
|
|
.
|
|
.It Bq Er EDEADLK
|
|
A component of either pathname refers to a
|
|
.Dq dataless
|
|
directory that requires materialization and the I/O policy of the current
|
|
thread or process disallows dataless directory materialization
|
|
.Po see
|
|
.Xr getiopolicy_np 3
|
|
.Pc .
|
|
.
|
|
.It Bq Er EDEADLK
|
|
The
|
|
.Fa src
|
|
pathname refers to a
|
|
.Dq dataless
|
|
file that must be materialized before being cloned and the I/O policy of
|
|
the current thread or process disallows file materialization
|
|
.Po see
|
|
.Xr getiopolicy_np 3
|
|
.Pc .
|
|
.El
|
|
.Pp
|
|
In addition, the
|
|
.Fn clonefileat
|
|
or
|
|
.Fn fclonefileat
|
|
functions may fail with the following errors:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EBADF
|
|
The
|
|
.Fa src
|
|
or
|
|
.Fa dst
|
|
argument does not specify an absolute path and the
|
|
.Fa src_dirfd
|
|
or
|
|
.Fa dst_dirfd
|
|
argument is neither
|
|
.Dv AT_FDCWD
|
|
nor a valid file descriptor open for searching.
|
|
.
|
|
.It Bq Er ENOTDIR
|
|
The
|
|
.Fa src
|
|
or
|
|
.Fa dst
|
|
argument is not an absolute path and
|
|
.Fa src_dirfd
|
|
or
|
|
.Fa dst_dirfd
|
|
is neither
|
|
.Dv AT_FDCWD
|
|
nor a file descriptor associated with a directory.
|
|
.
|
|
.El
|
|
.
|
|
.Pp
|
|
.
|
|
.Sh SEE ALSO
|
|
.
|
|
.Xr copyfile 3
|
|
.Xr chown 2
|
|
.
|
|
.Sh HISTORY
|
|
The
|
|
.Fn clonefile ,
|
|
.Fn clonefileat
|
|
and
|
|
.Fn fclonefileat
|
|
function calls appeared in OS X version 10.12
|
|
.
|