[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to buffers.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to buffers.texi |
|
Date: |
Thu, 06 Sep 2007 04:09:44 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:09:44
Index: buffers.texi
===================================================================
RCS file: buffers.texi
diff -N buffers.texi
--- buffers.texi 7 Apr 2007 01:56:48 -0000 1.55
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,1165 +0,0 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
2001, 2002,
address@hidden 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
address@hidden See the file elisp.texi for copying conditions.
address@hidden ../info/buffers
address@hidden Buffers, Windows, Backups and Auto-Saving, Top
address@hidden Buffers
address@hidden 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.
-
address@hidden
-* 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.
address@hidden menu
-
address@hidden Buffer Basics
address@hidden node-name, next, previous, up
address@hidden Buffer Basics
-
address@hidden
- 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.
address@hidden 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
address@hidden 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
address@hidden Files} and @ref{Saving Buffers}. For functions and
-variables related to the display of buffers in windows, see
address@hidden and Windows}.
-
address@hidden bufferp object
-This function returns @code{t} if @var{object} is a buffer,
address@hidden otherwise.
address@hidden defun
-
address@hidden Current Buffer
address@hidden The Current Buffer
address@hidden selecting a buffer
address@hidden changing to another buffer
address@hidden 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
address@hidden 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
address@hidden (@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):
-
address@hidden
address@hidden
-(defun append-to-buffer (buffer start end)
- "Append to specified buffer the text of the region.
address@hidden"
- (interactive "BAppend to buffer: \nr")
- (let ((oldbuf (current-buffer)))
- (save-current-buffer
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
address@hidden group
address@hidden example
-
address@hidden
-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,
address@hidden 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
address@hidden 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:
-
address@hidden
address@hidden
-(let (buffer-read-only
- (obuf (current-buffer)))
- (set-buffer @dots{})
- @dots{}
- (set-buffer obuf))
address@hidden group
address@hidden example
-
address@hidden
-Using @code{save-current-buffer}, as shown here, handles quitting,
-errors, and @code{throw}, as well as ordinary evaluation.
-
address@hidden
address@hidden
-(let (buffer-read-only)
- (save-current-buffer
- (set-buffer @dots{})
- @dots{}))
address@hidden group
address@hidden example
-
address@hidden current-buffer
-This function returns the current buffer.
-
address@hidden
address@hidden
-(current-buffer)
- @result{} #<buffer buffers.texi>
address@hidden group
address@hidden example
address@hidden defun
-
address@hidden 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.
address@hidden defun
-
address@hidden save-current-buffer address@hidden
-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.
address@hidden defspec
-
address@hidden with-current-buffer buffer-or-name address@hidden
-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.
address@hidden defmac
-
address@hidden with-temp-buffer address@hidden
address@hidden 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
address@hidden(buffer-string)} as the last form.
-
-The current buffer is restored even in case of an abnormal exit via
address@hidden or error (@pxref{Nonlocal Exits}).
-
-See also @code{with-temp-file} in @ref{Definition of with-temp-file,,
-Writing to Files}.
address@hidden defmac
-
address@hidden Buffer Names
address@hidden Buffer Names
address@hidden 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.
-
address@hidden hidden buffers
address@hidden 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
address@hidden 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
address@hidden
-
address@hidden buffer-name &optional buffer
-This function returns the name of @var{buffer} as a string. If
address@hidden 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}.
-
address@hidden
address@hidden
-(buffer-name)
- @result{} "buffers.texi"
address@hidden group
-
address@hidden
-(setq foo (get-buffer "temp"))
- @result{} #<buffer temp>
address@hidden group
address@hidden
-(kill-buffer foo)
- @result{} nil
address@hidden group
address@hidden
-(buffer-name foo)
- @result{} nil
address@hidden group
address@hidden
-foo
- @result{} #<killed buffer>
address@hidden group
address@hidden example
address@hidden defun
-
address@hidden 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.
-
address@hidden Emacs 19 feature
-Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
-already in use. However, if @var{unique} is address@hidden, it modifies
address@hidden to make a name that is not in use. Interactively, you can
-make @var{unique} address@hidden 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.
address@hidden deffn
-
address@hidden 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:
-
address@hidden
address@hidden
-(setq b (get-buffer "lewis"))
- @result{} #<buffer lewis>
address@hidden group
address@hidden
-(get-buffer b)
- @result{} #<buffer lewis>
address@hidden group
address@hidden
-(get-buffer "Frazzle-nots")
- @result{} nil
address@hidden group
address@hidden example
-
-See also the function @code{get-buffer-create} in @ref{Creating Buffers}.
address@hidden defun
-
address@hidden Emacs 19 feature
address@hidden 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 address@hidden, 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
address@hidden<4>} exist,
-
address@hidden
-(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>"
address@hidden example
-
-See the related function @code{generate-new-buffer} in @ref{Creating
-Buffers}.
address@hidden defun
-
address@hidden Buffer File Name
address@hidden Buffer File Name
address@hidden visited file
address@hidden buffer file name
address@hidden 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.
address@hidden Files}.
-
address@hidden buffer-file-name &optional buffer
-This function returns the absolute file name of the file that
address@hidden is visiting. If @var{buffer} is not visiting any file,
address@hidden returns @code{nil}. If @var{buffer} is not
-supplied, it defaults to the current buffer.
-
address@hidden
address@hidden
-(buffer-file-name (other-buffer))
- @result{} "/usr/user/lewis/manual/files.texi"
address@hidden group
address@hidden example
address@hidden defun
-
address@hidden 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
address@hidden
-
address@hidden
address@hidden
-buffer-file-name
- @result{} "/usr/user/lewis/manual/buffers.texi"
address@hidden group
address@hidden 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.
address@hidden defvar
-
address@hidden 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
address@hidden @xref{Truenames}, and
address@hidden of abbreviate-file-name}.
address@hidden defvar
-
address@hidden 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}
address@hidden)}. This pair of numbers uniquely identifies the file among
-all files accessible on the system. See the function
address@hidden, 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.
address@hidden defvar
-
address@hidden 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
address@hidden, 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.
-
address@hidden
address@hidden
-(get-file-buffer "buffers.texi")
- @result{} #<buffer buffers.texi>
address@hidden group
address@hidden 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.
address@hidden defun
-
address@hidden 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 address@hidden, 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 address@hidden If it can not find a suitable buffer to
-return, @code{find-buffer-visiting} returns @code{nil}.
address@hidden defun
-
address@hidden 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
address@hidden, that prevents asking this question. If there already
-is a buffer visiting @var{filename}, and the user confirms or
address@hidden is address@hidden, 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 address@hidden, 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
address@hidden (@pxref{Modification Time}). If
address@hidden is @code{nil}, this function clears the recorded
-last file modification time, after which @code{visited-file-modtime}
-returns zero.
-
address@hidden 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.
address@hidden deffn
-
address@hidden 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.
address@hidden defvar
-
address@hidden Buffer Modification
address@hidden Buffer Modification
address@hidden buffer modification
address@hidden 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
address@hidden 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
address@hidden
-
address@hidden 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.
address@hidden defun
-
address@hidden set-buffer-modified-p flag
-This function marks the current buffer as modified if @var{flag} is
address@hidden, 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:
-
address@hidden
address@hidden
-(set-buffer-modified-p (buffer-modified-p))
address@hidden group
address@hidden example
address@hidden defun
-
address@hidden restore-buffer-modified-p flag
-Like @code{set-buffer-modified-p}, but does not force redisplay
-of mode lines.
address@hidden defun
-
address@hidden Command not-modified &optional arg
-This command marks the current buffer as unmodified, and not needing
-to be saved. If @var{arg} is address@hidden, 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.
address@hidden deffn
-
address@hidden 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
address@hidden is @code{nil} (or omitted), the current buffer is used.
-The counter can wrap around occasionally.
address@hidden defun
-
address@hidden 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.
address@hidden defun
-
address@hidden Modification Time
address@hidden node-name, next, previous, up
address@hidden Buffer Modification Time
address@hidden comparing file modification time
address@hidden 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.)
-
address@hidden 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
address@hidden 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.
address@hidden defun
-
address@hidden 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.
address@hidden defun
-
address@hidden Emacs 19 feature
address@hidden 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
address@hidden Note, however, that
address@hidden 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
address@hidden and @var{low} is 65535, that is,
address@hidden
address@hidden - 1.}
address@hidden ifnottex
address@hidden
address@hidden
address@hidden tex
address@hidden defun
-
address@hidden Emacs 19 feature
address@hidden 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
address@hidden(@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.
address@hidden defun
-
address@hidden 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.
-
address@hidden 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
address@hidden 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}.
address@hidden defun
-
address@hidden Read Only Buffers
address@hidden Read-Only Buffers
address@hidden read-only buffer
address@hidden 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:
-
address@hidden @bullet
address@hidden
-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}.
-
address@hidden
-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
address@hidden (with @code{let}) or bind @code{inhibit-read-only} to
address@hidden around the places where they themselves change the text.
address@hidden itemize
-
address@hidden buffer-read-only
-This buffer-local variable specifies whether the buffer is read-only.
-The buffer is read-only if this variable is address@hidden
address@hidden defvar
-
address@hidden inhibit-read-only
-If this variable is address@hidden, 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
address@hidden @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
address@hidden character properties have no effect if they are members
-of the list (comparison is done with @code{eq}).
address@hidden defvar
-
address@hidden 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 address@hidden, it should be a raw prefix argument.
address@hidden sets @code{buffer-read-only} to @code{t} if
-the numeric value of that prefix argument is positive and to
address@hidden otherwise. @xref{Prefix Command Arguments}.
address@hidden deffn
-
address@hidden 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.
address@hidden defun
-
address@hidden The Buffer List
address@hidden The Buffer List
address@hidden 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
address@hidden, 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
address@hidden'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.
-
address@hidden 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
address@hidden 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.
-
address@hidden
address@hidden
-(buffer-list)
- @result{} (#<buffer buffers.texi>
- #<buffer *Minibuf-1*> #<buffer buffer.c>
- #<buffer *Help*> #<buffer TAGS>)
address@hidden group
-
address@hidden
-;; @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")
address@hidden group
address@hidden example
address@hidden 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:
-
address@hidden
-(defun reorder-buffer-list (new-list)
- (while new-list
- (bury-buffer (car new-list))
- (setq new-list (cdr new-list))))
address@hidden 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
address@hidden frame parameter with @code{modify-frame-parameters}
-(@pxref{Parameter Access}).
-
address@hidden other-buffer &optional buffer visible-ok frame
-This function returns the first buffer in the buffer list other than
address@hidden 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
address@hidden 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 address@hidden @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}.
-
address@hidden 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 address@hidden, 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).
address@hidden defun
-
address@hidden 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
address@hidden to return. The argument can be either a buffer
-itself or the name of one.
-
address@hidden 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
address@hidden)} 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
address@hidden) 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
address@hidden @xref{Buffers and Windows}.
address@hidden deffn
-
address@hidden Creating Buffers
address@hidden Creating Buffers
address@hidden creating buffers
address@hidden buffers, creating
-
- This section describes the two primitives for creating buffers.
address@hidden 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
address@hidden (@pxref{Temporary Displays}) and
address@hidden (@pxref{Visiting Files}). Starting a
-subprocess can also create a buffer (@pxref{Processes}).
-
address@hidden 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.
-
address@hidden
address@hidden
-(get-buffer-create "foo")
- @result{} #<buffer foo>
address@hidden group
address@hidden 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}).
address@hidden defun
-
address@hidden 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.
-
address@hidden
address@hidden
-(generate-new-buffer "bar")
- @result{} #<buffer bar>
address@hidden group
address@hidden
-(generate-new-buffer "bar")
- @result{} #<buffer bar<2>>
address@hidden group
address@hidden
-(generate-new-buffer "bar")
- @result{} #<buffer bar<3>>
address@hidden group
address@hidden 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.
address@hidden Major Mode}.
-
-See the related function @code{generate-new-buffer-name} in @ref{Buffer
-Names}.
address@hidden defun
-
address@hidden Killing Buffers
address@hidden Killing Buffers
address@hidden killing buffers
address@hidden 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:
-
address@hidden
address@hidden
-(defun buffer-killed-p (buffer)
- "Return t if BUFFER is killed."
- (not (buffer-name buffer)))
address@hidden group
address@hidden example
-
address@hidden 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
address@hidden 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,
address@hidden 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
address@hidden @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
address@hidden was already dead.
-
address@hidden
-(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
address@hidden smallexample
address@hidden deffn
-
address@hidden 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},
address@hidden spares the buffer's life.
address@hidden defvar
-
address@hidden 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.
address@hidden This variable is a permanent local, so its local binding
-is not cleared by changing major modes.
address@hidden defvar
-
address@hidden buffer-offer-save
-This variable, if address@hidden in a particular buffer, tells
address@hidden 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.
address@hidden of save-some-buffers}. The variable
address@hidden automatically becomes buffer-local when set
-for any reason. @xref{Buffer-Local Variables}.
address@hidden defvar
-
address@hidden buffer-save-without-query
-This variable, if address@hidden in a particular buffer, tells
address@hidden 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.
address@hidden defvar
-
address@hidden buffer-live-p object
-This function returns @code{t} if @var{object} is a buffer which has
-not been killed, @code{nil} otherwise.
address@hidden defun
-
address@hidden Indirect Buffers
address@hidden Indirect Buffers
address@hidden indirect buffers
address@hidden 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.
-
address@hidden 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
address@hidden is the name of an existing buffer, an error is signaled.
-
-If @var{clone} is address@hidden, 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
address@hidden, the initial state is copied from the actual base
-buffer, not from @var{base-buffer}.
address@hidden deffn
-
address@hidden 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 address@hidden, that means to display the new
-buffer by calling @code{pop-to-buffer}. If @var{norecord} is
address@hidden, that means not to put the new buffer to the front of
-the buffer list.
address@hidden defun
-
address@hidden 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
address@hidden Otherwise, the value is another buffer, which is never an
-indirect buffer.
address@hidden defun
-
address@hidden Buffer Gap
address@hidden 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.
-
address@hidden gap-position
-This function returns the current gap position in the current buffer.
address@hidden defun
-
address@hidden gap-size
-This function returns the current gap size of the current buffer.
address@hidden defun
-
address@hidden
- arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c
address@hidden ignore
- [Emacs-diffs] Changes to buffers.texi,
Glenn Morris <=