NetBSD Problem Report #45919

From www@NetBSD.org  Fri Feb  3 12:09:35 2012
Return-Path: <www@NetBSD.org>
Received: from mail.netbsd.org (mail.netbsd.org [149.20.53.66])
	by www.NetBSD.org (Postfix) with ESMTP id B5A2F63E026
	for <gnats-bugs@gnats.NetBSD.org>; Fri,  3 Feb 2012 12:09:34 +0000 (UTC)
Message-Id: <20120203120933.BFFC463DF88@www.NetBSD.org>
Date: Fri,  3 Feb 2012 12:09:33 +0000 (UTC)
From: gnrp@komkon2.de
Reply-To: gnrp@komkon2.de
To: gnats-bugs@NetBSD.org
Subject: mount(8) manpage description of option union is unclear
X-Send-Pr-Version: www-1.0

>Number:         45919
>Category:       bin
>Synopsis:       mount(8) manpage description of option union is unclear
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bin-bug-people
>State:          closed
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Feb 03 12:10:00 +0000 2012
>Closed-Date:    Sat Jun 23 23:32:29 +0000 2012
>Last-Modified:  Sat Jun 23 23:32:29 +0000 2012
>Originator:     Julian Fagir
>Release:        current
>Organization:
>Environment:
>Description:
The mount(8) manpage describes the 'union' option not as clear as it should be.
Though it mentions the functionality of the option, you could still confuse it with mount_union(8).

Imho, the appended patch clarifies this issue.
>How-To-Repeat:
man 8 mount
>Fix:
--- sbin/mount/mount.8
+++ sbin/mount/mount.8
@@ -307,10 +307,20 @@
 Lookups will be done in the mounted file system first.
 If those operations fail due to a non-existent file the underlying
 directory is then accessed.
 All creates are done in the mounted file system, except for the fdesc
 file system.
+.Pp
+Note that this option is fundamentally different to
+.Xr mount_union 8 .
+The underlying file system is still used if the file exists,
+.Em only
+file lookup and reading directory contents
+.Xr ( readdir 3 )
+is affected! So e.g. write
+operations on directories that exist on the underlying layer will still fail on 
+read-only or full filesystems.
 .It Cm update
 The same as
 .Fl u ;
 indicate that the status of an already mounted file system should be changed.
 .El

>Release-Note:

>Audit-Trail:
From: Julian Fagir <gnrp@komkon2.de>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: bin/45919: mount(8) manpage description of option union is
 unclear
Date: Mon, 9 Apr 2012 21:08:54 +0200

 --MP_/OCvkzCr90.5x8frwDJpeNTW
 Content-Type: text/plain; charset=US-ASCII
 Content-Transfer-Encoding: 7bit
 Content-Disposition: inline

 Hi,

 apb proposed the following text rather than the one before, clearly written
 in a better language.

 Regards, Julian
 --MP_/OCvkzCr90.5x8frwDJpeNTW
 Content-Type: text/x-patch
 Content-Transfer-Encoding: 7bit
 Content-Disposition: attachment; filename=mount.8.diff

 Index: ./sbin/mount/mount.8
 ===================================================================
 RCS file: /cvsroot/src/sbin/mount/mount.8,v
 retrieving revision 1.74
 diff -u -r1.74 mount.8
 --- ./sbin/mount/mount.8	22 Jul 2011 15:53:21 -0000	1.74
 +++ ./sbin/mount/mount.8	9 Apr 2012 19:07:14 -0000
 @@ -303,12 +303,32 @@
  mode.
  .It Cm union
  Causes the namespace at the mount point to appear as the union
 -of the mounted file system root and the existing directory.
 -Lookups will be done in the mounted file system first.
 -If those operations fail due to a non-existent file the underlying
 -directory is then accessed.
 -All creates are done in the mounted file system, except for the fdesc
 -file system.
 +of the mounted file system root
 +(referred to as the
 +.Em upper
 +layer), and the existing directory
 +(referred to as the
 +.Em lower
 +layer).
 +Name lookups will be done in the upper layer first.
 +If a name does not exist in the upper layer, then the name
 +will be looked up in the lower layer.
 +If a name exists in both the upper and lower layers, then only
 +the upper instance is accessible.
 +Creation of new files is done in the upper layer,
 +except in the case of the fdesc file system (see
 +.Xr mount_fdesc 8 ) .
 +.Pp
 +Note that the
 +.Cm union
 +option can be applied to any type of file system,
 +and is fundamentally different from
 +.Xr mount_union 8 ,
 +which is a particular type of file system.
 +Also note that the
 +.Cm union
 +option affects the file system name space only at the mount point
 +itself; it does not apply recursively to subdirectories.
  .It Cm update
  The same as
  .Fl u ;

 --MP_/OCvkzCr90.5x8frwDJpeNTW--

From: "Julian Fagir" <jdf@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/45919 CVS commit: src/sbin/mount
Date: Sat, 23 Jun 2012 23:17:47 +0000

 Module Name:	src
 Committed By:	jdf
 Date:		Sat Jun 23 23:17:46 UTC 2012

 Modified Files:
 	src/sbin/mount: mount.8

 Log Message:
 Clarify use of the union option for mount, as proposed in PR 45919.
 Text proposed by apb.


 To generate a diff of this commit:
 cvs rdiff -u -r1.74 -r1.75 src/sbin/mount/mount.8

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

From: Julian Fagir <gnrp@komkon2.de>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: bin/45919: mount(8) manpage description of option union is
 unclear
Date: Sun, 24 Jun 2012 01:20:39 +0200

 --Sig_/pk0m6sx0JKDTT=fIvVtU08q
 Content-Type: text/plain; charset=US-ASCII
 Content-Transfer-Encoding: quoted-printable

 This patch has been applied, I just had a typo in the commit message, so it
 wasn't appended here.

 --Sig_/pk0m6sx0JKDTT=fIvVtU08q
 Content-Type: application/pgp-signature; name=signature.asc
 Content-Disposition: attachment; filename=signature.asc

 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v2.0.18 (NetBSD)

 iEYEARECAAYFAk/mT0wACgkQc7h7cu1Hpp5N/QCggliI+Cbtjpbc9vgj96SvrKef
 c6kAoIbr+jPa/UlwbbD9AoGVZWGId1Bt
 =eCbp
 -----END PGP SIGNATURE-----

 --Sig_/pk0m6sx0JKDTT=fIvVtU08q--

State-Changed-From-To: open->closed
State-Changed-By: jdf@NetBSD.org
State-Changed-When: Sat, 23 Jun 2012 23:32:29 +0000
State-Changed-Why:
Patch applied


>Unformatted:

Home	PR Database Search