37.7 Read-Only Buffers

If a buffer is 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:

• A buffer visiting a write-protected file is normally read-only.

  Here, the purpose is to show 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 C-x C-q.

• Modes such as Dired and Rmail make buffers read-only when altering the contents with the usual editing commands is probably a mistake.

  The special commands of these modes bind buffer-read-only to nil (with let) or bind inhibit-read-only to t around the places where they change the text.

Variable: buffer-read-only

This buffer-local variable specifies whether the buffer is read-only. The buffer is read-only if this variable is non-nil.

Variable: inhibit-read-only

If this variable is non-nil, then read-only buffers and read-only characters may be modified. Read-only characters in a buffer are those that have non-nil read-only properties (either text properties or extent properties). See Extent Properties, for more information about text properties and extent properties.

If inhibit-read-only is t, all read-only character properties have no effect. If inhibit-read-only is a list, then read-only character properties have no effect if they are members of the list (comparison is done with eq).

Command: toggle-read-only &optional arg

This command changes whether the current buffer is read-only. Interactively, if a prefix arg arg is supplied, set the current buffer read only if and only if arg is positive.

This command is intended for interactive use only; don’t 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 buffer-read-only explicitly to the proper value, t or nil.

Function: barf-if-buffer-read-only &optional buffer start end

This function signals a buffer-read-only error if buffer is read-only. buffer defaults to the current buffer. See Interactive Call, for another way to signal an error if the current buffer is read-only.

If optional argument start is non-nil, all extents in the buffer which overlap that part of the buffer are checked to ensure none has a read-only property. (Extents that lie completely within the range, however, are not checked.) end defaults to the value of start.

If start and end are equal, the range checked is [start, end] (i.e. closed on both ends); otherwise, the range checked is (start, end) \(open on both ends), except that extents that lie completely within [start, end] are not checked. See extent-in-region-p for a fuller discussion.