From owner-freebsd-doc@FreeBSD.ORG Wed Aug 30 10:09:33 2006 Return-Path: X-Original-To: freebsd-doc@freebsd.org Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id C957116A4DA; Wed, 30 Aug 2006 10:09:33 +0000 (UTC) (envelope-from mdmay74@internode.on.net) Received: from ash25e.internode.on.net (ash25e.internode.on.net [203.16.214.182]) by mx1.FreeBSD.org (Postfix) with ESMTP id 4E69843D45; Wed, 30 Aug 2006 10:09:33 +0000 (GMT) (envelope-from mdmay74@internode.on.net) Received: from [192.168.0.2] (ppp122-228.lns2.adl2.internode.on.net [121.44.122.228]) by ash25e.internode.on.net (8.13.6/8.13.5) with ESMTP id k7UA9Ul6027847; Wed, 30 Aug 2006 19:39:31 +0930 (CST) (envelope-from mdmay74@internode.on.net) Message-ID: <44F5643A.9010908@internode.on.net> Date: Wed, 30 Aug 2006 19:41:06 +0930 From: Matthew May User-Agent: Mozilla Thunderbird 1.0.7 (X11/20051215) X-Accept-Language: en-us, en MIME-Version: 1.0 To: freebsd-doc@freebsd.org References: <20060827120052.1ECD416A514@hub.freebsd.org> In-Reply-To: <20060827120052.1ECD416A514@hub.freebsd.org> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Cc: Subject: Re: mount(8) async description X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 30 Aug 2006 10:09:34 -0000 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@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.