FSTRANS(9)             NetBSD 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_mount(struct mount *mp);

     void
     fstrans_unmount(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_setstate(struct mount *mp, enum fstrans_state new_state);

     enum fstrans_state
     fstrans_getstate(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 assists file system suspension and copy-on-write
     snapshots.

     For a file system to use fstrans, its VFS_MOUNT(9) method must call
     fstrans_mount(), and its VFS_UNMOUNT(9) method must call
     fstrans_unmount().

     The file system's normal operations, such as its vnodeops(9), must be
     bracketed by fstrans_start() and fstrans_done() in a shared transaction,
     which is blocked by suspending the file system and while it is suspended.

     Operations needed to sync the file system to its backing store must be
     bracketed by fstrans_start() and fstrans_done() in a lazy transaction,
     which is allowed while suspending the file system in order to sync it to
     its backing store, but blocked while the file system is suspended.

     Transactions are per-thread and nestable: if a thread is already in a
     transaction, it can enter another transaction without blocking.  Each
     fstrans_start() must be paired with fstrans_done().  Transactions for
     multiple distinct mount points may not be nested.

     The file system's VFS_SUSPENDCTL(9) method can use fstrans_setstate() to:

     -   enter the FSTRANS_SUSPENDING to suspend all normal operations but
         allow syncing,

     -   enter the FSTRANS_SUSPENDED state to suspend all operations once
         synced, and

     -   restore to the FSTRANS_NORMAL state to resume all operations.

     A file system supporting fstrans may establish a copy-on-write callback
     with fscow_establish().  The copy-on-write callback will be called every
     time a buffer is written to a block device with VOP_STRATEGY() and every
     time a buffer is read into the buffercache(9) with B_MODIFY set indicat-
     ing the caller's intent to modify it.  Anyone modifying a buffer may
     additionally use fscow_run() to explicitly invoke the established call-
     back.  The copy-on-write callback must be disestablished with
     fscow_disestablish() when the file system is done with it.

FUNCTIONS
     fstrans_mount(mp)
           Initialize the fstrans subsystem for the file system mounted at mp.
           Sets IMNT_HAS_TRANS in mp->mnt_iflag.  Return zero on success, or
           error code if vfs_busy(9) fails.

           May sleep.

     fstrans_unmount(mp)
           Finalize the fstrans subsystem.  Clears IMNT_HAS_TRANS in
           mp->mnt_iflag.  Caller is responsible for ensuring that no transac-
           tions are active.

           May sleep.

     fstrans_start(mp, lock_type)
           Enter a transaction of type lock_type on the file system mp in the
           current thread.  If the file system is in a state that blocks such
           transactions, wait until it changes state to one that does not.

           FSTRANS_SHARED  If the file system is suspending or suspended, wait
                           until it is resumed.  Intended for normal file sys-
                           tem operations.

           FSTRANS_LAZY    If the file system is suspended, wait until it is
                           resumed.  Intended for operations needed to sync
                           the file system to its backing store in order to
                           suspend it.

           However, if the current thread is already in a transaction on mp,
           fstrans_start() will enter a nested transaction and return immedi-
           ately without waiting.

           May sleep.

     fstrans_start_nowait(mp, lock_type)
           Like fstrans_start(), but return EBUSY immediately if lock_type
           transactions are blocked in its current state.

           May sleep nevertheless on internal locks.

     fstrans_done(mp)
           End the current transaction on mp.

     fstrans_getstate(mp)
           Return the current state of the file system mp.

           Must be called within a transaction for the answer to be stable.

     fstrans_setstate(mp, new_state)
           Change the state of the file system mp to new_state, and wait for
           all transactions not allowed in new_state to complete.

           FSTRANS_NORMAL      Allow all transactions.

           FSTRANS_SUSPENDING  Block FSTRANS_SHARED transactions but allow
                               FSTRANS_LAZY transactions.

           FSTRANS_SUSPENDED   Block all transactions.

           A thread that changes a file system to a state other than
           FSTRANS_NORMAL enters a transaction for the purposes of
           fstrans_getstate() until it changes state back to FSTRANS_NORMAL.

           Additionally, a thread that changes a file system to a state other
           than FSTRANS_NORMAL acquires an exclusive lock on the file system
           state, so that fstrans_is_owner() will return true in that thread,
           and no other thread can change the file system's state until the
           owner restores it to FSTRANS_NORMAL.

           May sleep, and may be interrupted by a signal.  On success, return
           zero.  On failure, restore the file system to the FSTRANS_NORMAL
           state and return an error code.  fstrans_setstate() never fails if
           new_state is FSTRANS_NORMAL.

     fstrans_is_owner(mp)
           Return true if the current 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 bp written through
           this file system as
                 func(cookie, bp, data_valid)
           where data_valid is true if and only if the buffer bp has not yet
           been modified.

           May sleep.

     fscow_disestablish(mp, func, cookie)
           Disestablish a copy-on-write callback established with
           fscow_establish().

           May sleep.

     fscow_run(bp, data_valid)
           Run all copy-on-write callbacks established for the file system
           this buffer belongs to, if they have not already been run for this
           buffer.  If data_valid is true the buffer data has not yet been
           modified.

           May sleep.

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)
                             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;

             fstrans_start(mp, FSTRANS_SHARED);

             /* Actually create the node. */

             fstrans_done(mp);

             return 0;
     }

CODE REFERENCES
     The fstrans subsystem is implemented in the file sys/kern/vfs_trans.c.

SEE ALSO
     vfs_resume(9), vfs_suspend(9)

HISTORY
     The fstrans subsystem appeared in NetBSD 5.0.

AUTHORS
     The fstrans subsystem was written by Jürgen Hannken-Illjes
     <hannken@NetBSD.org>.

BUGS
     fstrans is useful only for temporary suspension -- it does not help to
     permanently block file system operations for unmounting, because
     fstrans_start() cannot fail.

NetBSD 7.0                      March 31, 2015                      NetBSD 7.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2015 Modified for NetBSD by Kimmo Suominen