--- name: "fs_snapshot_create" section: "2" platform: "macos" package: "xnu" version: "12377.121.6" release: "macOS 26.5" platforms: ["macos"] url: "https://new.carta.tech/fs_snapshot_create" --- # fs\_snapshot\_create(2) create read only snapshot of a mounted filesystem ## NAME **fs\_snapshot\_create** – create read only snapshot of a mounted filesystem ## SYNOPSIS **#include \** **#include \** *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)](/getattrlistbulk/2.md). 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\_NOEXEC Can't exec from filesystem. - SNAPSHOT\_MNT\_DONTBROWSE File system is not appropriate path to user data. - SNAPSHOT\_MNT\_NOFOLLOW Don't follow symlink when resolving mount point. The SNAPSHOT\_MNT\_NOSUID, SNAPSHOT\_MNT\_NODEV, and SNAPSHOT\_MNT\_IGNORE\_OWNERSHIP options are automatically mirrored based on the presence of these flags in the live filesystem. ## 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)](/getattrlistbulk/2.md). ## COMPATIBILITY Not all volumes support snapshots. A volume can be tested for snapshot support by using [getattrlist(2)](/getattrlist/2.md) 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)](/getattrlist/2.md), [getattrlistbulk(2)](/getattrlistbulk/2.md) ## 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