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