Module Name: src
Committed By: snj
Date: Sat Apr 11 06:59:21 UTC 2009
Modified Files:
src/share/man/man4 [netbsd-5]: wapbl.4
Log Message:
Pull up following revision(s) (requested by ad in ticket #687):
share/man/man4/wapbl.4: revisions 1.7-1.9
Sync with reality and be a bit less literal.
To generate a diff of this commit:
cvs rdiff -u -r1.6 -r1.6.6.1 src/share/man/man4/wapbl.4
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man4/wapbl.4
diff -u src/share/man/man4/wapbl.4:1.6 src/share/man/man4/wapbl.4:1.6.6.1
--- src/share/man/man4/wapbl.4:1.6 Sat Aug 2 14:29:12 2008
+++ src/share/man/man4/wapbl.4 Sat Apr 11 06:59:21 2009
@@ -1,6 +1,6 @@
-.\" $NetBSD: wapbl.4,v 1.6 2008/08/02 14:29:12 simonb Exp $
+.\" $NetBSD: wapbl.4,v 1.6.6.1 2009/04/11 06:59:21 snj Exp $
.\"
-.\" Copyright (c) 2008 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2008, 2009 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@@ -24,7 +24,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd July 21, 2008
+.Dd April 10, 2009
.Dt WAPBL 4
.Os
.Sh NAME
@@ -33,13 +33,12 @@
.Sh SYNOPSIS
.Cd options WAPBL
.Cd options WAPBL_DEBUG
-.Cd options WAPBL_DEBUG_SERIALIZE
.Sh DESCRIPTION
The
.Nm
-driver provides meta-data journaling for file systems. In
-particular, it is used with the fast file system (FFS) to provide
-rapid file system consistency checking after a system outage.
+driver provides meta-data journaling for file systems.
+In particular, it is used with the fast file system (FFS) to provide
+rapid file system consistency checking after a system outage.
It also provides better general-use performance over regular FFS.
.Pp
WAPBL currently maintains its journal in one of two locations:
@@ -54,13 +53,13 @@
.El
.Pp
A new journal is created automatically when a file system is mounted
-via
+via
.Xr mount 8
with the
-.Pa -o log
+.Fl o Ar log
option.
If no journal size has been specified with
-.Xr tunefs 8 ,
+.Xr tunefs 8 ,
then the size of the journal
will be based on 1MB of journal per 1GB of file system, to a maximum
journal size of 64MB.
@@ -125,7 +124,7 @@
will remove the log and then re-create it with the default size.
This method can also be used to grow or shrink the size of the journal.
.Pp
-With the journal,
+With the journal,
.Xr fsck 8
is no longer required at system boot.
If the system has been shutdown in an unclean fashion then the journal
@@ -134,92 +133,75 @@
can still be used to force a consistency check of the file system
should that be desired.
.Pp
-.Xr WAPBL 8
-has a number of debugging options.
-The option
-.Bd -unfilled -offset indent
-options WAPBL_DEBUG
-.Ed
-.Pp
-turns on general debugging.
-The option
-.Bd -unfilled -offset indent
-options WAPBL_DEBUG_SERIALIZE
-.Ed
-.Pp
-forces the serialization of all IO.
-This is currently be used to help alleviate a performance issue
-seen on multi-core machines, where multiple simultaneous extractions
-of tar-files can cause degenerate performance.
-.Pp
+For kernel developers, the compile time option
+.Dv WAPBL_DEBUG
+turns on debugging.
.Sh SEE ALSO
.Xr config 1 ,
.Xr fsck 8 ,
-.Xr newfs 8 ,
.Xr mount 8 ,
+.Xr newfs 8 ,
.Xr umount 8
-.Sh CAVEATS
-An unreplayed
-.Nm
-journal (eg after a crash or power failure) may cause problems if the
-file system is then used with an older kernel or userland what isn't
+.Sh HISTORY
+.An -nosplit
.Nm
-aware.
+was originally written by
+.An Darrin B. Jewell
+while at Wasabi Systems Inc.
+Wasabi Systems contributed the code to
+.Nx
+and was integrated by
+.An Simon Burge ,
+.An Antti Kantee ,
+.An Andy Doran ,
+and
+.An Greg Oster .
.Pp
-An older
+.Nm
+first appeared in
+.Nx 5.0 .
+.Sh CAVEATS
+Older releases of the system, and other systems that support the
+.Dv UFS
+format should only access
+.Nm
+file systems in read-only mode.
+Additionally, the
.Xr fsck 8
-that isn't
+command from such systems should not be run against
.Nm
-aware will not be able to deal with an in-filesystem log.
+file systems.
+Failure to observe these guidelines may damage the file system.
.Pp
.Nm
requires the super block to be in the UFS2 format.
-Older FFSv1 file systems will need to be updated to the newer super block
-layout with the
+The super block format can be checked using the
+.Fl s
+option with
+.Xr dumpfs 8 ,
+and older FFSv1 file systems will need to be updated to the newer
+super block layout with the
.Fl c
option to
.Xr fsck_ffs 8 .
.Pp
.Xr fsync 2
-causes the journal to be committed to disk, resulting in
-non-negligible performance issues.
+causes all outstanding metadata transactions to be committed to disk,
+introducing additional latency.
This can have an impact on database software and other software
that calls
.Xr fsync 2
often.
.Pp
File system snapshots
-.Xr ( fss 4 )
-currently do not work with
+.Pq Xr fss 4
+and quotas do not yet work with
.Nm .
.Pp
-There are some pending issues with high metadata-rate workloads (like
-multiple simultaneous tar-file extractions) resulting in degenerate file
-system performance.
-The current work-around is to use
-.Bd -unfilled -offset indent
-options WAPBL_DEBUG_SERIALIZE
-.Ed
-.Pp
-as mentioned above.
-.Pp
In-file system log allocation should be done on a relatively quiet
-file system. The error path for log allocation failures could result
-in a
+file system.
+The error path for log allocation failures could result in a
.Dq dangling inode
issue, requiring an
.Xr fsck 8
to fix.
-.Pp
-If the file system is full or close to full then making a journal can fail.
-.Sh HISTORY
-.Nm
-was originally written by Darrin B. Jewell while at Wasabi Systems Inc.
-Wasabi Systems contributed the code to
-.Nx
-and was integrated by Simon Burge, Antti Kantee, Andy Doran, and
-Greg Oster.
-.Pp
-.Nm
-first appeared in
-.Nx 5.0 .
