kern/45711: integrity properties of file systems are badly documented

[Taylor R Campbell <campbell+netbsd%mumble.net@localhost>]

>Number:         45711
>Category:       kern
>Synopsis:       integrity properties of file systems are badly documented
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Tue Dec 13 23:00:01 +0000 2011
>Originator:     Taylor R Campbell <campbell+netbsd%mumble.net@localhost>
>Release:        NetBSD 5.99.58
>Organization:
>Environment:
System: NetBSD oberon.local 5.99.58 NetBSD 5.99.58 (RIAMONOHACK) #4: Sat Dec 10 
23:18:29 UTC 2011 
root@oberon.local:/home/riastradh/netbsd/current/obj/sys/arch/i386/compile/RIAMONOHACK
 i386
Architecture: i386
Machine: i386
>Description:

        The assumptions made by our file systems and the intended
        integrity guarantees they are supposed to provide, particularly
        related to the meaning of fsck, `mount -o sync', and wapbl, are
        badly documented, and users are very confused about them.

>How-To-Repeat:

        Read tech-kern and try not to submerge in a sea of confusion.

>Fix:

        We ought to write down somewhere what assumptions the file
        systems make about the underlying disk devices, such as
        atomicity and ordering of disk sector writes and how those
        relate to disk write caches and power failures.

        We ought to clarify what integrity guarantees the file systems
        make, and how fsck/replay/&c. enforce those, and how fsck
        additionally sometimes works as a diagnostic or debugging tool
        when the assumptions may have broken down or bugs have
        manifested in the file systems.