From owner-freebsd-doc@FreeBSD.ORG Mon Sep 4 04:36:25 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 4405816A4DE; Mon, 4 Sep 2006 04:36:25 +0000 (UTC) (envelope-from keramida@FreeBSD.org) Received: from igloo.linux.gr (igloo.linux.gr [62.1.205.36]) by mx1.FreeBSD.org (Postfix) with ESMTP id 6605F43D45; Mon, 4 Sep 2006 04:36:23 +0000 (GMT) (envelope-from keramida@FreeBSD.org) Received: from gothmog.pc (host5.bedc.ondsl.gr [62.103.39.229]) (authenticated bits=128) by igloo.linux.gr (8.13.7/8.13.7/Debian-2) with ESMTP id k844aA34031083 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Mon, 4 Sep 2006 07:36:12 +0300 Received: from gothmog.pc (gothmog [127.0.0.1]) by gothmog.pc (8.13.7/8.13.7) with ESMTP id k844aVvI005635; Mon, 4 Sep 2006 07:36:31 +0300 (EEST) (envelope-from keramida@FreeBSD.org) Received: (from giorgos@localhost) by gothmog.pc (8.13.7/8.13.7/Submit) id k844aVNO005634; Mon, 4 Sep 2006 07:36:31 +0300 (EEST) (envelope-from keramida@FreeBSD.org) Date: Mon, 4 Sep 2006 07:36:31 +0300 From: Giorgos Keramidas To: Daniel Gerzo , Tom Rhodes Message-ID: <20060904043631.GA5039@gothmog.pc> References: <2510186921.20060827034225@rulez.sk> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="AqsLC8rIMeq19msA" Content-Disposition: inline In-Reply-To: <2510186921.20060827034225@rulez.sk> X-Hellug-MailScanner: Found to be clean X-Hellug-MailScanner-SpamCheck: not spam, SpamAssassin (score=-3.034, required 5, autolearn=not spam, AWL -0.44, BAYES_00 -2.60, UNPARSEABLE_RELAY 0.00) X-Hellug-MailScanner-From: keramida@freebsd.org X-Spam-Status: No Cc: freebsd-doc@FreeBSD.org 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: Mon, 04 Sep 2006 04:36:25 -0000 --AqsLC8rIMeq19msA Content-Type: text/plain; charset=us-ascii Content-Disposition: inline On 2006-08-27 03:42, Daniel Gerzo 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 , 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 --AqsLC8rIMeq19msA Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.5 (FreeBSD) iD8DBQFE+61P1g+UGjGGA7YRAhxoAJ9cINpa45EeQpYUpV4HCeerjv/dqgCfdH/D HwF69OTIPZ4n8awCQ3B5MMU= =61qe -----END PGP SIGNATURE----- --AqsLC8rIMeq19msA--