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 69The 70.Nm 71subsystem is a set of operations to assist file system suspension. 72These operations must not be used outside of file systems. 73.Pp 74File systems supporting this subsystem must set the flag 75.Dv IMNT_HAS_TRANS 76in 77.Dv "mnt_iflag" . 78.Pp 79File systems are always in one of these states: 80.Bl -tag -offset indent -width FSTRANS_SUSPENDING -compact 81.It Dv FSTRANS_NORMAL 82normal operations. 83.It Dv FSTRANS_SUSPENDING 84preparing a suspension. 85.It Dv FSTRANS_SUSPENDED 86suspended. 87.El 88This state is represented by 89.Vt "enum fstrans_state" . 90.Bl -tag -width compact 91.It Fn fstrans_getstate "mp" 92returns the current state of the file system 93.Fa mp . 94.Pp 95.It Fn fstrans_setstate "mp" "new_state" 96changes the state of the file system 97.Fa mp 98to 99.Fa new_state . 100.El 101.Pp 102All file system operations use a 103.Em "fstrans lock" . 104This lock is recursive. 105A thread already owning a lock will always get another lock. 106The lock has two variants: 107.Bl -tag -offset indent -width FSTRANS_SHARED -compact 108.It Dv FSTRANS_SHARED 109this lock will be granted if the file system is in state 110.Dv FSTRANS_NORMAL . 111.It Dv FSTRANS_LAZY 112this lock will be granted if the file system is in state 113.Dv FSTRANS_NORMAL 114or 115.Dv FSTRANS_SUSPENDING . 116It needs special care because operations using this variant will not block 117while the file system prepares suspension. 118.El 119The lock variant is represented by 120.Vt "enum fstrans_lock_type" . 121.Bl -tag -width compact 122.It Fn fstrans_start "mp" "lock_type" 123sets a lock of type 124.Fa lock_type 125on the file system 126.Fa mp . 127.It Fn fstrans_start_nowait "mp" "lock_type" 128will not wait for a state change of the file system when attempting to 129aquire the lock. 130The thread may still sleep while attempting to aquire the lock. 131.It Fn fstrans_done "mp" 132releases a lock on the file system 133.Fa mp . 134.It Fn fstrans_is_owner "mp" 135returns 136.Dv true 137if this thread is currently suspending the file system 138.Fa mp . 139.It Fn fscow_establish "mp" "func" "cookie" 140Establish a copy-on-write callback for the file system 141.Fa mp . 142.Fa func 143will be called for every buffer written through this file system. 144.It Fn fscow_disestablish "mp" "func" "cookie" 145Disestablish a copy-on-write callback registered with 146.Fn fscow_establish . 147.It Fn fscow_run "bp" "data_valid" 148Run all copy-on-write callbacks established for the file system this buffer 149belongs to. 150If 151.Fa data_valid 152is 153.Dv true 154the buffer data has not yet been modified. 155.El 156.Sh RETURN VALUES 157The functions 158.Fn fstrans_setstate 159and 160.Fn fstrans_start_nowait 161return zero on success and an error value on failure. 162.Sh EXAMPLES 163The following is an example of a file system suspend operation. 164.Bd -literal 165int 166xxx_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 189This is an example of a file system operation. 190.Bd -literal 191int 192xxx_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 212The actual code implementing this subsystem can be found in the file 213.Pa sys/kern/vfs_trans.c . 214.Sh HISTORY 215The 216.Nm 217subsystem appeared in 218.Nx 5.0 . 219.Sh AUTHORS 220The 221.Nm 222subsystem was written by 223.An J\(:urgen Hannken-Illjes 224.Aq hannken@NetBSD.org . 225