FS_SNAPSHOT_CREATE(2) System Calls Manual FS_SNAPSHOT_CREATE(2)
NAME
fs_snapshot_create – create read only snapshot of a mounted filesystem
SYNOPSIS
#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);
DESCRIPTION
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).
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.
The flags parameter specifies the options that can be passed. only
fs_snapshot_mount() options are currently defined:
SNAPSHOT_MNT_DONTBROWSE File system is not appropriate path to
user data.
SNAPSHOT_MNT_IGNORE_OWNERSHIP Treats all files on the disk as though
they are owned by the current user, no
matter who actually owns them.
SNAPSHOT_MNT_NOFOLLOW Don't follow symlink when resolving mount
point.
RETURN VALUES
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).
COMPATIBILITY
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.
ERRORS
The fs_snapshot_create() , fs_snapshot_delete() , fs_snapshot_rename()
and fs_snapshot_list() function will fail if:
[EACCES] Read permissions are denied for the caller on the
filesystem
[ENOTSUP] The underlying filesystem does not support this call.
[EINVAL] The value of the flags parameter is invalid.
[ENOSPC] There is no free space remaining on the file system
containing the file.
[ENOSPC] The limit for the maximum number of snapshots for a
filesystem has been reached.
[EIO] An I/O error occurred while reading from or writing to
the file system.
[EPERM] The calling process does not have appropriate
privileges.
[EROFS] The requested operation requires modifications in a
read-only file system.
[ENAMETOOLONG] The length of a component of a pathname is longer than
{NAME_MAX}.
[EBADF] dirfd is not a valid file descriptor.
[ENOTDIR] dirfd is a file descriptor associated with a non-
directory file.
In addition, the fs_snapshot_create() or fs_snapshot_rename() functions
may fail with the following errors
[EEXIST] The The named snapshot to be created already exists or
the new name already exists for the snapshot being
renamed.
fs_snapshot_create() or fs_snapshot_rename() functions may fail with the
following errors
[ENOENT] The named snapshot does not exist.
fs_snapshot_delete() function may fail with
[EBUSY] The named snapshot is currently mounted.
SEE ALSO
getattrlist(2), getattrlistbulk(2)
HISTORY
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
Darwin July 4th, 2017 Darwin