share/man/man9/fstrans.9

   1 .\"     $NetBSD: fstrans.9,v 1.13 2009/04/12 19:00:56 joerg Exp $
   2 .\"
   3 .\" Copyright (c) 2007 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Juergen Hannken-Illjes.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd December 2, 2007
  31 .Dt FSTRANS 9
  32 .Os
  33 .Sh NAME
  34 .Nm fstrans ,
  35 .Nm fstrans_setstate ,
  36 .Nm fstrans_getstate ,
  37 .Nm fstrans_start ,
  38 .Nm fstrans_start_nowait ,
  39 .Nm fstrans_done ,
  40 .Nm fstrans_is_owner ,
  41 .Nm fscow_establish ,
  42 .Nm fscow_disestablish ,
  43 .Nm fscow_run
  44 .Nd file system suspension helper subsystem
  45 .Sh SYNOPSIS
  46 .In sys/mount.h
  47 .In sys/fstrans.h
  48 .Ft int
  49 .Fn fstrans_setstate "struct mount *mp" "enum fstrans_state new_state"
  50 .Ft "enum fstrans_state"
  51 .Fn fstrans_getstate "struct mount *mp"
  52 .Ft void
  53 .Fn fstrans_start "struct mount *mp" "enum fstrans_lock_type lock_type"
  54 .Ft int
  55 .Fn fstrans_start_nowait "struct mount *mp" "enum fstrans_lock_type lock_type"
  56 .Ft void
  57 .Fn fstrans_done "struct mount *mp"
  58 .Ft int
  59 .Fn fstrans_is_owner "struct mount *mp"
  60 .Ft int
  61 .Fn fscow_establish "struct mount *mp" \
  62 "int (*func)(void *, struct buf *, bool)" "void *cookie"
  63 .Ft int
  64 .Fn fscow_disestablish "struct mount *mp" \
  65 "int (*func)(void *, struct buf *, bool)" "void *cookie"
  66 .Ft int
  67 .Fn fscow_run "struct buf *bp" "bool data_valid"
  68 .Sh DESCRIPTION
  69 The
  70 .Nm
  71 subsystem is a set of operations to assist file system suspension.
  72 These operations must not be used outside of file systems.
  73 .Pp
  74 File systems supporting this subsystem must set the flag
  75 .Dv IMNT_HAS_TRANS
  76 in
  77 .Dv "mnt_iflag" .
  78 .Pp
  79 File systems are always in one of these states:
  80 .Bl -tag -offset indent -width FSTRANS_SUSPENDING -compact
  81 .It Dv FSTRANS_NORMAL
  82 normal operations.
  83 .It Dv FSTRANS_SUSPENDING
  84 preparing a suspension.
  85 .It Dv FSTRANS_SUSPENDED
  86 suspended.
  87 .El
  88 This state is represented by
  89 .Vt "enum fstrans_state" .
  90 .Bl -tag -width compact
  91 .It Fn fstrans_getstate "mp"
  92 returns the current state of the file system
  93 .Fa mp .
  94 .Pp
  95 .It Fn fstrans_setstate "mp" "new_state"
  96 changes the state of the file system
  97 .Fa mp
  98 to
  99 .Fa new_state .
 100 .El
 101 .Pp
 102 All file system operations use a
 103 .Em "fstrans lock" .
 104 This lock is recursive.
 105 A thread already owning a lock will always get another lock.
 106 The lock has two variants:
 107 .Bl -tag -offset indent -width FSTRANS_SHARED -compact
 108 .It Dv FSTRANS_SHARED
 109 this lock will be granted if the file system is in state
 110 .Dv FSTRANS_NORMAL .
 111 .It Dv FSTRANS_LAZY
 112 this lock will be granted if the file system is in state
 113 .Dv FSTRANS_NORMAL
 114 or
 115 .Dv FSTRANS_SUSPENDING .
 116 It needs special care because operations using this variant will not block
 117 while the file system prepares suspension.
 118 .El
 119 The lock variant is represented by
 120 .Vt "enum fstrans_lock_type" .
 121 .Bl -tag -width compact
 122 .It Fn fstrans_start "mp" "lock_type"
 123 sets a lock of type
 124 .Fa lock_type
 125 on the file system
 126 .Fa mp .
 127 .It Fn fstrans_start_nowait "mp" "lock_type"
 128 will not wait for a state change of the file system when attempting to
 129 acquire the lock.
 130 The thread may still sleep while attempting to acquire the lock.
 131 .It Fn fstrans_done "mp"
 132 releases a lock on the file system
 133 .Fa mp .
 134 .It Fn fstrans_is_owner "mp"
 135 returns
 136 .Dv true
 137 if this thread is currently suspending the file system
 138 .Fa mp .
 139 .It Fn fscow_establish "mp" "func" "cookie"
 140 Establish a copy-on-write callback for the file system
 141 .Fa mp .
 142 .Fa func
 143 will be called for every buffer written through this file system.
 144 .It Fn fscow_disestablish "mp" "func" "cookie"
 145 Disestablish a copy-on-write callback registered with
 146 .Fn fscow_establish .
 147 .It Fn fscow_run "bp" "data_valid"
 148 Run all copy-on-write callbacks established for the file system this buffer
 149 belongs to.
 150 If
 151 .Fa data_valid
 152 is
 153 .Dv true
 154 the buffer data has not yet been modified.
 155 .El
 156 .Sh RETURN VALUES
 157 The functions
 158 .Fn fstrans_setstate
 159 and
 160 .Fn fstrans_start_nowait
 161 return zero on success and an error value on failure.
 162 .Sh EXAMPLES
 163 The following is an example of a file system suspend operation.
 164 .Bd -literal
 165 int
 166 xxx_suspendctl(struct mount *mp, int cmd)
 167 {
 168         int error;
 169
 170         switch (cmd) {
 171         case SUSPEND_SUSPEND:
 172                 error = fstrans_setstate(mp, FSTRANS_SUSPENDING);
 173                 if (error != 0)
 174                         return error;
 175
 176                 /* Sync file system state to disk. */
 177
 178                 return fstrans_setstate(mp, FSTRANS_SUSPENDED);
 179
 180         case SUSPEND_RESUME:
 181                 return fstrans_setstate(mp, FSTRANS_NORMAL);
 182
 183         default:
 184                 return EINVAL;
 185         }
 186 }
 187 .Ed
 188 .Pp
 189 This is an example of a file system operation.
 190 .Bd -literal
 191 int
 192 xxx_create(void *v)
 193 {
 194         struct vop_create_args *ap = v;
 195         struct mount *mp = ap-\*[Gt]a_dvp-\*[Gt]v_mount;
 196         int error;
 197
 198         if ((error = fstrans_start(mp, FSTRANS_SHARED)) != 0)
 199                 return error;
 200
 201         /* Actually create the node. */
 202
 203         fstrans_done(mp);
 204
 205         return 0;
 206 }
 207 .Ed
 208 .Sh SEE ALSO
 209 .Xr vfs_resume 9 ,
 210 .Xr vfs_suspend 9
 211 .Sh CODE REFERENCES
 212 The actual code implementing this subsystem can be found in the file
 213 .Pa sys/kern/vfs_trans.c .
 214 .Sh HISTORY
 215 The
 216 .Nm
 217 subsystem appeared in
 218 .Nx 5.0 .
 219 .Sh AUTHORS
 220 The
 221 .Nm
 222 subsystem was written by
 223 .An J\(:urgen Hannken-Illjes
 224 .Aq hannken@NetBSD.org .