mount(8) async description

[Matthew May]

Hi Daniel,

Daniel wrote:
 >
 > Hello doc,
 >
 >   Milos Vyletel [mv(a)rulez.sk] noticed me about the current
 >   description of the async flag for the mount -- we currently have:
 >
 >   async   All I/O to the file system should be done asynchronously.
 > `         This is a dangerous flag to set, and should not be used
 >           unless you are prepared to recreate the file system
 >           should your system crash.
 >
 >
 >   Firstly, we thought that the last line is wrong, that
 >   s/should/after/ would work, but I was told that the current version
 >   is proper English.
 >
 >   But I still agree with Milos and I don't like the current
 >   description, therefore I produced a patch which says:
 >
 >   async   All I/O to the file system should be done asynchronously.
 >           This is a dangerous flag to set, although it increases
 >           I/O performance.  When this option is used, it is not
 >           guaranteed to keep a consistent file system structure on
 >           the disk, and it is impossible to verify the integrity of
 >           data.  It should be used only if some application-spe-
 >           cific data recovery mechanism is present, or recreation
 >           of the file system is not a problem.
 >
 >   I passed this through my mentors, it was OK'd by Tom, but Giorgos
 >   says it's too wordy and he likes NetBSD's description:
 >
 >   async    All I/O to the file system should be done asyn-
 >            chronously.  In the event of a crash, it is
 >            impossible for the system to verify the integrity of
 >            data on a file system mounted with this option.  You
 >            should only use this option if you have an applica-
 >            tion-specific data recovery mechanism, or are willing
 >            to recreate the file system from scratch.
 >
 >   To be complete, OpenBSD has:
 >
 >   async   All I/O to the file system should be done asynchronously.
 >           This is a dangerous flag to set since it does not guaran-
 >           tee to keep a consistent file system structure on the
 >           disk.  You should not use this flag unless you are pre-
 >           pared to recreate the file system should your system
 >           crash.  The most common use of this flag is to speed up
 >           restore(8) where it can give a factor of two speed in-
 >           crease.
 >
 >   Giorgos told me to go through doc@ and ask what other people think.
 >   So here it is. What do you think about my description? Would you
 >   accept it, or should I trim it a bit? Or just pick the NetBSD's one
 >   and commit?
 >
 > -- Best regards, Daniel mailto:danger at FreeBSD.org


I haven't posted to this list before, but I've been lurking for a while. 
  I'm working on getting my system set up so that I can contribute as 
well, but for the moment:

For what it's worth, I think NetBSD's description is pretty good. 
(That's from an English language point of view as well as from a lack of 
ambiguity / confusion point of view :-)



As far as OpenBSD's description goes, I'm happy with the meaning but 
slightly unsure about the English language aspects of "... it does not 
guarantee to keep a consistent file system structure ...".  That doesn't 
strike me as being very "nice" English, but it seems pretty clear what 
it actually means.  If a sentence like that is considered necessary, I 
wonder if this would be nicer:

           This is a dangerous flag to set since it does not guaran-
           tee that the file system structure on the disk will remain
           consistent.  You should not use this flag unless you are pre-

I'm trying to think of nicer ways to say it, which are still unambiguous 
and don't use more words than are already used, and I'm finding it 
difficult.


My 2c :-)

MAtt.