Unionfs: clarify usage.txt read/write behavior

CC: Michael Tokarev <mjt@tls.msk.ru>
Signed-off-by: Erez Zadok <ezk@cs.sunysb.edu>

diff --git a/Documentation/filesystems/unionfs/concepts.txt b/Documentation/filesystems/unionfs/concepts.txt
index 7654ccca1343628fce1fd0d57b8c5435bd79a575..bed69bdc87d7165179cbc53f3a4a092d08be983b 100644 (file)
--- a/Documentation/filesystems/unionfs/concepts.txt
+++ b/Documentation/filesystems/unionfs/concepts.txt
@@ -1,4 +1,4 @@
-Unionfs 2.1 CONCEPTS:
+Unionfs 2.x CONCEPTS:
 =====================
 
 This file describes the concepts needed by a namespace unification file
@@ -66,12 +66,26 @@ Copyup:
 =======
 
 When a change is made to the contents of a file's data or meta-data, they
-have to be stored somewhere. The best way is to create a copy of the
+have to be stored somewhere.  The best way is to create a copy of the
 original file on a branch that is writable, and then redirect the write
-though to this copy. The copy must be made on a higher priority branch so
+though to this copy.  The copy must be made on a higher priority branch so
 that lookup and readdir return this newer "version" of the file rather than
 the original (see duplicate elimination).
 
+An entire unionfs mount can be read-only or read-write.  If it's read-only,
+then none of the branches will be written to, even if some of the branches
+are physically writeable.  If the unionfs mount is read-write, then the
+leftmost (highest priority) branch must be writeable (for copyup to take
+place); the remaining branches can be any mix of read-write and read-only.
+
+In a writeable mount, unionfs will create new files/dir in the leftmost
+branch.  If one tries to modify a file in a read-only branch/media, unionfs
+will copyup the file to the leftmost branch and modify it there.  If you try
+to modify a file from a writeable branch which is not the leftmost branch,
+then unionfs will modify it in that branch; this is useful if you, say,
+unify differnet packages (e.g., apache, sendmail, ftpd, etc.) and you want
+changes to specific package files to remain logically in the directory where
+they came from.
 
 Cache Coherency:
 ================

diff --git a/Documentation/filesystems/unionfs/issues.txt b/Documentation/filesystems/unionfs/issues.txt
index 9db1d7017f352c345552f2476025b688c7f80cd8..bb6ab052c17c7694cdeec96b42d5018369d268ad 100644 (file)
--- a/Documentation/filesystems/unionfs/issues.txt
+++ b/Documentation/filesystems/unionfs/issues.txt
@@ -1,4 +1,4 @@
-KNOWN Unionfs 2.1 ISSUES:
+KNOWN Unionfs 2.x ISSUES:
 =========================
 
 1. Unionfs should not use lookup_one_len() on the underlying f/s as it

diff --git a/Documentation/filesystems/unionfs/usage.txt b/Documentation/filesystems/unionfs/usage.txt
index 59c4f283abfb8841b10be2e6a12acba64ed6bd2d..1adde69e1ea60c7694bf2b5b246b88ec41c4b9d0 100644 (file)
--- a/Documentation/filesystems/unionfs/usage.txt
+++ b/Documentation/filesystems/unionfs/usage.txt
@@ -12,7 +12,7 @@ GENERAL SYNTAX
 
 # mount -t unionfs -o <OPTIONS>,<BRANCH-OPTIONS> none MOUNTPOINT
 
-OPTIONS can be any legal combination one of:
+OPTIONS can be any legal combination of:
 
 - ro           # mount file system read-only
 - rw           # mount file system read-write
@@ -20,8 +20,9 @@ OPTIONS can be any legal combination one of:
 - incgen       # increment generation no. (see Cache Consistency below)
 
 BRANCH-OPTIONS can be either (1) a list of branches given to the "dirs="
-option, or (2) a list of individual branch manipulation commands, described
-in the "Branch Management" section below.
+option, or (2) a list of individual branch manipulation commands, combined
+with the "remount" option, and is further described in the "Branch
+Management" section below.
 
 The syntax for the "dirs=" mount option is:
 
@@ -32,7 +33,9 @@ the union, with an optional branch mode for each of those directories.
 Directories that come earlier (specified first, on the left) in the list
 have a higher precedence than those which come later.  Additionally,
 read-only or read-write permissions of the branch can be specified by
-appending =ro or =rw (default) to each directory.
+appending =ro or =rw (default) to each directory.  See the Copyup section in
+concepts.txt, for a description of Unionfs's behavior when mixing read-only
+and read-write branches and mounts.
 
 Syntax:
 
@@ -112,7 +115,7 @@ CACHE CONSISTENCY
 =================
 
 If you modify any file on any of the lower branches directly, while there is
-a Unionfs 2.1 mounted above any of those branches, you should tell Unionfs
+a Unionfs 2.x mounted above any of those branches, you should tell Unionfs
 to purge its caches and re-get the objects.  To do that, you have to
 increment the generation number of the superblock using the following
 command: