FSTRANS(9) BSD Kernel Developer's Manual FSTRANS(9)
NAME
fstrans, fstrans_setstate, fstrans_getstate, fstrans_start, fstrans_start_nowait, fstrans_done, fstrans_is_owner, fscow_establish,
fscow_disestablish, fscow_run -- file system suspension helper subsystem
SYNOPSIS
#include <sys/mount.h>
#include <sys/fstrans.h>
int
fstrans_setstate(struct mount *mp, enum fstrans_state new_state);
enum fstrans_state
fstrans_getstate(struct mount *mp);
void
fstrans_start(struct mount *mp, enum fstrans_lock_type lock_type);
int
fstrans_start_nowait(struct mount *mp, enum fstrans_lock_type lock_type);
void
fstrans_done(struct mount *mp);
int
fstrans_is_owner(struct mount *mp);
int
fscow_establish(struct mount *mp, int (*func)(void *, struct buf *, bool), void *cookie);
int
fscow_disestablish(struct mount *mp, int (*func)(void *, struct buf *, bool), void *cookie);
int
fscow_run(struct buf *bp, bool data_valid);
DESCRIPTION
The fstrans subsystem is a set of operations to assist file system suspension. These operations must not be used outside of file systems.
File systems supporting this subsystem must set the flag IMNT_HAS_TRANS in mnt_iflag.
File systems are always in one of these states:
FSTRANS_NORMAL Normal operations.
FSTRANS_SUSPENDING Preparing a suspension.
FSTRANS_SUSPENDED Suspended.
This state is represented by enum fstrans_state.
All file system operations use a fstrans lock. This lock is recursive. A thread already owning a lock will always get another lock. The
lock has two variants:
FSTRANS_SHARED A lock that will be granted if the file system is in state FSTRANS_NORMAL.
FSTRANS_LAZY A lock that will be granted if the file system is in state FSTRANS_NORMAL or FSTRANS_SUSPENDING. It needs special care
because operations using this variant will not block while the file system prepares suspension.
The lock variant is represented by enum fstrans_lock_type.
FUNCTIONS
The following functions comprise the API provided by fstrans.
fstrans_getstate(mp)
Returns the current state of the file system mp.
fstrans_setstate(mp, new_state)
Changes the state of the file system mp to new_state.
fstrans_start(mp, lock_type)
Sets a lock of type lock_type on the file system mp.
fstrans_start_nowait(mp, lock_type)
Like fstrans_start(), but will not wait for a state change of the file system when attempting to acquire the lock. The thread may
still sleep while attempting to acquire the lock.
fstrans_done(mp)
Releases a lock on the file system mp.
fstrans_is_owner(mp)
Returns true if this thread is currently suspending the file system mp.
fscow_establish(mp, func, cookie)
Establish a copy-on-write callback for the file system mp. The function func will be called for every buffer written through this
file system.
fscow_disestablish(mp, func, cookie)
Disestablish a copy-on-write callback registered with fscow_establish().
fscow_run(bp, data_valid)
Run all copy-on-write callbacks established for the file system this buffer belongs to. If data_valid is true the buffer data has
not yet been modified.
RETURN VALUES
The functions fstrans_setstate() and fstrans_start_nowait() return zero on success and an error value on failure.
EXAMPLES
The following is an example of a file system suspend operation.
int
xxx_suspendctl(struct mount *mp, int cmd)
{
int error;
switch (cmd) {
case SUSPEND_SUSPEND:
error = fstrans_setstate(mp, FSTRANS_SUSPENDING);
if (error != 0)
return error;
/* Sync file system state to disk. */
return fstrans_setstate(mp, FSTRANS_SUSPENDED);
case SUSPEND_RESUME:
return fstrans_setstate(mp, FSTRANS_NORMAL);
default:
return EINVAL;
}
}
This is an example of a file system operation.
int
xxx_create(void *v)
{
struct vop_create_args *ap = v;
struct mount *mp = ap->a_dvp->v_mount;
int error;
if ((error = fstrans_start(mp, FSTRANS_SHARED)) != 0)
return error;
/* Actually create the node. */
fstrans_done(mp);
return 0;
}
SEE ALSO
vfs_resume(9), vfs_suspend(9)
CODE REFERENCES
The actual code implementing this subsystem can be found in the file sys/kern/vfs_trans.c.
HISTORY
The fstrans subsystem appeared in NetBSD 5.0.
AUTHORS
The fstrans subsystem was written by Jurgen Hannken-Illjes <hannken@NetBSD.org>.
BSD
April 13, 2010 BSD