lib/libpuffs/puffs_suspend.3

   1 .\"     $NetBSD: puffs_suspend.3,v 1.1 2007/01/26 23:55:27 pooka Exp $
   2 .\"
   3 .\" Copyright (c) 2007 Antti Kantee.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd January 27, 2007
  27 .Dt PUFFS_SUSPEND 3
  28 .Os
  29 .Sh NAME
  30 .Nm puffs_suspend
  31 .Nd puffs file system suspension and snapshotting
  32 .Sh LIBRARY
  33 .Lb libpuffs
  34 .Sh SYNOPSIS
  35 .In puffs.h
  36 .Ft int
  37 .Fn puffs_fs_suspend "struct puffs_usermount *pu"
  38 .Sh DESCRIPTION
  39 .Em IMPORTANT NOTE!
  40 This document describes interfaces which are not yet guaranteed to be
  41 stable.
  42 In case you update your system sources, please recompile everything
  43 and fix compilation errors.
  44 If your sources are out-of-sync, incorrect operation may result.
  45 The interfaces in this document will most likely be hugely simplified
  46 in later versions or made transparent to the implementation.
  47 .Pp
  48 The function
  49 .Fn puffs_fs_suspend
  50 requests the kernel to suspend operations to the file system indicated by
  51 .Fa pu .
  52 There are several possible outcomes: nothing, an error or success.
  53 These will be indicated through the callback of the same name.
  54 The file system must set this callback if it wants to be notified of
  55 file system suspension.
  56 The interface call itself returns 0 on success or \-1 on error and
  57 sets
  58 .Va errno .
  59 In case an error is returned, the callback will never be called.
  60 However, the converse does not hold and the callback may never be
  61 called even if the library call is successful.
  62 .Pp
  63 In case the kernel is successful to start suspending the file system,
  64 the callback is called with status
  65 .Dv PUFFS_SUSPEND START .
  66 The file system implementation may use this as a hint on how to handle
  67 following operations.
  68 Once the file system has successfully been suspended, the status
  69 .Dv PUFFS_SUSPEND_SUSPENDED
  70 will be delivered.
  71 In case there was an error while suspending,
  72 .Dv PUFFS_SUSPEND_ERROR
  73 is given.
  74 This effectively nullifies any
  75 .Dv PUFFS_SUSPEND_START
  76 given earlier.
  77 Operation will automatically resume after suspension and the status
  78 .Dv PUFFS_SUSPEND_RESUME
  79 is delivered to the callback.
  80 Error or success is always provided in case start is given.
  81 .Pp
  82 The file system is supposed to do a file system specific snapshotting
  83 routine when it receives
  84 .Dv PUFFS_SUSPEND_SUSPENDED .
  85 .Sh SEE ALSO
  86 .Xr puffs 3 ,
  87 .Xr puffs_cc 3
  88 .Sh BUGS
  89 Currently the implementation works only for single-threaded file systems
  90 which do not use
  91 .Nm puffs_cc .
  92 .Pp
  93 File system data and metadata are not always totally correctly
  94 synchronized at suspend.
  95 This will be fixed soon.