.\"	$NetBSD: fss.4,v 1.12 2008/09/21 10:25:07 hannken Exp $	*/
.\"
.\"
.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Juergen Hannken-Illjes.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd September 21, 2008
.Dt FSS 4
.Os
.Sh NAME
.Nm fss
.Nd file system snapshot device
.Sh SYNOPSIS
.Cd "pseudo-device fss 4"
.Sh DESCRIPTION
The
.Nm
driver provides a read-only interface to the snapshot of a currently
mounted file system.
Reading from a
.Nm
device gives the view of the file system when the snapshot was taken.
It can be configured via
.Xr ioctl 2 .
.Sh IOCTLS
The
.Xr ioctl 2
command codes below are defined in
.Aq Pa sys/dev/fssvar.h .
.Pp
The (third) argument to
.Xr ioctl 2
should be a pointer to the type indicated.
.Bl -tag -width 8n
.It Dv FSSIOCSET(struct fss_set)
Configures a
.Nm
device.
.Bd -literal -offset indent
struct fss_set {
	char *fss_mount;
	char *fss_bstore;
	blksize_t fss_csize;
};
.Ed
.Pp
The struct element
.Va fss_mount
is the mount point of the file system.
The struct element
.Va fss_bstore
is either a regular file or a raw disk device where data overwritten on
the file system will be saved.
The struct element
.Va fss_csize
is the preferred size of this data.
.It Dv FSSIOCGET(struct fss_get)
Gets the status of a
.Nm
device.
.Bd -literal -offset indent
struct fss_get {
	char fsg_mount[MNAMELEN];
	struct timeval fsg_time;
	blksize_t fsg_csize;
	blkcnt_t fsg_mount_size;
	blkcnt_t fsg_bs_size;
};
.Ed
The struct element
.Va fsg_mount
is the mount point of the file system.
The struct element
.Va fsg_time
is the time this snapshot was taken.
The struct element
.Va fsg_csize
is the current size of data clusters.
The struct element
.Va fsg_mount_size
is the number of clusters of the file system.
The struct element
.Va fsg_bs_size
is the number of clusters written to the backing store.
.It Dv FSSIOCCLR
Unconfigures a
.Nm
device.
.It Dv FSSIOFSET(int)
Sets the flags of a
.Nm
device.
Possible flags are:
.Bl -tag -width Dv
.It Dv FSS_UNCONFIG_ON_CLOSE
Unconfigure the
.Nm
device on the last close.
.El
.It Dv FSSIOFGET(int)
Gets the flags of a
.Nm
device.
.El
.Sh KERNEL THREADS
For each active snapshot device there is a kernel thread
that handles the backing store.
This thread is named
.Va fssN
where
.Va N
is the device minor number.
.Sh FILES
.Bl -tag -width /dev/rfss? -compact
.It Pa /dev/rfss?
.It Pa /dev/fss?
.El
.Sh SEE ALSO
.Xr fssconfig 8 ,
.Xr mount 8 ,
.Xr umount 8
.Sh HISTORY
The
.Nm
device appeared in
.Nx 2.0 .
.Sh BUGS
This driver is
.Em experimental .
Be sure you have a backup before you use it.