(Traversing symlinks, Treating / specially): New sections.

(rm invocation, chown invocation, chmod invocation, chgrp invocation):
Describe new options, --preserve-root and --no-preserve-root.

1 files changed, 130 insertions, 39 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index a47048b19..3b2ecacd5 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -201,6 +201,8 @@ Common Options
 * Block size::                  Block size
 * Target directory::            Target directory
 * Trailing slashes::            Trailing slashes
+* Traversing symlinks::         Traversing symlinks to directories
+* Treating / specially::        Treating / specially
 * Standards conformance::       Standards conformance
 
 Output of entire files
@@ -548,6 +550,8 @@ context that requires a file name.
 * Block size::                  BLOCK_SIZE and --block-size, in some programs.
 * Target directory::            --target-directory, in some programs.
 * Trailing slashes::            --strip-trailing-slashes, in some programs.
+* Traversing symlinks::         -H, -L, or -P, in some programs.
+* Treating / specially::        --preserve-root and --no-preserve-root.
 * Standards conformance::       Conformance to the @acronym{POSIX} standard.
 @end menu
 
@@ -894,6 +898,79 @@ the symbolic link.  Although it may seem surprising that such behavior
 be the default, it is required by @acronym{POSIX} and is consistent with
 other parts of that standard.
 
+@node Traversing symlinks
+@section Traversing symlinks
+
+@macro chownchgrpoptions
+
+@cindex symbolic link to directory, controlling traversal of
+
+The following options modify how @command{chown} and @command{chgrp}
+@c FIXME: note that `du' has these options, too, but they have slightly
+@c different meaning.
+traverse a hierarchy when the @option{--recursive} (@option{-R})
+option is also specified.
+If more than one is specified, only the final one takes effect.
+These options determine whether processing a symbolic link to a directory
+entails operating on just the symbolic link or on all files in the
+hierarchy rooted at that directory.
+Note that these options are independent of @option{--dereference} and
+@option{--no-dereference} (@option{-h}), which control whether to modify
+a symlink or its referent.
+
+@table @samp
+
+@item -H
+@opindex -H
+@cindex symbolic link to directory, traverse each that is specified on the command line
+If @option{--recursive} (@option{-R}) is specified and
+a command line argument is a symbolic link to a directory, traverse it.
+
+@item -L
+@opindex -L
+@cindex symbolic link to directory, traverse each that is encountered
+In a recursive traversal, traverse every symbolic link to a directory
+that is encountered.
+
+@item -P
+@opindex -P
+@cindex symbolic link to directory, never traverse
+Do not traverse any symbolic links.
+This is the default if none of @option{-H}, @option{-L},
+or @option{-P} is specified.
+
+@end table
+@end macro
+
+@chownchgrpoptions
+
+
+@node Treating / specially
+@section Treating / specially
+
+Certain commands can operate destructively on entire hierarchies.
+For example, if a user with appropriate privileges mistakenly runs
+@samp{rm -rf / tmp/junk} or @samp{cd /bin; rm -rf ../}, that may remove
+all files on the entire system.  Since there are so few
+@footnote{If you know of one, please write to @email{bug-coreutils@@gnu.org}.}
+legitimate uses for such a command,
+@sc{gnu} @command{rm} provides the @option{--preserve-root} option
+to make it so @command{rm} declines to operate on any directory
+that resolves to @file{/}.  The default is still to allow
+@samp{rm -rf /} to operate unimpeded.
+Another new option, @option{--no-preserve-root}, cancels the
+effect of any preceding @option{--preserve-root} option.
+Note that the @option{--preserve-root} behavior may become the default
+for @command{rm}.
+
+The commands @command{chgrp}, @command{chmod} and @command{chown}
+can also operate destructively on entire hierarchies, so they too
+support these options.  Although, unlike @command{rm}, they don't
+actually unlink files, these commands are arguably more dangerous
+when operating recursively on @file{/}, since they often work much
+more quickly, and hence damage more files before an alert user can
+interrupt them.
+
 @node Standards conformance
 @section Standards conformance
 
@@ -6705,6 +6782,20 @@ Prompt whether to remove each file.  If the response does not begin
 with @samp{y} or @samp{Y}, the file is skipped.
 Ignore any previous @option{--force} (@option{-f}) option.
 
+@itemx --preserve-root
+@opindex --preserve-root
+@cindex root directory, disallow recursive destruction
+Fail upon any attempt to remove the filesystem root, @file{/},
+when used with the @option{--recursive} option.
+Without @option{--recursive}, this option has no effect.
+@xref{Treating / specially}.
+
+@itemx --no-preserve-root
+@opindex --no-preserve-root
+@cindex root directory, allow recursive destruction
+Cancel the effect of any preceding @option{--preserve-root} option.
+@xref{Treating / specially}.
+
 @item -r
 @itemx -R
 @itemx --recursive
@@ -7644,6 +7735,19 @@ is a symbolic link.
 By default, no diagnostic is issued for symbolic links encountered
 during a recursive traversal, but see @option{--verbose}.
 
+@itemx --preserve-root
+@opindex --preserve-root
+@cindex root directory, disallow recursive modification
+Fail upon any attempt to recursively change the filesystem root, @file{/}.
+Without @option{--recursive}, this option has no effect.
+@xref{Treating / specially}.
+
+@itemx --no-preserve-root
+@opindex --no-preserve-root
+@cindex root directory, allow recursive modification
+Cancel the effect of any preceding @option{--preserve-root} option.
+@xref{Treating / specially}.
+
 @item --reference=@var{ref_file}
 @opindex --reference
 Change the user and group of each @var{file} to be the same as those of
@@ -7670,45 +7774,6 @@ Recursively change ownership of directories and their contents.
 
 @end table
 
-@macro chownchgrpoptions
-
-@cindex symbolic links, controlling traversal of
-
-The following options modify how @command{chown} and @command{chgrp}
-traverse a hierarchy when the @option{--recursive} (@option{-R})
-option is also specified.
-If more than one is specified, only the final one takes effect.
-These options determine whether processing a symbolic link to a directory
-entails operating on just the symbolic link or on all files in the
-hierarchy rooted at that directory.
-Note that these options are independent of @option{--dereference} and
-@option{--no-dereference} (@option{-h}), which control whether to modify
-a symlink or its referent.
-
-@table @samp
-
-@item -H
-@opindex -H
-@cindex traverse symbolic links specified on the command line
-If @option{--recursive} (@option{-R}) is specified and
-a command line argument is a symbolic link to a directory, traverse it.
-
-@item -L
-@opindex -L
-@cindex traverse every symbolic link to a directory encountered
-In a recursive traversal, traverse every symbolic link to a directory
-that is encountered.
-
-@item -P
-@opindex -P
-@cindex do not traverse any symbolic links
-Do not traverse any symbolic links.
-This is the default if none of @option{-H}, @option{-L},
-or @option{-P} is specified.
-
-@end table
-@end macro
-
 @chownchgrpoptions
 
 
@@ -7770,6 +7835,19 @@ is a symbolic link.
 By default, no diagnostic is issued for symbolic links encountered
 during a recursive traversal, but see @option{--verbose}.
 
+@itemx --preserve-root
+@opindex --preserve-root
+@cindex root directory, disallow recursive modification
+Fail upon any attempt to recursively change the filesystem root, @file{/}.
+Without @option{--recursive}, this option has no effect.
+@xref{Treating / specially}.
+
+@itemx --no-preserve-root
+@opindex --no-preserve-root
+@cindex root directory, allow recursive modification
+Cancel the effect of any preceding @option{--preserve-root} option.
+@xref{Treating / specially}.
+
 @item --reference=@var{ref_file}
 @opindex --reference
 Change the group of each @var{file} to be the same as that of
@@ -7845,6 +7923,19 @@ actually changes.
 Do not print error messages about files whose permissions cannot be
 changed.
 
+@itemx --preserve-root
+@opindex --preserve-root
+@cindex root directory, disallow recursive modification
+Fail upon any attempt to recursively change the filesystem root, @file{/}.
+Without @option{--recursive}, this option has no effect.
+@xref{Treating / specially}.
+
+@itemx --no-preserve-root
+@opindex --no-preserve-root
+@cindex root directory, allow recursive modification
+Cancel the effect of any preceding @option{--preserve-root} option.
+@xref{Treating / specially}.
+
 @item -v
 @itemx --verbose
 @opindex -v