fstrans(9) - NetBSD Manual Pages

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_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 sus-
     pension.  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 pre-
                           pares 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;
     }


CODE REFERENCES

     The actual code implementing this subsystem can be found 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>.

NetBSD 7.1.2                    April 13, 2010                    NetBSD 7.1.2