bsd/man/man2/fs_snapshot_create.2

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