1.\" Copyright (c) 2017-2018 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.\" @(#)fs_snapshot_create.2 18. 19.Dd July 4th, 2017 20.Dt FS_SNAPSHOT_CREATE 2 21.Os Darwin 22.Sh NAME 23.Nm fs_snapshot_create 24.Nd create read only snapshot of a mounted filesystem 25.Sh SYNOPSIS 26.Fd #include <sys/attr.h> 27.Fd #include <sys/snapshot.h> 28.Pp 29.Ft int 30.Fn fs_snapshot_create "int dirfd" "const char * name" "uint32_t flags" 31. 32.Ft int 33.Fn fs_snapshot_delete "int dirfd" "const char * name" "uint32_t flags" 34. 35.Ft int 36.Fn fs_snapshot_list "int dirfd" "struct attrlist * name" "void * attrbuf" "size_t bufsize" "uint32_t flags" 37. 38.Ft int 39.Fn fs_snapshot_rename "int dirfd" "const char * old" "const char * new" "uint32_t flags" 40. 41.Ft int 42.Fn fs_snapshot_mount "int dirfd" "const char * dir" "const char * snapshot" "uint32_t flags" 43. 44.Ft int 45.Fn fs_snapshot_revert "int dirfd" "const char * name" "uint32_t flags" 46. 47.Sh DESCRIPTION 48The 49.Fn fs_snapshot_create 50function, for supported Filesystems, causes a snapshot of the Filesystem to be created. A snapshot is a read only copy 51of the filesystem frozen at a point in time. The Filesystem is identified by the 52.Fa dirfd 53parameter which should be a file descriptor associated with the root directory of the filesystem for which the snapshot is to be created. 54.Fa name 55can be any valid name for a component name (except . and ..). 56. 57The 58.Fn fs_snapshot_delete 59function causes the named snapshot 60.Fa name 61to be deleted and the 62.Fn fs_snapshot_rename 63function causes the named snapshot 64.Fa old 65to be renamed to the name 66.Fa new . 67Available snapshots along with their attributes can be listed by calling 68.Fn fs_snapshot_list 69which is to be used in exactly the same way as 70.Xr getattrlistbulk 2 . 71. 72The 73.Fa flags 74parameter specifies the options that can be passed. No options are currently defined. 75.Pp 76Snapshots may be useful for backing up the Filesystem and to restore the Filesystem to a previous state. 77Snapshots are expected to consume no additional storage on creation but might consume additional storage as the active 78Filesystem is modified. Similarly deletion of files on the active filesystem may not result in the storage being available 79if the snapshot contains the file. Additionally, the underlying Filesystem may impose a limit on the number 80of snapshots that can be taken. For supporting Filesystems, a snapshot may be used as a source for a mount. This can be done 81by the 82.Fn fs_snapshot_mount 83function. The snapshot will be mounted read only. When a snapshot is mounted, it cannot be deleted but it can be renamed. 84To revert the filesystem to a previous snapshot, the 85.Fn fs_snapshot_revert 86can be used. It should be noted that reverting a filesystem to a snapshot is a destructive operation and causes all 87changes made to the filesystem (including snapshots created after the snapshot being reverted to) to be lost. 88. 89.Pp 90All snapshot functions require superuser privileges and also require an additional entitlement. 91. 92.Sh RETURN VALUES 93Upon successful completion, 94.Fn fs_snapshot_create 95, 96.Fn fs_snapshot_delete 97and 98.Fn fs_snapshot_rename 99returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error. 100.Fn fs_snapshot_list 101returns the number of entries successfully read. A return value of 0 indicates there are no more entries. 102Otherwise, a value of -1 is returned and errno is set to indicate the error. Return values are the same as 103.Xr getattrlistbulk 2 . 104.Pp 105.Sh COMPATIBILITY 106Not all volumes support snapshots. A volume can be tested for snapshot support 107by using 108.Xr getattrlist 2 109to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_INT_SNAPSHOT flag. 110.Pp 111.Sh ERRORS 112The 113.Fn fs_snapshot_create 114, 115.Fn fs_snapshot_delete 116, 117.Fn fs_snapshot_rename 118and 119.Fn fs_snapshot_list 120function will fail if: 121.Bl -tag -width Er 122. 123.It Bq Er EACCES 124Read permissions are denied for the caller on the filesystem 125. 126.It Bq Er ENOTSUP 127The underlying filesystem does not support this call. 128. 129.It Bq Er EINVAL 130The value of the 131.Fa flags 132parameter is invalid. 133. 134.It Bq Er ENOSPC 135There is no free space remaining on the file system containing the file. 136. 137.It Bq Er ENOSPC 138The limit for the maximum number of snapshots for a filesystem has been reached. 139. 140.It Bq Er EIO 141An I/O error occurred while reading from or writing to the file system. 142. 143.It Bq Er EPERM 144The calling process does not have appropriate privileges. 145. 146.It Bq Er EROFS 147The requested operation requires modifications in a read-only file system. 148. 149.It Bq Er ENAMETOOLONG 150The length of a component of a pathname is longer than {NAME_MAX}. 151. 152.It Bq Er EBADF 153dirfd is not a valid file descriptor. 154. 155.It Bq Er ENOTDIR 156dirfd is a file descriptor associated with a non-directory file. 157.El 158.Pp 159In addition, the 160.Fn fs_snapshot_create 161or 162.Fn fs_snapshot_rename 163functions may fail with the following errors 164.Bl -tag -width Er 165.It Bq Er EEXIST 166The The named snapshot to be created already exists or the new name already 167exists for the snapshot being renamed. 168. 169.El 170.Pp 171.Fn fs_snapshot_create 172or 173.Fn fs_snapshot_rename 174functions may fail with the following errors 175.Bl -tag -width Er 176.It Bq Er ENOENT 177The named snapshot does not exist. 178.El 179. 180.Pp 181.Fn fs_snapshot_delete 182function may fail with 183.Bl -tag -width Er 184.It Bq Er EBUSY 185The named snapshot is currently mounted. 186.El 187. 188.Sh SEE ALSO 189. 190.Xr getattrlist 2 , 191.Xr getattrlistbulk 2 192. 193.Sh HISTORY 194The 195.Fn fs_snapshot_create 196, 197.Fn fs_snapshot_delete 198, 199.Fn fs_snapshot_list 200, 201.Fn fs_snapshot_mount 202, 203.Fn fs_snapshot_rename 204and 205.Fn fs_snapshot_revert 206function calls appeared in macOS version 10.13 207. 208