changeset 84052:5655f2e3736d

Move here from ../../lispref

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/lispref/buffers.texi	Thu Sep 06 04:18:21 2007 +0000
@@ -0,0 +1,1165 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@c   2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/buffers
+@node Buffers, Windows, Backups and Auto-Saving, Top
+@chapter Buffers
+@cindex buffer
+
+  A @dfn{buffer} is a Lisp object containing text to be edited.  Buffers
+are used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files.  While several buffers may
+exist at one time, only one buffer is designated the @dfn{current
+buffer} at any time.  Most editing commands act on the contents of the
+current buffer.  Each buffer, including the current buffer, may or may
+not be displayed in any windows.
+
+@menu
+* Buffer Basics::       What is a buffer?
+* Current Buffer::      Designating a buffer as current
+                          so that primitives will access its contents.
+* Buffer Names::        Accessing and changing buffer names.
+* Buffer File Name::    The buffer file name indicates which file is visited.
+* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
+* Modification Time::   Determining whether the visited file was changed
+                         ``behind Emacs's back''.
+* Read Only Buffers::   Modifying text is not allowed in a read-only buffer.
+* The Buffer List::     How to look at all the existing buffers.
+* Creating Buffers::    Functions that create buffers.
+* Killing Buffers::     Buffers exist until explicitly killed.
+* Indirect Buffers::    An indirect buffer shares text with some other buffer.
+* Buffer Gap::          The gap in the buffer.
+@end menu
+
+@node Buffer Basics
+@comment  node-name,  next,  previous,  up
+@section Buffer Basics
+
+@ifnottex
+  A @dfn{buffer} is a Lisp object containing text to be edited.  Buffers
+are used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files.  Although several buffers
+normally exist, only one buffer is designated the @dfn{current
+buffer} at any time.  Most editing commands act on the contents of the
+current buffer.  Each buffer, including the current buffer, may or may
+not be displayed in any windows.
+@end ifnottex
+
+  Buffers in Emacs editing are objects that have distinct names and hold
+text that can be edited.  Buffers appear to Lisp programs as a special
+data type.  You can think of the contents of a buffer as a string that
+you can extend; insertions and deletions may occur in any part of the
+buffer.  @xref{Text}.
+
+  A Lisp buffer object contains numerous pieces of information.  Some of
+this information is directly accessible to the programmer through
+variables, while other information is accessible only through
+special-purpose functions.  For example, the visited file name is
+directly accessible through a variable, while the value of point is
+accessible only through a primitive function.
+
+  Buffer-specific information that is directly accessible is stored in
+@dfn{buffer-local} variable bindings, which are variable values that are
+effective only in a particular buffer.  This feature allows each buffer
+to override the values of certain variables.  Most major modes override
+variables such as @code{fill-column} or @code{comment-column} in this
+way.  For more information about buffer-local variables and functions
+related to them, see @ref{Buffer-Local Variables}.
+
+  For functions and variables related to visiting files in buffers, see
+@ref{Visiting Files} and @ref{Saving Buffers}.  For functions and
+variables related to the display of buffers in windows, see
+@ref{Buffers and Windows}.
+
+@defun bufferp object
+This function returns @code{t} if @var{object} is a buffer,
+@code{nil} otherwise.
+@end defun
+
+@node Current Buffer
+@section The Current Buffer
+@cindex selecting a buffer
+@cindex changing to another buffer
+@cindex current buffer
+
+  There are, in general, many buffers in an Emacs session.  At any time,
+one of them is designated as the @dfn{current buffer}.  This is the
+buffer in which most editing takes place, because most of the primitives
+for examining or changing text in a buffer operate implicitly on the
+current buffer (@pxref{Text}).  Normally the buffer that is displayed on
+the screen in the selected window is the current buffer, but this is not
+always so: a Lisp program can temporarily designate any buffer as
+current in order to operate on its contents, without changing what is
+displayed on the screen.
+
+  The way to designate a current buffer in a Lisp program is by calling
+@code{set-buffer}.  The specified buffer remains current until a new one
+is designated.
+
+  When an editing command returns to the editor command loop, the
+command loop designates the buffer displayed in the selected window as
+current, to prevent confusion: the buffer that the cursor is in when
+Emacs reads a command is the buffer that the command will apply to.
+(@xref{Command Loop}.)  Therefore, @code{set-buffer} is not the way to
+switch visibly to a different buffer so that the user can edit it.  For
+that, you must use the functions described in @ref{Displaying Buffers}.
+
+  @strong{Warning:} Lisp functions that change to a different current buffer
+should not depend on the command loop to set it back afterwards.
+Editing commands written in Emacs Lisp can be called from other programs
+as well as from the command loop; it is convenient for the caller if
+the subroutine does not change which buffer is current (unless, of
+course, that is the subroutine's purpose).  Therefore, you should
+normally use @code{set-buffer} within a @code{save-current-buffer} or
+@code{save-excursion} (@pxref{Excursions}) form that will restore the
+current buffer when your function is done.  Here is an example, the
+code for the command @code{append-to-buffer} (with the documentation
+string abridged):
+
+@example
+@group
+(defun append-to-buffer (buffer start end)
+  "Append to specified buffer the text of the region.
+@dots{}"
+  (interactive "BAppend to buffer: \nr")
+  (let ((oldbuf (current-buffer)))
+    (save-current-buffer
+      (set-buffer (get-buffer-create buffer))
+      (insert-buffer-substring oldbuf start end))))
+@end group
+@end example
+
+@noindent
+This function binds a local variable to record the current buffer, and
+then @code{save-current-buffer} arranges to make it current again.
+Next, @code{set-buffer} makes the specified buffer current.  Finally,
+@code{insert-buffer-substring} copies the string from the original
+current buffer to the specified (and now current) buffer.
+
+  If the buffer appended to happens to be displayed in some window,
+the next redisplay will show how its text has changed.  Otherwise, you
+will not see the change immediately on the screen.  The buffer becomes
+current temporarily during the execution of the command, but this does
+not cause it to be displayed.
+
+  If you make local bindings (with @code{let} or function arguments) for
+a variable that may also have buffer-local bindings, make sure that the
+same buffer is current at the beginning and at the end of the local
+binding's scope.  Otherwise you might bind it in one buffer and unbind
+it in another!  There are two ways to do this.  In simple cases, you may
+see that nothing ever changes the current buffer within the scope of the
+binding.  Otherwise, use @code{save-current-buffer} or
+@code{save-excursion} to make sure that the buffer current at the
+beginning is current again whenever the variable is unbound.
+
+  Do not rely on using @code{set-buffer} to change the current buffer
+back, because that won't do the job if a quit happens while the wrong
+buffer is current.  Here is what @emph{not} to do:
+
+@example
+@group
+(let (buffer-read-only
+      (obuf (current-buffer)))
+  (set-buffer @dots{})
+  @dots{}
+  (set-buffer obuf))
+@end group
+@end example
+
+@noindent
+Using @code{save-current-buffer}, as shown here, handles quitting,
+errors, and @code{throw}, as well as ordinary evaluation.
+
+@example
+@group
+(let (buffer-read-only)
+  (save-current-buffer
+    (set-buffer @dots{})
+    @dots{}))
+@end group
+@end example
+
+@defun current-buffer
+This function returns the current buffer.
+
+@example
+@group
+(current-buffer)
+     @result{} #<buffer buffers.texi>
+@end group
+@end example
+@end defun
+
+@defun set-buffer buffer-or-name
+This function makes @var{buffer-or-name} the current buffer.  This does
+not display the buffer in any window, so the user cannot necessarily see
+the buffer.  But Lisp programs will now operate on it.
+
+This function returns the buffer identified by @var{buffer-or-name}.
+An error is signaled if @var{buffer-or-name} does not identify an
+existing buffer.
+@end defun
+
+@defspec save-current-buffer body@dots{}
+The @code{save-current-buffer} special form saves the identity of the
+current buffer, evaluates the @var{body} forms, and finally restores
+that buffer as current.  The return value is the value of the last
+form in @var{body}.  The current buffer is restored even in case of an
+abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
+
+If the buffer that used to be current has been killed by the time of
+exit from @code{save-current-buffer}, then it is not made current again,
+of course.  Instead, whichever buffer was current just before exit
+remains current.
+@end defspec
+
+@defmac with-current-buffer buffer-or-name body@dots{}
+The @code{with-current-buffer} macro saves the identity of the current
+buffer, makes @var{buffer-or-name} current, evaluates the @var{body}
+forms, and finally restores the buffer.  The return value is the value
+of the last form in @var{body}.  The current buffer is restored even
+in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal
+Exits}).
+
+An error is signaled if @var{buffer-or-name} does not identify an
+existing buffer.
+@end defmac
+
+@defmac with-temp-buffer body@dots{}
+@anchor{Definition of with-temp-buffer}
+The @code{with-temp-buffer} macro evaluates the @var{body} forms
+with a temporary buffer as the current buffer.  It saves the identity of
+the current buffer, creates a temporary buffer and makes it current,
+evaluates the @var{body} forms, and finally restores the previous
+current buffer while killing the temporary buffer.  By default, undo
+information (@pxref{Undo}) is not recorded in the buffer created by
+this macro (but @var{body} can enable that, if needed).
+
+The return value is the value of the last form in @var{body}.  You can
+return the contents of the temporary buffer by using
+@code{(buffer-string)} as the last form.
+
+The current buffer is restored even in case of an abnormal exit via
+@code{throw} or error (@pxref{Nonlocal Exits}).
+
+See also @code{with-temp-file} in @ref{Definition of with-temp-file,,
+Writing to Files}.
+@end defmac
+
+@node Buffer Names
+@section Buffer Names
+@cindex buffer names
+
+  Each buffer has a unique name, which is a string.  Many of the
+functions that work on buffers accept either a buffer or a buffer name
+as an argument.  Any argument called @var{buffer-or-name} is of this
+sort, and an error is signaled if it is neither a string nor a buffer.
+Any argument called @var{buffer} must be an actual buffer
+object, not a name.
+
+@cindex hidden buffers
+@cindex buffers without undo information
+  Buffers that are ephemeral and generally uninteresting to the user
+have names starting with a space, so that the @code{list-buffers} and
+@code{buffer-menu} commands don't mention them (but if such a buffer
+visits a file, it @strong{is} mentioned).  A name starting with
+space also initially disables recording undo information; see
+@ref{Undo}.
+
+@defun buffer-name &optional buffer
+This function returns the name of @var{buffer} as a string.  If
+@var{buffer} is not supplied, it defaults to the current buffer.
+
+If @code{buffer-name} returns @code{nil}, it means that @var{buffer}
+has been killed.  @xref{Killing Buffers}.
+
+@example
+@group
+(buffer-name)
+     @result{} "buffers.texi"
+@end group
+
+@group
+(setq foo (get-buffer "temp"))
+     @result{} #<buffer temp>
+@end group
+@group
+(kill-buffer foo)
+     @result{} nil
+@end group
+@group
+(buffer-name foo)
+     @result{} nil
+@end group
+@group
+foo
+     @result{} #<killed buffer>
+@end group
+@end example
+@end defun
+
+@deffn Command rename-buffer newname &optional unique
+This function renames the current buffer to @var{newname}.  An error
+is signaled if @var{newname} is not a string.
+
+@c Emacs 19 feature
+Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
+already in use.  However, if @var{unique} is non-@code{nil}, it modifies
+@var{newname} to make a name that is not in use.  Interactively, you can
+make @var{unique} non-@code{nil} with a numeric prefix argument.
+(This is how the command @code{rename-uniquely} is implemented.)
+
+This function returns the name actually given to the buffer.
+@end deffn
+
+@defun get-buffer buffer-or-name
+This function returns the buffer specified by @var{buffer-or-name}.
+If @var{buffer-or-name} is a string and there is no buffer with that
+name, the value is @code{nil}.  If @var{buffer-or-name} is a buffer, it
+is returned as given; that is not very useful, so the argument is usually
+a name.  For example:
+
+@example
+@group
+(setq b (get-buffer "lewis"))
+     @result{} #<buffer lewis>
+@end group
+@group
+(get-buffer b)
+     @result{} #<buffer lewis>
+@end group
+@group
+(get-buffer "Frazzle-nots")
+     @result{} nil
+@end group
+@end example
+
+See also the function @code{get-buffer-create} in @ref{Creating Buffers}.
+@end defun
+
+@c Emacs 19 feature
+@defun generate-new-buffer-name starting-name &optional ignore
+This function returns a name that would be unique for a new buffer---but
+does not create the buffer.  It starts with @var{starting-name}, and
+produces a name not currently in use for any buffer by appending a
+number inside of @samp{<@dots{}>}.  It starts at 2 and keeps
+incrementing the number until it is not the name of an existing buffer.
+
+If the optional second argument @var{ignore} is non-@code{nil}, it
+should be a string, a potential buffer name.  It means to consider
+that potential buffer acceptable, if it is tried, even it is the name
+of an existing buffer (which would normally be rejected).  Thus, if
+buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and
+@samp{foo<4>} exist,
+
+@example
+(generate-new-buffer-name "foo")
+     @result{} "foo<5>"
+(generate-new-buffer-name "foo" "foo<3>")
+     @result{} "foo<3>"
+(generate-new-buffer-name "foo" "foo<6>")
+     @result{} "foo<5>"
+@end example
+
+See the related function @code{generate-new-buffer} in @ref{Creating
+Buffers}.
+@end defun
+
+@node Buffer File Name
+@section Buffer File Name
+@cindex visited file
+@cindex buffer file name
+@cindex file name of buffer
+
+  The @dfn{buffer file name} is the name of the file that is visited in
+that buffer.  When a buffer is not visiting a file, its buffer file name
+is @code{nil}.  Most of the time, the buffer name is the same as the
+nondirectory part of the buffer file name, but the buffer file name and
+the buffer name are distinct and can be set independently.
+@xref{Visiting Files}.
+
+@defun buffer-file-name &optional buffer
+This function returns the absolute file name of the file that
+@var{buffer} is visiting.  If @var{buffer} is not visiting any file,
+@code{buffer-file-name} returns @code{nil}.  If @var{buffer} is not
+supplied, it defaults to the current buffer.
+
+@example
+@group
+(buffer-file-name (other-buffer))
+     @result{} "/usr/user/lewis/manual/files.texi"
+@end group
+@end example
+@end defun
+
+@defvar buffer-file-name
+This buffer-local variable contains the name of the file being visited
+in the current buffer, or @code{nil} if it is not visiting a file.  It
+is a permanent local variable, unaffected by
+@code{kill-all-local-variables}.
+
+@example
+@group
+buffer-file-name
+     @result{} "/usr/user/lewis/manual/buffers.texi"
+@end group
+@end example
+
+It is risky to change this variable's value without doing various other
+things.  Normally it is better to use @code{set-visited-file-name} (see
+below); some of the things done there, such as changing the buffer name,
+are not strictly necessary, but others are essential to avoid confusing
+Emacs.
+@end defvar
+
+@defvar buffer-file-truename
+This buffer-local variable holds the abbreviated truename of the file
+visited in the current buffer, or @code{nil} if no file is visited.
+It is a permanent local, unaffected by
+@code{kill-all-local-variables}.  @xref{Truenames}, and
+@ref{Definition of abbreviate-file-name}.
+@end defvar
+
+@defvar buffer-file-number
+This buffer-local variable holds the file number and directory device
+number of the file visited in the current buffer, or @code{nil} if no
+file or a nonexistent file is visited.  It is a permanent local,
+unaffected by @code{kill-all-local-variables}.
+
+The value is normally a list of the form @code{(@var{filenum}
+@var{devnum})}.  This pair of numbers uniquely identifies the file among
+all files accessible on the system.  See the function
+@code{file-attributes}, in @ref{File Attributes}, for more information
+about them.
+
+If @code{buffer-file-name} is the name of a symbolic link, then both
+numbers refer to the recursive target.
+@end defvar
+
+@defun get-file-buffer filename
+This function returns the buffer visiting file @var{filename}.  If
+there is no such buffer, it returns @code{nil}.  The argument
+@var{filename}, which must be a string, is expanded (@pxref{File Name
+Expansion}), then compared against the visited file names of all live
+buffers.  Note that the buffer's @code{buffer-file-name} must match
+the expansion of @var{filename} exactly.  This function will not
+recognize other names for the same file.
+
+@example
+@group
+(get-file-buffer "buffers.texi")
+    @result{} #<buffer buffers.texi>
+@end group
+@end example
+
+In unusual circumstances, there can be more than one buffer visiting
+the same file name.  In such cases, this function returns the first
+such buffer in the buffer list.
+@end defun
+
+@defun find-buffer-visiting filename &optional predicate
+This is like @code{get-file-buffer}, except that it can return any
+buffer visiting the file @emph{possibly under a different name}.  That
+is, the buffer's @code{buffer-file-name} does not need to match the
+expansion of @var{filename} exactly, it only needs to refer to the
+same file.  If @var{predicate} is non-@code{nil}, it should be a
+function of one argument, a buffer visiting @var{filename}.  The
+buffer is only considered a suitable return value if @var{predicate}
+returns non-@code{nil}.  If it can not find a suitable buffer to
+return, @code{find-buffer-visiting} returns @code{nil}.
+@end defun
+
+@deffn Command set-visited-file-name filename &optional no-query along-with-file
+If @var{filename} is a non-empty string, this function changes the
+name of the file visited in the current buffer to @var{filename}.  (If the
+buffer had no visited file, this gives it one.)  The @emph{next time}
+the buffer is saved it will go in the newly-specified file.
+
+This command marks the buffer as modified, since it does not (as far
+as Emacs knows) match the contents of @var{filename}, even if it
+matched the former visited file.  It also renames the buffer to
+correspond to the new file name, unless the new name is already in
+use.
+
+If @var{filename} is @code{nil} or the empty string, that stands for
+``no visited file.''  In this case, @code{set-visited-file-name} marks
+the buffer as having no visited file, without changing the buffer's
+modified flag.
+
+Normally, this function asks the user for confirmation if there
+already is a buffer visiting @var{filename}.  If @var{no-query} is
+non-@code{nil}, that prevents asking this question.  If there already
+is a buffer visiting @var{filename}, and the user confirms or
+@var{query} is non-@code{nil}, this function makes the new buffer name
+unique by appending a number inside of @samp{<@dots{}>} to @var{filename}.
+
+If @var{along-with-file} is non-@code{nil}, that means to assume that
+the former visited file has been renamed to @var{filename}.  In this
+case, the command does not change the buffer's modified flag, nor the
+buffer's recorded last file modification time as reported by
+@code{visited-file-modtime} (@pxref{Modification Time}).  If
+@var{along-with-file} is @code{nil}, this function clears the recorded
+last file modification time, after which @code{visited-file-modtime}
+returns zero.
+
+@c Wordy to avoid overfull hbox.  --rjc 16mar92
+When the function @code{set-visited-file-name} is called interactively, it
+prompts for @var{filename} in the minibuffer.
+@end deffn
+
+@defvar list-buffers-directory
+This buffer-local variable specifies a string to display in a buffer
+listing where the visited file name would go, for buffers that don't
+have a visited file name.  Dired buffers use this variable.
+@end defvar
+
+@node Buffer Modification
+@section Buffer Modification
+@cindex buffer modification
+@cindex modification flag (of buffer)
+
+  Emacs keeps a flag called the @dfn{modified flag} for each buffer, to
+record whether you have changed the text of the buffer.  This flag is
+set to @code{t} whenever you alter the contents of the buffer, and
+cleared to @code{nil} when you save it.  Thus, the flag shows whether
+there are unsaved changes.  The flag value is normally shown in the mode
+line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving
+Buffers}) and auto-saving (@pxref{Auto-Saving}).
+
+  Some Lisp programs set the flag explicitly.  For example, the function
+@code{set-visited-file-name} sets the flag to @code{t}, because the text
+does not match the newly-visited file, even if it is unchanged from the
+file formerly visited.
+
+  The functions that modify the contents of buffers are described in
+@ref{Text}.
+
+@defun buffer-modified-p &optional buffer
+This function returns @code{t} if the buffer @var{buffer} has been modified
+since it was last read in from a file or saved, or @code{nil}
+otherwise.  If @var{buffer} is not supplied, the current buffer
+is tested.
+@end defun
+
+@defun set-buffer-modified-p flag
+This function marks the current buffer as modified if @var{flag} is
+non-@code{nil}, or as unmodified if the flag is @code{nil}.
+
+Another effect of calling this function is to cause unconditional
+redisplay of the mode line for the current buffer.  In fact, the
+function @code{force-mode-line-update} works by doing this:
+
+@example
+@group
+(set-buffer-modified-p (buffer-modified-p))
+@end group
+@end example
+@end defun
+
+@defun restore-buffer-modified-p flag
+Like @code{set-buffer-modified-p}, but does not force redisplay
+of mode lines.
+@end defun
+
+@deffn Command not-modified &optional arg
+This command marks the current buffer as unmodified, and not needing
+to be saved.  If @var{arg} is non-@code{nil}, it marks the buffer as
+modified, so that it will be saved at the next suitable occasion.
+Interactively, @var{arg} is the prefix argument.
+
+Don't use this function in programs, since it prints a message in the
+echo area; use @code{set-buffer-modified-p} (above) instead.
+@end deffn
+
+@defun buffer-modified-tick &optional buffer
+This function returns @var{buffer}'s modification-count.  This is a
+counter that increments every time the buffer is modified.  If
+@var{buffer} is @code{nil} (or omitted), the current buffer is used.
+The counter can wrap around occasionally.
+@end defun
+
+@defun buffer-chars-modified-tick &optional buffer
+This function returns @var{buffer}'s character-change modification-count.
+Changes to text properties leave this counter unchanged; however, each
+time text is inserted or removed from the buffer, the counter is reset
+to the value that would be returned @code{buffer-modified-tick}.
+By comparing the values returned by two @code{buffer-chars-modified-tick}
+calls, you can tell whether a character change occurred in that buffer
+in between the calls.  If @var{buffer} is @code{nil} (or omitted), the
+current buffer is used.
+@end defun
+
+@node Modification Time
+@comment  node-name,  next,  previous,  up
+@section Buffer Modification Time
+@cindex comparing file modification time
+@cindex modification time of buffer
+
+  Suppose that you visit a file and make changes in its buffer, and
+meanwhile the file itself is changed on disk.  At this point, saving the
+buffer would overwrite the changes in the file.  Occasionally this may
+be what you want, but usually it would lose valuable information.  Emacs
+therefore checks the file's modification time using the functions
+described below before saving the file.  (@xref{File Attributes},
+for how to examine a file's modification time.)
+
+@defun verify-visited-file-modtime buffer
+This function compares what @var{buffer} has recorded for the
+modification time of its visited file against the actual modification
+time of the file as recorded by the operating system.  The two should be
+the same unless some other process has written the file since Emacs
+visited or saved it.
+
+The function returns @code{t} if the last actual modification time and
+Emacs's recorded modification time are the same, @code{nil} otherwise.
+It also returns @code{t} if the buffer has no recorded last
+modification time, that is if @code{visited-file-modtime} would return
+zero.
+
+It always returns @code{t} for buffers that are not visiting a file,
+even if @code{visited-file-modtime} returns a non-zero value.  For
+instance, it always returns @code{t} for dired buffers.  It returns
+@code{t} for buffers that are visiting a file that does not exist and
+never existed, but @code{nil} for file-visiting buffers whose file has
+been deleted.
+@end defun
+
+@defun clear-visited-file-modtime
+This function clears out the record of the last modification time of
+the file being visited by the current buffer.  As a result, the next
+attempt to save this buffer will not complain of a discrepancy in
+file modification times.
+
+This function is called in @code{set-visited-file-name} and other
+exceptional places where the usual test to avoid overwriting a changed
+file should not be done.
+@end defun
+
+@c Emacs 19 feature
+@defun visited-file-modtime
+This function returns the current buffer's recorded last file
+modification time, as a list of the form @code{(@var{high} @var{low})}.
+(This is the same format that @code{file-attributes} uses to return
+time values; see @ref{File Attributes}.)
+
+If the buffer has no recorded last modification time, this function
+returns zero.  This case occurs, for instance, if the buffer is not
+visiting a file or if the time has been explicitly cleared by
+@code{clear-visited-file-modtime}.  Note, however, that
+@code{visited-file-modtime} returns a list for some non-file buffers
+too.  For instance, in a Dired buffer listing a directory, it returns
+the last modification time of that directory, as recorded by Dired.
+
+For a new buffer visiting a not yet existing file, @var{high} is
+@minus{}1 and @var{low} is 65535, that is,
+@ifnottex
+@w{2**16 - 1.}
+@end ifnottex
+@tex
+@math{2^{16}-1}.
+@end tex
+@end defun
+
+@c Emacs 19 feature
+@defun set-visited-file-modtime &optional time
+This function updates the buffer's record of the last modification time
+of the visited file, to the value specified by @var{time} if @var{time}
+is not @code{nil}, and otherwise to the last modification time of the
+visited file.
+
+If @var{time} is neither @code{nil} nor zero, it should have the form
+@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in
+either case containing two integers, each of which holds 16 bits of the
+time.
+
+This function is useful if the buffer was not read from the file
+normally, or if the file itself has been changed for some known benign
+reason.
+@end defun
+
+@defun ask-user-about-supersession-threat filename
+This function is used to ask a user how to proceed after an attempt to
+modify an buffer visiting file @var{filename} when the file is newer
+than the buffer text.  Emacs detects this because the modification
+time of the file on disk is newer than the last save-time of the
+buffer.  This means some other program has probably altered the file.
+
+@kindex file-supersession
+Depending on the user's answer, the function may return normally, in
+which case the modification of the buffer proceeds, or it may signal a
+@code{file-supersession} error with data @code{(@var{filename})}, in which
+case the proposed buffer modification is not allowed.
+
+This function is called automatically by Emacs on the proper
+occasions.  It exists so you can customize Emacs by redefining it.
+See the file @file{userlock.el} for the standard definition.
+
+See also the file locking mechanism in @ref{File Locks}.
+@end defun
+
+@node Read Only Buffers
+@section Read-Only Buffers
+@cindex read-only buffer
+@cindex buffer, read-only
+
+  If a buffer is @dfn{read-only}, then you cannot change its contents,
+although you may change your view of the contents by scrolling and
+narrowing.
+
+  Read-only buffers are used in two kinds of situations:
+
+@itemize @bullet
+@item
+A buffer visiting a write-protected file is normally read-only.
+
+Here, the purpose is to inform the user that editing the buffer with the
+aim of saving it in the file may be futile or undesirable.  The user who
+wants to change the buffer text despite this can do so after clearing
+the read-only flag with @kbd{C-x C-q}.
+
+@item
+Modes such as Dired and Rmail make buffers read-only when altering the
+contents with the usual editing commands would probably be a mistake.
+
+The special commands of these modes bind @code{buffer-read-only} to
+@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to
+@code{t} around the places where they themselves change the text.
+@end itemize
+
+@defvar buffer-read-only
+This buffer-local variable specifies whether the buffer is read-only.
+The buffer is read-only if this variable is non-@code{nil}.
+@end defvar
+
+@defvar inhibit-read-only
+If this variable is non-@code{nil}, then read-only buffers and,
+depending on the actual value, some or all read-only characters may be
+modified.  Read-only characters in a buffer are those that have
+non-@code{nil} @code{read-only} properties (either text properties or
+overlay properties).  @xref{Special Properties}, for more information
+about text properties.  @xref{Overlays}, for more information about
+overlays and their properties.
+
+If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
+properties have no effect.  If @code{inhibit-read-only} is a list, then
+@code{read-only} character properties have no effect if they are members
+of the list (comparison is done with @code{eq}).
+@end defvar
+
+@deffn Command toggle-read-only &optional arg
+This command toggles whether the current buffer is read-only.  It is
+intended for interactive use; do not use it in programs.  At any given
+point in a program, you should know whether you want the read-only flag
+on or off; so you can set @code{buffer-read-only} explicitly to the
+proper value, @code{t} or @code{nil}.
+
+If @var{arg} is non-@code{nil}, it should be a raw prefix argument.
+@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if
+the numeric value of that prefix argument is positive and to
+@code{nil} otherwise.  @xref{Prefix Command Arguments}.
+@end deffn
+
+@defun barf-if-buffer-read-only
+This function signals a @code{buffer-read-only} error if the current
+buffer is read-only.  @xref{Using Interactive}, for another way to
+signal an error if the current buffer is read-only.
+@end defun
+
+@node The Buffer List
+@section The Buffer List
+@cindex buffer list
+
+  The @dfn{buffer list} is a list of all live buffers.  The order of
+the buffers in the list is based primarily on how recently each buffer
+has been displayed in a window.  Several functions, notably
+@code{other-buffer}, use this ordering.  A buffer list displayed for
+the user also follows this order.
+
+  Creating a buffer adds it to the end of the buffer list, and killing
+a buffer removes it.  Buffers move to the front of the list when they
+are selected for display in a window (@pxref{Displaying Buffers}), and
+to the end when they are buried (see @code{bury-buffer}, below).
+There are no functions available to the Lisp programmer which directly
+manipulate the buffer list.
+  
+  In addition to the fundamental Emacs buffer list, each frame has its
+own version of the buffer list, in which the buffers that have been
+selected in that frame come first, starting with the buffers most
+recently selected @emph{in that frame}.  (This order is recorded in
+@var{frame}'s @code{buffer-list} frame parameter; see @ref{Buffer
+Parameters}.)  The buffers that were never selected in @var{frame} come
+afterward, ordered according to the fundamental Emacs buffer list.
+
+@defun buffer-list &optional frame
+This function returns the buffer list, including all buffers, even those
+whose names begin with a space.  The elements are actual buffers, not
+their names.
+
+If @var{frame} is a frame, this returns @var{frame}'s buffer list.  If
+@var{frame} is @code{nil}, the fundamental Emacs buffer list is used:
+all the buffers appear in order of most recent selection, regardless of
+which frames they were selected in.
+
+@example
+@group
+(buffer-list)
+     @result{} (#<buffer buffers.texi>
+         #<buffer  *Minibuf-1*> #<buffer buffer.c>
+         #<buffer *Help*> #<buffer TAGS>)
+@end group
+
+@group
+;; @r{Note that the name of the minibuffer}
+;;   @r{begins with a space!}
+(mapcar (function buffer-name) (buffer-list))
+    @result{} ("buffers.texi" " *Minibuf-1*"
+        "buffer.c" "*Help*" "TAGS")
+@end group
+@end example
+@end defun
+
+  The list that @code{buffer-list} returns is constructed specifically
+by @code{buffer-list}; it is not an internal Emacs data structure, and
+modifying it has no effect on the order of buffers.  If you want to
+change the order of buffers in the frame-independent buffer list, here
+is an easy way:
+
+@example
+(defun reorder-buffer-list (new-list)
+  (while new-list
+    (bury-buffer (car new-list))
+    (setq new-list (cdr new-list))))
+@end example
+
+  With this method, you can specify any order for the list, but there is
+no danger of losing a buffer or adding something that is not a valid
+live buffer.
+
+  To change the order or value of a frame's buffer list, set the frame's
+@code{buffer-list} frame parameter with @code{modify-frame-parameters}
+(@pxref{Parameter Access}).
+
+@defun other-buffer &optional buffer visible-ok frame
+This function returns the first buffer in the buffer list other than
+@var{buffer}.  Usually this is the buffer selected most recently (in
+frame @var{frame} or else the currently selected frame, @pxref{Input
+Focus}), aside from @var{buffer}.  Buffers whose names start with a
+space are not considered at all.
+
+If @var{buffer} is not supplied (or if it is not a buffer), then
+@code{other-buffer} returns the first buffer in the selected frame's
+buffer list that is not now visible in any window in a visible frame.
+
+If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter,
+then @code{other-buffer} uses that predicate to decide which buffers to
+consider.  It calls the predicate once for each buffer, and if the value
+is @code{nil}, that buffer is ignored.  @xref{Buffer Parameters}.
+
+@c Emacs 19 feature
+If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning
+a buffer visible in any window on any visible frame, except as a last
+resort.   If @var{visible-ok} is non-@code{nil}, then it does not matter
+whether a buffer is displayed somewhere or not.
+
+If no suitable buffer exists, the buffer @samp{*scratch*} is returned
+(and created, if necessary).
+@end defun
+
+@deffn Command bury-buffer &optional buffer-or-name
+This function puts @var{buffer-or-name} at the end of the buffer list,
+without changing the order of any of the other buffers on the list.
+This buffer therefore becomes the least desirable candidate for
+@code{other-buffer} to return.  The argument can be either a buffer
+itself or the name of one.
+
+@code{bury-buffer} operates on each frame's @code{buffer-list} parameter
+as well as the frame-independent Emacs buffer list; therefore, the
+buffer that you bury will come last in the value of @code{(buffer-list
+@var{frame})} and in the value of @code{(buffer-list nil)}.
+
+If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
+current buffer.  In addition, if the buffer is displayed in the selected
+window, this switches to some other buffer (obtained using
+@code{other-buffer}) in the selected window.  But if the buffer is
+displayed in some other window, it remains displayed there.
+
+To replace a buffer in all the windows that display it, use
+@code{replace-buffer-in-windows}.  @xref{Buffers and Windows}.
+@end deffn
+
+@node Creating Buffers
+@section Creating Buffers
+@cindex creating buffers
+@cindex buffers, creating
+
+  This section describes the two primitives for creating buffers.
+@code{get-buffer-create} creates a buffer if it finds no existing buffer
+with the specified name; @code{generate-new-buffer} always creates a new
+buffer and gives it a unique name.
+
+  Other functions you can use to create buffers include
+@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and
+@code{create-file-buffer} (@pxref{Visiting Files}).  Starting a
+subprocess can also create a buffer (@pxref{Processes}).
+
+@defun get-buffer-create name
+This function returns a buffer named @var{name}.  It returns a live
+buffer with that name, if one exists; otherwise, it creates a new
+buffer.  The buffer does not become the current buffer---this function
+does not change which buffer is current.
+
+If @var{name} is a buffer instead of a string, it is returned, even if
+it is dead.  An error is signaled if @var{name} is neither a string
+nor a buffer.
+
+@example
+@group
+(get-buffer-create "foo")
+     @result{} #<buffer foo>
+@end group
+@end example
+
+The major mode for a newly created buffer is set to Fundamental mode.
+(The variable @code{default-major-mode} is handled at a higher level;
+see @ref{Auto Major Mode}.)  If the name begins with a space, the
+buffer initially disables undo information recording (@pxref{Undo}).
+@end defun
+
+@defun generate-new-buffer name
+This function returns a newly created, empty buffer, but does not make
+it current.  If there is no buffer named @var{name}, then that is the
+name of the new buffer.  If that name is in use, this function adds
+suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an
+integer.  It tries successive integers starting with 2 until it finds an
+available name.
+
+An error is signaled if @var{name} is not a string.
+
+@example
+@group
+(generate-new-buffer "bar")
+     @result{} #<buffer bar>
+@end group
+@group
+(generate-new-buffer "bar")
+     @result{} #<buffer bar<2>>
+@end group
+@group
+(generate-new-buffer "bar")
+     @result{} #<buffer bar<3>>
+@end group
+@end example
+
+The major mode for the new buffer is set to Fundamental mode.  The
+variable @code{default-major-mode} is handled at a higher level.
+@xref{Auto Major Mode}.
+
+See the related function @code{generate-new-buffer-name} in @ref{Buffer
+Names}.
+@end defun
+
+@node Killing Buffers
+@section Killing Buffers
+@cindex killing buffers
+@cindex buffers, killing
+
+  @dfn{Killing a buffer} makes its name unknown to Emacs and makes the
+memory space it occupied available for other use.
+
+  The buffer object for the buffer that has been killed remains in
+existence as long as anything refers to it, but it is specially marked
+so that you cannot make it current or display it.  Killed buffers retain
+their identity, however; if you kill two distinct buffers, they remain
+distinct according to @code{eq} although both are dead.
+
+  If you kill a buffer that is current or displayed in a window, Emacs
+automatically selects or displays some other buffer instead.  This means
+that killing a buffer can in general change the current buffer.
+Therefore, when you kill a buffer, you should also take the precautions
+associated with changing the current buffer (unless you happen to know
+that the buffer being killed isn't current).  @xref{Current Buffer}.
+
+  If you kill a buffer that is the base buffer of one or more indirect
+buffers, the indirect buffers are automatically killed as well.
+
+  The @code{buffer-name} of a killed buffer is @code{nil}.  You can use
+this feature to test whether a buffer has been killed:
+
+@example
+@group
+(defun buffer-killed-p (buffer)
+  "Return t if BUFFER is killed."
+  (not (buffer-name buffer)))
+@end group
+@end example
+
+@deffn Command kill-buffer buffer-or-name
+This function kills the buffer @var{buffer-or-name}, freeing all its
+memory for other uses or to be returned to the operating system.  If
+@var{buffer-or-name} is @code{nil}, it kills the current buffer.
+
+Any processes that have this buffer as the @code{process-buffer} are
+sent the @code{SIGHUP} signal, which normally causes them to terminate.
+(The basic meaning of @code{SIGHUP} is that a dialup line has been
+disconnected.)  @xref{Signals to Processes}.
+
+If the buffer is visiting a file and contains unsaved changes,
+@code{kill-buffer} asks the user to confirm before the buffer is killed.
+It does this even if not called interactively.  To prevent the request
+for confirmation, clear the modified flag before calling
+@code{kill-buffer}.  @xref{Buffer Modification}.
+
+Killing a buffer that is already dead has no effect.
+
+This function returns @code{t} if it actually killed the buffer.  It
+returns @code{nil} if the user refuses to confirm or if
+@var{buffer-or-name} was already dead.
+
+@smallexample
+(kill-buffer "foo.unchanged")
+     @result{} t
+(kill-buffer "foo.changed")
+
+---------- Buffer: Minibuffer ----------
+Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
+---------- Buffer: Minibuffer ----------
+
+     @result{} t
+@end smallexample
+@end deffn
+
+@defvar kill-buffer-query-functions
+After confirming unsaved changes, @code{kill-buffer} calls the functions
+in the list @code{kill-buffer-query-functions}, in order of appearance,
+with no arguments.  The buffer being killed is the current buffer when
+they are called.  The idea of this feature is that these functions will
+ask for confirmation from the user.  If any of them returns @code{nil},
+@code{kill-buffer} spares the buffer's life.
+@end defvar
+
+@defvar kill-buffer-hook
+This is a normal hook run by @code{kill-buffer} after asking all the
+questions it is going to ask, just before actually killing the buffer.
+The buffer to be killed is current when the hook functions run.
+@xref{Hooks}.  This variable is a permanent local, so its local binding
+is not cleared by changing major modes.
+@end defvar
+
+@defvar buffer-offer-save
+This variable, if non-@code{nil} in a particular buffer, tells
+@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the
+second optional argument to that function is @code{t}) to offer to
+save that buffer, just as they offer to save file-visiting buffers.
+@xref{Definition of save-some-buffers}.  The variable
+@code{buffer-offer-save} automatically becomes buffer-local when set
+for any reason.  @xref{Buffer-Local Variables}.
+@end defvar
+
+@defvar buffer-save-without-query
+This variable, if non-@code{nil} in a particular buffer, tells
+@code{save-buffers-kill-emacs} and @code{save-some-buffers} to save
+this buffer (if it's modified) without asking the user.  The variable
+automatically becomes buffer-local when set for any reason.
+@end defvar
+
+@defun buffer-live-p object
+This function returns @code{t} if @var{object} is a buffer which has
+not been killed, @code{nil} otherwise.
+@end defun
+
+@node Indirect Buffers
+@section Indirect Buffers
+@cindex indirect buffers
+@cindex base buffer
+
+  An @dfn{indirect buffer} shares the text of some other buffer, which
+is called the @dfn{base buffer} of the indirect buffer.  In some ways it
+is the analogue, for buffers, of a symbolic link among files.  The base
+buffer may not itself be an indirect buffer.
+
+  The text of the indirect buffer is always identical to the text of its
+base buffer; changes made by editing either one are visible immediately
+in the other.  This includes the text properties as well as the characters
+themselves.
+
+  In all other respects, the indirect buffer and its base buffer are
+completely separate.  They have different names, independent values of
+point, independent narrowing, independent markers and overlays (though
+inserting or deleting text in either buffer relocates the markers and
+overlays for both), independent major modes, and independent
+buffer-local variable bindings.
+
+  An indirect buffer cannot visit a file, but its base buffer can.  If
+you try to save the indirect buffer, that actually saves the base
+buffer.
+
+  Killing an indirect buffer has no effect on its base buffer.  Killing
+the base buffer effectively kills the indirect buffer in that it cannot
+ever again be the current buffer.
+
+@deffn Command make-indirect-buffer base-buffer name &optional clone
+This creates and returns an indirect buffer named @var{name} whose
+base buffer is @var{base-buffer}.  The argument @var{base-buffer} may
+be a live buffer or the name (a string) of an existing buffer.  If
+@var{name} is the name of an existing buffer, an error is signaled.
+
+If @var{clone} is non-@code{nil}, then the indirect buffer originally
+shares the ``state'' of @var{base-buffer} such as major mode, minor
+modes, buffer local variables and so on.  If @var{clone} is omitted
+or @code{nil} the indirect buffer's state is set to the default state
+for new buffers.
+
+If @var{base-buffer} is an indirect buffer, its base buffer is used as
+the base for the new buffer.  If, in addition, @var{clone} is
+non-@code{nil}, the initial state is copied from the actual base
+buffer, not from @var{base-buffer}.
+@end deffn
+
+@defun clone-indirect-buffer newname display-flag &optional norecord
+This function creates and returns a new indirect buffer that shares
+the current buffer's base buffer and copies the rest of the current
+buffer's attributes.  (If the current buffer is not indirect, it is
+used as the base buffer.)
+
+If @var{display-flag} is non-@code{nil}, that means to display the new
+buffer by calling @code{pop-to-buffer}.  If @var{norecord} is
+non-@code{nil}, that means not to put the new buffer to the front of
+the buffer list.
+@end defun
+
+@defun buffer-base-buffer &optional buffer
+This function returns the base buffer of @var{buffer}, which defaults
+to the current buffer.  If @var{buffer} is not indirect, the value is
+@code{nil}.  Otherwise, the value is another buffer, which is never an
+indirect buffer.
+@end defun
+
+@node Buffer Gap
+@section The Buffer Gap
+
+  Emacs buffers are implemented using an invisible @dfn{gap} to make
+insertion and deletion faster.  Insertion works by filling in part of
+the gap, and deletion adds to the gap.  Of course, this means that the
+gap must first be moved to the locus of the insertion or deletion.
+Emacs moves the gap only when you try to insert or delete.  This is why
+your first editing command in one part of a large buffer, after
+previously editing in another far-away part, sometimes involves a
+noticeable delay.
+
+  This mechanism works invisibly, and Lisp code should never be affected
+by the gap's current location, but these functions are available for
+getting information about the gap status.
+
+@defun gap-position
+This function returns the current gap position in the current buffer.
+@end defun
+
+@defun gap-size
+This function returns the current gap size of the current buffer.
+@end defun
+
+@ignore
+   arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c
+@end ignore