Document file synchronization issues

* doc/lispref/files.texi (Files and Storage): New section.

3 files changed, 32 insertions, 2 deletions

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index f195a41d54..7bf4690873 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1554,8 +1554,8 @@ delete-file}.  @xref{VC Delete/Rename}.
 
 @findex copy-file
 @cindex copying files
-  @kbd{M-x copy-file} reads the file @var{old} and writes a new file
-named @var{new} with the same contents.
+  @kbd{M-x copy-file} copies the contents of the file @var{old} to the
+file @var{new}.
 
 @findex copy-directory
   @kbd{M-x copy-directory} copies directories, similar to the
diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index b9e6466c87..35a1865148 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -41,6 +41,11 @@ You can alternatively request numbered backups; then each new backup
 file gets a new name.  You can delete old numbered backups when you
 don't want them any more, or Emacs can delete them automatically.
 
+  For performance, the operating system may not write the backup
+file's contents to secondary storage immediately, or may alias the
+backup data with the original until one or the other is later
+modified.  @xref{Files and Storage}.
+
 @menu
 * Making Backups::     How Emacs makes backup files, and when.
 * Rename or Copy::     Two alternatives: renaming the old file or copying it.
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 0aea1dfd9a..b912d7bc8f 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -41,6 +41,7 @@ to locale @code{system-messages-locale}, and decoded using coding system
                                simultaneous editing by two people.
 * Information about Files::  Testing existence, accessibility, size of files.
 * Changing Files::           Renaming files, changing permissions, etc.
+* Files and Storage::        Surviving power and media failures
 * File Names::               Decomposing and expanding file names.
 * Contents of Directories::  Getting a list of the files in a directory.
 * Create/Delete Dirs::       Creating and Deleting Directories.
@@ -1496,6 +1497,10 @@ error if they fail to perform their function, reporting the
 system-dependent error message that describes the reason for the
 failure.
 
+  For performance, the operating system may cache or alias changes
+made by these functions instead of writing them immediately to
+secondary storage.  @xref{Files and Storage}.
+
   In the functions that have an argument @var{newname}, if a file by the
 name of @var{newname} already exists, the actions taken depend on the
 value of the argument @var{ok-if-already-exists}:
@@ -1794,6 +1799,26 @@ The function returns @code{t} if it successfully sets the ACL of
 @var{filename}, @code{nil} otherwise.
 @end defun
 
+@node Files and Storage
+@section Files and Secondary Storage
+@cindex secondary storage
+
+After Emacs changes a file, there are two reasons the changes might
+not survive later failures of power or media, both having to do with
+efficiency.  First, the operating system might alias written data with
+data already stored elsewhere on secondary storage until one file or
+the other is later modified; this will lose both files if the only
+copy on secondary storage is lost due to media failure.  Second, the
+operating system might not write data to secondary storage
+immediately, which will lose the data if power is lost.
+
+Although both sorts of failures can largely be avoided by a suitably
+configured file system, such systems are typically more expensive or
+less efficient.  In more-typical systems, to survive media failure you
+can copy the file to a different device, and to survive a power
+failure you can invoke the @command{sync} utility (@pxref{sync
+invocation,,, coreutils, The @sc{gnu} @code{Coreutils} Manual}).
+
 @node File Names
 @section File Names
 @cindex file names