xnu-7195.101.1.tar.gz

[apple/xnu.git] / bsd / man / man2 / fs_snapshot_create.2

.\" Copyright (c) 2017-2018 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_snapshot_create
.Nd create read only snapshot of a mounted filesystem
.Sh SYNOPSIS
.Fd #include <sys/attr.h>
.Fd #include <sys/snapshot.h>
.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
.Fa dirfd
parameter which should be a file descriptor associated with the root directory of the filesystem for which 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
and
.Fn fs_snapshot_rename
returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.
.Fn 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
.Xr getattrlistbulk 2 .
.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_list
,
.Fn fs_snapshot_mount
,
.Fn fs_snapshot_rename
and
.Fn fs_snapshot_revert
function calls appeared in macOS version 10.13
.