1.\" $NetBSD: fstrans.9,v 1.11 2007/12/02 13:56:15 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 December 2, 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" \ 69"int (*func)(void *, struct buf *, bool)" "void *cookie" 70.Ft int 71.Fn fscow_disestablish "struct mount *mp" \ 72"int (*func)(void *, struct buf *, bool)" "void *cookie" 73.Ft int 74.Fn fscow_run "struct buf *bp" "bool data_valid" 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" "data_valid" 155Run all copy-on-write callbacks established for the file system this buffer 156belongs to. 157If 158.Fa data_valid 159is 160.Dv true 161the buffer data has not yet been modified. 162.El 163.Sh RETURN VALUES 164The functions 165.Fn fstrans_setstate 166and 167.Fn fstrans_start_nowait 168return zero on success and an error value on failure. 169.Sh EXAMPLES 170The following is an example of a file system suspend operation. 171.Bd -literal 172int 173xxx_suspendctl(struct mount *mp, int cmd) 174{ 175 int error; 176 177 switch (cmd) { 178 case SUSPEND_SUSPEND: 179 error = fstrans_setstate(mp, FSTRANS_SUSPENDING); 180 if (error != 0) 181 return error; 182 183 /* Sync file system state to disk. */ 184 185 return fstrans_setstate(mp, FSTRANS_SUSPENDED); 186 187 case SUSPEND_RESUME: 188 return fstrans_setstate(mp, FSTRANS_NORMAL); 189 190 default: 191 return EINVAL; 192 } 193} 194.Ed 195.Pp 196This is an example of a file system operation. 197.Bd -literal 198int 199xxx_create(void *v) 200{ 201 struct vop_create_args *ap = v; 202 struct mount *mp = ap-\*[Gt]a_dvp-\*[Gt]v_mount; 203 int error; 204 205 if ((error = fstrans_start(mp, FSTRANS_SHARED)) != 0) 206 return error; 207 208 /* Actually create the node. */ 209 210 fstrans_done(mp); 211 212 return 0; 213} 214.Ed 215.Sh SEE ALSO 216.Xr vfs_resume 9 , 217.Xr vfs_suspend 9 218.Sh CODE REFERENCES 219The actual code implementing this subsystem can be found in the file 220.Pa sys/kern/vfs_trans.c . 221.Sh HISTORY 222The 223.Nm 224subsystem appeared in 225.Nx 5.0 . 226.Sh AUTHORS 227The 228.Nm 229subsystem was written by 230.if t .An J\(:urgen Hannken-Illjes 231.if n .An Juergen Hannken-Illjes 232.Aq hannken@NetBSD.org . 233