FS_SNAPSHOT_CREATE(2) | System Calls Manual | FS_SNAPSHOT_CREATE(2) |
fs_snapshot_create
—
create read only snapshot of a mounted
filesystem
#include
<sys/attr.h>
#include <sys/snapshot.h>
int
fs_snapshot_create
(int
dirfd, const char *
name, uint32_t
flags);
int
fs_snapshot_delete
(int
dirfd, const char *
name, uint32_t
flags);
int
fs_snapshot_list
(int
dirfd, struct attrlist *
name, void *
attrbuf, size_t
bufsize, uint32_t
flags);
int
fs_snapshot_rename
(int
dirfd, const char *
old, const char *
new, uint32_t
flags);
int
fs_snapshot_mount
(int
dirfd, const char *
dir, const char *
snapshot, uint32_t
flags);
int
fs_snapshot_revert
(int
dirfd, const char *
name, uint32_t
flags);
The
fs_snapshot_create
()
function, for supported Filesystems, causes a snapshot of the Filesystem to
be created. A snapshot is a read only copy of the filesystem frozen at a
point in time. The Filesystem is identified by the
dirfd parameter which should be a file descriptor
associated with the root directory of the filesystem for which the snapshot
is to be created. name can be any valid name for a
component name (except . and ..). The
fs_snapshot_delete
()
function causes the named snapshot name to be deleted
and the
fs_snapshot_rename
()
function causes the named snapshot old to be renamed
to the name new. Available snapshots along with their
attributes can be listed by calling
fs_snapshot_list
()
which is to be used in exactly the same way as
getattrlistbulk(2). The flags
parameter specifies the options that can be passed. No options are currently
defined.
Snapshots may be useful for backing up the
Filesystem and to restore the Filesystem to a previous state. Snapshots are
expected to consume no additional storage on creation but might consume
additional storage as the active Filesystem is modified. Similarly deletion
of files on the active filesystem may not result in the storage being
available if the snapshot contains the file. Additionally, the underlying
Filesystem may impose a limit on the number of snapshots that can be taken.
For supporting Filesystems, a snapshot may be used as a source for a mount.
This can be done by the
fs_snapshot_mount
()
function. The snapshot will be mounted read only. When a snapshot is
mounted, it cannot be deleted but it can be renamed. To revert the
filesystem to a previous snapshot, the
fs_snapshot_revert
()
can be used. It should be noted that reverting a filesystem to a snapshot is
a destructive operation and causes all changes made to the filesystem
(including snapshots created after the snapshot being reverted to) to be
lost.
All snapshot functions require superuser privileges and also require an additional entitlement.
Upon successful completion,
fs_snapshot_create
() ,
fs_snapshot_delete
() and
fs_snapshot_rename
() returns 0. Otherwise, a value
of -1 is returned and errno is set to indicate the error.
fs_snapshot_list
() returns the number of entries
successfully read. A return value of 0 indicates there are no more entries.
Otherwise, a value of -1 is returned and errno is set to indicate the error.
Return values are the same as getattrlistbulk(2).
Not all volumes support snapshots. A volume can be tested for snapshot support by using getattrlist(2) to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_INT_SNAPSHOT flag.
The fs_snapshot_create
() ,
fs_snapshot_delete
() ,
fs_snapshot_rename
() and
fs_snapshot_list
() function will fail if:
EACCES
]ENOTSUP
]EINVAL
]ENOSPC
]ENOSPC
]EIO
]EPERM
]EROFS
]ENAMETOOLONG
]EBADF
]ENOTDIR
]In addition, the fs_snapshot_create
() or
fs_snapshot_rename
() functions may fail with the
following errors
EEXIST
]fs_snapshot_create
() or
fs_snapshot_rename
() functions may fail with the
following errors
ENOENT
]fs_snapshot_delete
() function may fail
with
EBUSY
]The fs_snapshot_create
() ,
fs_snapshot_delete
() ,
fs_snapshot_list
() ,
fs_snapshot_mount
() ,
fs_snapshot_rename
() and
fs_snapshot_revert
() function calls appeared in
macOS version 10.13
July 4th, 2017 | Darwin |