[src/uebayasi-xip]: src/share/man/man9 Add a FUNCTIONS section.

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/af2e771ae2e0
branches:  uebayasi-xip
changeset: 751652:af2e771ae2e0
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Mon Apr 12 21:28:56 2010 +0000

description:
Add a FUNCTIONS section.

In addition, small improvements to wording and markup.

diffstat:

 share/man/man9/fstrans.9 |  232 +++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 232 insertions(+), 0 deletions(-)

diffs (236 lines):

diff -r 244643586796 -r af2e771ae2e0 share/man/man9/fstrans.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/fstrans.9  Mon Apr 12 21:28:56 2010 +0000
@@ -0,0 +1,232 @@
+.\"     $NetBSD: fstrans.9,v 1.15.2.2 2010/04/12 21:28:56 jruoho Exp $
+.\"
+.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Juergen Hannken-Illjes.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd April 13, 2010
+.Dt FSTRANS 9
+.Os
+.Sh NAME
+.Nm fstrans ,
+.Nm fstrans_setstate ,
+.Nm fstrans_getstate ,
+.Nm fstrans_start ,
+.Nm fstrans_start_nowait ,
+.Nm fstrans_done ,
+.Nm fstrans_is_owner ,
+.Nm fscow_establish ,
+.Nm fscow_disestablish ,
+.Nm fscow_run
+.Nd file system suspension helper subsystem
+.Sh SYNOPSIS
+.In sys/mount.h
+.In sys/fstrans.h
+.Ft int
+.Fn fstrans_setstate "struct mount *mp" "enum fstrans_state new_state"
+.Ft "enum fstrans_state"
+.Fn fstrans_getstate "struct mount *mp"
+.Ft void
+.Fn fstrans_start "struct mount *mp" "enum fstrans_lock_type lock_type"
+.Ft int
+.Fn fstrans_start_nowait "struct mount *mp" "enum fstrans_lock_type lock_type"
+.Ft void
+.Fn fstrans_done "struct mount *mp"
+.Ft int
+.Fn fstrans_is_owner "struct mount *mp"
+.Ft int
+.Fn fscow_establish "struct mount *mp" \
+"int (*func)(void *, struct buf *, bool)" "void *cookie"
+.Ft int
+.Fn fscow_disestablish "struct mount *mp" \
+"int (*func)(void *, struct buf *, bool)" "void *cookie"
+.Ft int
+.Fn fscow_run "struct buf *bp" "bool data_valid"
+.Sh DESCRIPTION
+The
+.Nm
+subsystem is a set of operations to assist file system suspension.
+These operations must not be used outside of file systems.
+.Pp
+File systems supporting this subsystem must set the flag
+.Dv IMNT_HAS_TRANS
+in
+.Dv "mnt_iflag" .
+.Pp
+File systems are always in one of these states:
+.Pp
+.Bl -tag -offset indent -width FSTRANS_SUSPENDING -compact
+.It Dv FSTRANS_NORMAL
+Normal operations.
+.It Dv FSTRANS_SUSPENDING
+Preparing a suspension.
+.It Dv FSTRANS_SUSPENDED
+Suspended.
+.El
+.Pp
+This state is represented by
+.Vt "enum fstrans_state" .
+.Pp
+All file system operations use a
+.Em "fstrans lock" .
+This lock is recursive.
+A thread already owning a lock will always get another lock.
+The lock has two variants:
+.Bl -tag -offset indent -width FSTRANS_SHARED
+.It Dv FSTRANS_SHARED
+A lock that will be granted if the file system is in state
+.Dv FSTRANS_NORMAL .
+.It Dv FSTRANS_LAZY
+A lock that will be granted if the file system is in state
+.Dv FSTRANS_NORMAL
+or
+.Dv FSTRANS_SUSPENDING .
+It needs special care because operations using this variant will not block
+while the file system prepares suspension.
+.El
+.Pp
+The lock variant is represented by
+.Vt "enum fstrans_lock_type" .
+.Sh FUNCTIONS
+The following functions comprise the
+.Tn API
+provided by
+.Nm .
+.Bl -tag -width compact
+.It Fn fstrans_getstate "mp"
+Returns the current state of the file system
+.Fa mp .
+.It Fn fstrans_setstate "mp" "new_state"
+Changes the state of the file system
+.Fa mp
+to
+.Fa new_state .
+.It Fn fstrans_start "mp" "lock_type"
+Sets a lock of type
+.Fa lock_type
+on the file system
+.Fa mp .
+.It Fn fstrans_start_nowait "mp" "lock_type"
+Like
+.Fn 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.
+.It Fn fstrans_done "mp"
+Releases a lock on the file system
+.Fa mp .
+.It Fn fstrans_is_owner "mp"
+Returns
+.Dv true
+if this thread is currently suspending the file system
+.Fa mp .
+.It Fn fscow_establish "mp" "func" "cookie"
+Establish a copy-on-write callback for the file system
+.Fa mp .
+The function
+.Fa func
+will be called for every buffer written through this file system.
+.It Fn fscow_disestablish "mp" "func" "cookie"
+Disestablish a copy-on-write callback registered with
+.Fn fscow_establish .
+.It Fn fscow_run "bp" "data_valid"
+Run all copy-on-write callbacks established for the file system this buffer
+belongs to.
+If
+.Fa data_valid
+is
+.Dv true
+the buffer data has not yet been modified.
+.El
+.Sh RETURN VALUES
+The functions
+.Fn fstrans_setstate
+and
+.Fn fstrans_start_nowait
+return zero on success and an error value on failure.
+.Sh EXAMPLES
+The following is an example of a file system suspend operation.
+.Bd -literal
+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;
+       }
+}
+.Ed
+.Pp
+This is an example of a file system operation.
+.Bd -literal
+int
+xxx_create(void *v)
+{
+       struct vop_create_args *ap = v;
+       struct mount *mp = ap-\*[Gt]a_dvp-\*[Gt]v_mount;
+       int error;
+
+       if ((error = fstrans_start(mp, FSTRANS_SHARED)) != 0)
+               return error;
+
+       /* Actually create the node. */
+
+       fstrans_done(mp);
+
+       return 0;
+}
+.Ed
+.Sh SEE ALSO
+.Xr vfs_resume 9 ,
+.Xr vfs_suspend 9
+.Sh CODE REFERENCES
+The actual code implementing this subsystem can be found in the file
+.Pa sys/kern/vfs_trans.c .
+.Sh HISTORY
+The
+.Nm
+subsystem appeared in
+.Nx 5.0 .
+.Sh AUTHORS
+The
+.Nm
+subsystem was written by
+.An J\(:urgen Hannken-Illjes
+.Aq hannken%NetBSD.org@localhost .