bin/45919: mount(8) manpage description of option union is unclear

[gnrp%komkon2.de@localhost]

>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:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Feb 03 12:10:00 +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