1.\" $NetBSD: fstrans.9,v 1.26 2017/07/03 21:28:48 wiz 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 June 4, 2017 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 void 49.Fn fstrans_start "struct mount *mp" 50.Ft int 51.Fn fstrans_start_nowait "struct mount *mp" 52.Ft void 53.Fn fstrans_done "struct mount *mp" 54.Ft int 55.Fn fstrans_setstate "struct mount *mp" "enum fstrans_state new_state" 56.Ft "enum fstrans_state" 57.Fn fstrans_getstate "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 assists file system suspension and copy-on-write snapshots. 72.Pp 73The file system's normal operations, such as its 74.Xr vnodeops 9 , 75must be bracketed by 76.Fn fstrans_start 77and 78.Fn fstrans_done 79in a 80.Em shared 81transaction, which is blocked by suspending the file system and while 82it is suspended. 83.Pp 84Transactions are per-thread and nestable: if a thread is already in a 85transaction, it can enter another transaction without blocking. 86Each 87.Fn fstrans_start 88must be paired with 89.Fn fstrans_done . 90Transactions for multiple distinct mount points may not be nested. 91.Pp 92The file system's 93.Xr VFS_SUSPENDCTL 9 94method can use 95.Fn fstrans_setstate 96to: 97.Bl -dash 98.It 99enter the 100.Dv FSTRANS_SUSPENDED 101state to suspend all operations, and 102.It 103restore to the 104.Dv FSTRANS_NORMAL 105state to resume all operations. 106.El 107.Pp 108A file system supporting 109.Nm 110may establish a copy-on-write callback with 111.Fn fscow_establish . 112The copy-on-write callback will be called every time a buffer is 113written to a block device with 114.Fn VOP_STRATEGY 115and every time a buffer is read into the 116.Xr buffercache 9 117with 118.Dv B_MODIFY 119set indicating the caller's intent to modify it. 120Anyone modifying a buffer may additionally use 121.Fn fscow_run 122to explicitly invoke the established callback. 123The copy-on-write callback must be disestablished with 124.Fn fscow_disestablish 125when the file system is done with it. 126.Sh FUNCTIONS 127.Bl -tag -width abcd 128.It Fn fstrans_start "mp" 129Enter a transaction on the file system 130.Fa mp 131in the current thread. 132If the file system is in a state that blocks such transactions, wait 133until it changes state to one that does not. 134.Pp 135If the file system is suspended, wait until it is resumed. 136.Pp 137However, if the current thread is already in a transaction on 138.Fa mp , 139.Fn fstrans_start 140will enter a nested transaction and return immediately without 141waiting. 142.Pp 143May sleep. 144.It Fn fstrans_start_nowait "mp" 145Like 146.Fn fstrans_start , 147but return 148.Dv EBUSY 149immediately if transactions are blocked in its current state. 150.Pp 151May sleep nevertheless on internal locks. 152.It Fn fstrans_done "mp" 153End the current transaction on 154.Fa mp . 155.It Fn fstrans_getstate "mp" 156Return the current state of the file system 157.Fa mp . 158.Pp 159Must be called within a transaction for the answer to be stable. 160.It Fn fstrans_setstate "mp" "new_state" 161Change the state of the file system 162.Fa mp 163to 164.Fa new_state , 165and wait for all transactions not allowed in 166.Fa new_state 167to complete. 168.Bl -tag -width FSTRANS_SUSPENDED 169.It Dv FSTRANS_NORMAL 170Allow all transactions. 171.It Dv FSTRANS_SUSPENDED 172Block all transactions. 173.El 174.Pp 175A thread that changes a file system to a state other than 176.Dv FSTRANS_NORMAL 177enters a transaction for the purposes of 178.Fn fstrans_getstate 179until it changes state back to 180.Dv FSTRANS_NORMAL . 181.Pp 182Additionally, a thread that changes a file system to a state other than 183.Dv FSTRANS_NORMAL 184acquires an exclusive lock on the file system state, so that 185.Fn fstrans_is_owner 186will return true in that thread, and no other thread can change the 187file system's state until the owner restores it to 188.Dv FSTRANS_NORMAL . 189.Pp 190May sleep, and may be interrupted by a signal. 191On success, return zero. 192On failure, restore the file system to the 193.Dv FSTRANS_NORMAL 194state and return an error code. 195.Fn fstrans_setstate 196never fails if 197.Fa new_state 198is 199.Dv FSTRANS_NORMAL . 200.It Fn fstrans_is_owner "mp" 201Return 202.Dv true 203if the current thread is currently suspending the file system 204.Fa mp . 205.It Fn fscow_establish "mp" "func" "cookie" 206Establish a copy-on-write callback for the file system 207.Fa mp . 208The function 209.Fa func 210will be called for every buffer 211.Fa bp 212written through this file system as 213.Dl Fa func Ns Li "(" Ns Fa cookie Ns Li "," Fa bp Ns Li "," Fa data_valid Ns Li ")" 214where 215.Fa data_valid 216is true if and only if the buffer 217.Fa bp 218has not yet been modified. 219.Pp 220May sleep. 221.It Fn fscow_disestablish "mp" "func" "cookie" 222Disestablish a copy-on-write callback established with 223.Fn fscow_establish . 224.Pp 225May sleep. 226.It Fn fscow_run "bp" "data_valid" 227Run all copy-on-write callbacks established for the file system this buffer 228belongs to, if they have not already been run for this buffer. 229If 230.Fa data_valid 231is 232.Dv true 233the buffer data has not yet been modified. 234.Pp 235May sleep. 236.El 237.Sh EXAMPLES 238The following is an example of a file system suspend operation. 239.Bd -literal 240int 241xxx_suspendctl(struct mount *mp, int cmd) 242{ 243 int error; 244 245 switch (cmd) { 246 case SUSPEND_SUSPEND: 247 return fstrans_setstate(mp, FSTRANS_SUSPENDED); 248 249 case SUSPEND_RESUME: 250 return fstrans_setstate(mp, FSTRANS_NORMAL); 251 252 default: 253 return EINVAL; 254 } 255} 256.Ed 257.Pp 258This is an example of a file system operation. 259.Bd -literal 260int 261xxx_create(void *v) 262{ 263 struct vop_create_args *ap = v; 264 struct mount *mp = ap->a_dvp->v_mount; 265 int error; 266 267 fstrans_start(mp); 268 269 /* Actually create the node. */ 270 271 fstrans_done(mp); 272 273 return 0; 274} 275.Ed 276.Sh CODE REFERENCES 277The 278.Nm 279subsystem is implemented in the file 280.Pa sys/kern/vfs_trans.c . 281.Sh SEE ALSO 282.Xr vfs_resume 9 , 283.Xr vfs_suspend 9 284.Sh HISTORY 285The 286.Nm 287subsystem appeared in 288.Nx 5.0 . 289.Sh AUTHORS 290The 291.Nm 292subsystem was written by 293.An J\(:urgen Hannken-Illjes 294.Aq hannken@NetBSD.org . 295.Sh BUGS 296.Nm 297is useful only for temporary suspension \(em it does not help to 298permanently block file system operations for unmounting, because 299.Fn fstrans_start 300cannot fail. 301