comparison man/files.texi @ 65532:1a6c78b455d7

(Saving Commands): New node, broken out of Saving. (Customize Save): New node, broken out of Saving. Clarify effect of write-region-inhibit-fsync. (Misc File Ops): Say write-region-inhibit-fsync affects write-region.

65531:18b565312060

@node Saving
@section Saving Files

  @dfn{Saving} a buffer in Emacs means writing its contents back into the file
that was visited in the buffer.

@table @kbd
@item C-x C-s
Save the current buffer in its visited file on disk (@code{save-buffer}).
@item C-x s

version on disk does not match what Emacs last read or wrote, Emacs
notifies you of this fact, because it probably indicates a problem caused
by simultaneous editing and requires your immediate attention.
@xref{Interlocking,, Simultaneous Editing}.

@vindex require-final-newline
  If the value of the variable @code{require-final-newline} is
@code{t}, Emacs silently puts a newline at the end of any file that
doesn't already end in one, every time a file is saved or written.  If
the value is @code{visit}, Emacs adds a newline at the end of any file
that doesn't have one, just after it visits the file.  (This marks the
buffer as modified, and you can undo it.)  If the value is
@code{visit-save}, that means to add newlines both on visiting and on
saving.  If the value is @code{nil}, Emacs leaves the end of the file
unchanged; if it's neither @code{nil} nor @code{t}, Emacs asks you
whether to add a newline.  The default is @code{nil}.

@vindex mode-require-final-newline
  Many major modes are designed for specific kinds of files that are
always supposed to end in newlines.  These major modes set the
variable @code{require-final-newline} according to
@code{mode-require-final-newline}.  By setting the latter variable,
you can control how these modes handle final newlines.

@vindex write-region-inhibit-fsync
  When Emacs saves a file to disk, it issues an @code{fsync} call to the
operating system to ensure that your data has indeed reached the media.
This is important for safety if the system crashes or in case of power
outage.  However, it can be disruptive on laptops using power saving
because it forces the system to spin up the drive each time you save a
file; the variable @code{write-region-inhibit-fsync} disables this
synchronization.  This may result in data loss, use with care!

@menu
* Backup::              How Emacs saves the old version of your file.
* Interlocking::        How Emacs protects against simultaneous editing
                          of one file by two users.
* Shadowing: File Shadowing.  Copying files to "shadows" automatically.
* Time Stamps::         Emacs can update time stamps on saved files.
@end menu

@node Backup
@subsection Backup Files
@cindex backup file
@vindex make-backup-files
@vindex vc-make-backup-files

making backups.  One unfortunate similarity is that these operations
typically break hard links, disconnecting the file name you visited from
any alternate names for the same file.  This has nothing to do with
Emacs---the version control system does it.

@node Interlocking
@subsection Protection against Simultaneous Editing

@cindex file dates
@cindex simultaneous editing

leaving point unchanged before the contents and the mark after them.

@findex write-region
  @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
copies the contents of the region into the specified file.  @kbd{M-x
append-to-file} adds the text of the region to the end of the specified
file.  @xref{Accumulating Text}.

@findex delete-file
@cindex deletion (of files)
  @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
command in the shell.  If you are deleting many files in one directory, it

65532:1a6c78b455d7

@node Saving
@section Saving Files

  @dfn{Saving} a buffer in Emacs means writing its contents back into the file
that was visited in the buffer.

@menu
* Save Commands::       Commands for saving files.
* Backup::              How Emacs saves the old version of your file.
* Customize Save::      Customizing the saving of files.
* Interlocking::        How Emacs protects against simultaneous editing
                          of one file by two users.
* Shadowing: File Shadowing.  Copying files to "shadows" automatically.
* Time Stamps::         Emacs can update time stamps on saved files.
@end menu

@node Saving Commands
@subsection Commands for Saving Files

  These are the commands that relate to saving and writing files.

@table @kbd
@item C-x C-s
Save the current buffer in its visited file on disk (@code{save-buffer}).
@item C-x s

version on disk does not match what Emacs last read or wrote, Emacs
notifies you of this fact, because it probably indicates a problem caused
by simultaneous editing and requires your immediate attention.
@xref{Interlocking,, Simultaneous Editing}.

@node Backup
@subsection Backup Files
@cindex backup file
@vindex make-backup-files
@vindex vc-make-backup-files

making backups.  One unfortunate similarity is that these operations
typically break hard links, disconnecting the file name you visited from
any alternate names for the same file.  This has nothing to do with
Emacs---the version control system does it.

@node Customize Save
@subsection Customizing Saving of Files

@vindex require-final-newline
  If the value of the variable @code{require-final-newline} is
@code{t}, saving or writing a file silently puts a newline at the end
if there isn't already one there.  If the value is @code{visit}, Emacs
adds a newline at the end of any file that doesn't have one, just
after it visits the file.  (This marks the buffer as modified, and you
can undo it.)  If the value is @code{visit-save}, that means to add
newlines both on visiting and on saving.  If the value is @code{nil},
Emacs leaves the end of the file unchanged; if it's neither @code{nil}
nor @code{t}, Emacs asks you whether to add a newline.  The default is
@code{nil}.

@vindex mode-require-final-newline
  Many major modes are designed for specific kinds of files that are
always supposed to end in newlines.  These major modes set the
variable @code{require-final-newline} according to
@code{mode-require-final-newline}.  By setting the latter variable,
you can control how these modes handle final newlines.

@vindex write-region-inhibit-fsync
  When Emacs saves a file, it invokes the @code{fsync} system call to
force the data immediately out to disk.  This is important for safety
if the system crashes or in case of power outage.  However, it can be
disruptive on laptops using power saving, because it requires the disk
to spin up each time you save a file.  Setting
@code{write-region-inhibit-fsync} to a non-@code{nil} value disables
this synchronization.  Be careful---this means increased risk of data
loss.

@node Interlocking
@subsection Protection against Simultaneous Editing

@cindex file dates
@cindex simultaneous editing

leaving point unchanged before the contents and the mark after them.

@findex write-region
  @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
copies the contents of the region into the specified file.  @kbd{M-x
append-to-file} adds the text of the region to the end of the
specified file.  @xref{Accumulating Text}.  The variable
@code{write-region-inhibit-fsync} applies to these commands, as well
as saving files; see @ref{Customize Save}.

@findex delete-file
@cindex deletion (of files)
  @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
command in the shell.  If you are deleting many files in one directory, it