mount(8) async description

[Giorgos Keramidas]

On 2006-08-27 03:42, Daniel Gerzo <danger at FreeBSD.org> 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?

Hi Daniel and everyone else,

In retrospect, having let this sink down for a few days, I think we
should also bear in mind Ruslan Ermilov's comments about referring to
the reader in second person.  Is there any way we can keep the same
meaning, stress the dangers of using ``-o async'' *and* avoid using
``you'' in the text?

This is definitely far across the borders of nit-picking, but perhaps we
can use something like this (based on the OpenBSD version, with the
fixes suggested by Matthew May <mdmay74 at internode.on.net>, and using the
backup/newfs text suggested by Daniel):

    async   All I/O to the file system should be done asynchronously.
            This is a dengerous flag to set, since it does not guarantee
            that the file system structure on the disk will remain
            consistent.  For this reason, the `async' flag should not be
            used unless some application-specific data recovery
            mechanism is present, or recreation of the file system is
            not a problem.

Does this look less wordy and still useful as a change?

- Giorgos

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20060904/7ce95472/attachment.sig>