NetBSD-5.0.2/lib/libpuffs/puffs_suspend.3

.\"	$NetBSD: puffs_suspend.3,v 1.2.18.1 2009/02/24 03:45:56 snj Exp $
.\"
.\" Copyright (c) 2007 Antti Kantee.  All rights reserved.
.\"
.\" 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 AUTHOR 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 AUTHOR 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 January 27, 2007
.Dt PUFFS_SUSPEND 3
.Os
.Sh NAME
.Nm puffs_suspend
.Nd puffs file system suspension and snapshotting
.Sh LIBRARY
.Lb libpuffs
.Sh SYNOPSIS
.In puffs.h
.Ft int
.Fn puffs_fs_suspend "struct puffs_usermount *pu"
.Sh DESCRIPTION
The function
.Fn puffs_fs_suspend
requests the kernel to suspend operations to the file system indicated by
.Fa pu .
There are several possible outcomes: nothing, an error or success.
These will be indicated through the callback of the same name.
The file system must set this callback if it wants to be notified of
file system suspension.
The interface call itself returns 0 on success or \-1 on error and
sets
.Va errno .
In case an error is returned, the callback will never be called.
However, the converse does not hold and the callback may never be
called even if the library call is successful.
.Pp
In case the kernel is successful to start suspending the file system,
the callback is called with status
.Dv PUFFS_SUSPEND START .
The file system implementation may use this as a hint on how to handle
following operations.
Once the file system has successfully been suspended, the status
.Dv PUFFS_SUSPEND_SUSPENDED
will be delivered.
In case there was an error while suspending,
.Dv PUFFS_SUSPEND_ERROR
is given.
This effectively nullifies any
.Dv PUFFS_SUSPEND_START
given earlier.
Operation will automatically resume after suspension and the status
.Dv PUFFS_SUSPEND_RESUME
is delivered to the callback.
Error or success is always provided in case start is given.
.Pp
The file system is supposed to do a file system specific snapshotting
routine when it receives
.Dv PUFFS_SUSPEND_SUSPENDED .
.Sh SEE ALSO
.Xr puffs 3 ,
.Xr puffs_cc 3
.Sh BUGS
Currently the implementation works only for single-threaded file systems
which do not use
.Nm puffs_cc .
.Pp
File system data and metadata are not always totally correctly
synchronized at suspend.