X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/4d15aeb193b2c68f1d38666c317f8d3734f5f083..5ba3f43ea354af8ad55bea84372a2bc834d8757c:/bsd/man/man2/fs_snapshot_create.2?ds=sidebyside diff --git a/bsd/man/man2/fs_snapshot_create.2 b/bsd/man/man2/fs_snapshot_create.2 new file mode 100644 index 000000000..57e3b3d34 --- /dev/null +++ b/bsd/man/man2/fs_snapshot_create.2 @@ -0,0 +1,201 @@ +.\" Copyright (c) 2017 Apple Computer, Inc. All rights reserved. +.\" +.\" The contents of this file constitute Original Code as defined in and +.\" are subject to the Apple Public Source License Version 1.1 (the +.\" "License"). You may not use this file except in compliance with the +.\" License. Please obtain a copy of the License at +.\" http://www.apple.com/publicsource and read it before using this file. +.\" +.\" This Original Code and all software distributed under the License are +.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER +.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, +.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, +.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the +.\" License for the specific language governing rights and limitations +.\" under the License. +.\" +.\" @(#)fs_snapshot_create.2 +. +.Dd July 4th, 2017 +.Dt FS_SNAPSHOT_CREATE 2 +.Os Darwin +.Sh NAME +.Nm fs_snasphot_create +.Nd create read only snapshot of a mounted filesystem +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Pp +.Ft int +.Fn fs_snapshot_create "int dirfd" "const char * name" "uint32_t flags" +. +.Ft int +.Fn fs_snapshot_delete "int dirfd" "const char * name" "uint32_t flags" +. +.Ft int +.Fn fs_snapshot_list "int dirfd" "struct attrlist * name" "void * attrbuf" "size_t bufsize" "uint32_t flags" +. +.Ft int +.Fn fs_snapshot_rename "int dirfd" "const char * old" "const char * new" "uint32_t flags" +. +.Ft int +.Fn fs_snapshot_mount "int dirfd" "const char * dir" "const char * snapshot" "uint32_t flags" +. +.Ft int +.Fn fs_snapshot_revert "int dirfd" "const char * name" "uint32_t flags" +. +.Sh DESCRIPTION +The +.Fn 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 the +.Fa dirfd +parameter which should be a file descriptor associated with the root directory of the filesystem for the snapshot is to be created. +.Fa name +can be any valid name for a component name (except . and ..). +. +The +.Fn fs_snapshot_delete +function causes the named snapshot +.Fa name +to be deleted and the +.Fn fs_snapshot_rename +function causes the named snapshot +.Fa old +to be renamed to the name +.Fa new . +Available snapshots along with their attributes can be listed by calling +.Fn fs_snapshot_list +which is to be used in exactly the same way as +.Xr getattrlistbulk 2 . +. +The +.Fa flags +parameter specifies the options that can be passed. No options are currently defined. +.Pp +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 +.Fn 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 +.Fn 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. +. +.Pp +All snapshot functions require superuser privileges and also require an additional entitlement. +. +.Sh RETURN VALUES +Upon successful completion, +.Fn fs_snapshot_create +, +.Fn fs_snapshot_delete +, +.Fn fs_snapshot_rename +and +.Fn fs_snapshot_list +returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error. +.Pp +.Sh COMPATIBILITY +Not all volumes support snapshots. A volume can be tested for snapshot support +by using +.Xr getattrlist 2 +to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_INT_SNAPSHOT flag. +.Pp +.Sh ERRORS +The +.Fn fs_snapshot_create +, +.Fn fs_snapshot_delete +, +.Fn fs_snapshot_rename +and +.Fn fs_snapshot_list +function will fail if: +.Bl -tag -width Er +. +.It Bq Er EACCES +Read permissions are denied for the caller on the filesystem +. +.It Bq Er ENOTSUP +The underlying filesystem does not support this call. +. +.It Bq Er EINVAL +The value of the +.Fa flags +parameter is invalid. +. +.It Bq Er ENOSPC +There is no free space remaining on the file system containing the file. +. +.It Bq Er ENOSPC +The limit for the maximum number of snapshots for a filesystem has been reached. +. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +. +.It Bq Er EPERM +The calling process does not have appropriate privileges. +. +.It Bq Er EROFS +The requested operation requires modifications in a read-only file system. +. +.It Bq Er ENAMETOOLONG +The length of a component of a pathname is longer than {NAME_MAX}. +. +.It Bq Er EBADF +dirfd is not a valid file descriptor. +. +.It Bq Er ENOTDIR +dirfd is a file descriptor associated with a non-directory file. +.El +.Pp +In addition, the +.Fn fs_snapshot_create +or +.Fn fs_snapshot_rename +functions may fail with the following errors +.Bl -tag -width Er +.It Bq Er EEXIST +The The named snapshot to be created already exists or the new name already +exists for the snapshot being renamed. +. +.El +.Pp +.Fn fs_snapshot_create +or +.Fn fs_snapshot_rename +functions may fail with the following errors +.Bl -tag -width Er +.It Bq Er ENOENT +The named snapshot does not exist. +.El +. +.Pp +.Fn fs_snapshot_delete +function may fail with +.Bl -tag -width Er +.It Bq Er EBUSY +The named snapshot is currently mounted. +.El +. +.Sh SEE ALSO +. +.Xr getattrlist 2 , +.Xr getattrlistbulk 2 +. +.Sh HISTORY +The +.Fn fs_snapshot_create +, +.Fn fs_snapshot_delete +, +.Fn fs_snapshot_delete +and +.Fn fs_snapshot_list +function calls appeared in macOS version 10.13 +.