[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] trunk r115880: More doc updates.
|
From: |
Chong Yidong |
|
Subject: |
[Emacs-diffs] trunk r115880: More doc updates. |
|
Date: |
Sun, 05 Jan 2014 23:36:19 +0000 |
|
User-agent: |
Bazaar (2.6b2) |
------------------------------------------------------------
revno: 115880
revision-id: address@hidden
parent: address@hidden
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Mon 2014-01-06 07:36:13 +0800
message:
More doc updates.
* backups.texi (Making Backups): Document backup-buffer change.
* commands.texi (Defining Commands): Document the interactive-form
property more carefully. Document interactive-only.
* compile.texi (Compiler Errors): Copyedits. Note that the
details for byte-compile-warnings are in its docstring.
* customize.texi (Variable Definitions): Likewise.
* files.texi (Visiting Files): Copyedits.
(Testing Accessibility): Mention ACLs. Move file-modes here from
File Attributes.
(Truenames): Move file-equal-p here from Kinds of Files.
(File Attributes): Move file-newer-than-file-p here from Testing
Accessibility.
(Extended Attributes): New node. Add file-extended-attributes.
(Changing Files): Document set-file-extended-attributes.
* minibuf.texi (Minibuffer Contents): Remove obsolete function
minibuffer-completion-contents.
* variables.texi (Defining Variables): Note that defvar acts
always on the dynamic value.
modified:
doc/lispref/ChangeLog changelog-20091113204419-o5vbwnq5f7feedwu-6155
doc/lispref/backups.texi
backups.texi-20091113204419-o5vbwnq5f7feedwu-6162
doc/lispref/commands.texi
commands.texi-20091113204419-o5vbwnq5f7feedwu-6165
doc/lispref/compile.texi
compile.texi-20091113204419-o5vbwnq5f7feedwu-6166
doc/lispref/customize.texi
customize.texi-20091113204419-o5vbwnq5f7feedwu-6170
doc/lispref/elisp.texi elisp.texi-20091113204419-o5vbwnq5f7feedwu-6176
doc/lispref/files.texi files.texi-20091113204419-o5vbwnq5f7feedwu-6179
doc/lispref/minibuf.texi
minibuf.texi-20091113204419-o5vbwnq5f7feedwu-6199
doc/lispref/variables.texi
variables.texi-20091113204419-o5vbwnq5f7feedwu-6221
etc/NEWS news-20100311060928-aoit31wvzf25yr1z-1
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2014-01-05 01:33:33 +0000
+++ b/doc/lispref/ChangeLog 2014-01-05 23:36:13 +0000
@@ -1,3 +1,30 @@
+2014-01-05 Chong Yidong <address@hidden>
+
+ * backups.texi (Making Backups): Document backup-buffer change.
+
+ * files.texi (Visiting Files): Copyedits.
+ (Testing Accessibility): Mention ACLs. Move file-modes here from
+ File Attributes.
+ (Truenames): Move file-equal-p here from Kinds of Files.
+ (File Attributes): Move file-newer-than-file-p here from Testing
+ Accessibility.
+ (Extended Attributes): New node. Add file-extended-attributes.
+ (Changing Files): Document set-file-extended-attributes.
+
+ * commands.texi (Defining Commands): Document the interactive-form
+ property more carefully. Document interactive-only.
+
+ * compile.texi (Compiler Errors): Copyedits. Note that the
+ details for byte-compile-warnings are in its docstring.
+
+ * minibuf.texi (Minibuffer Contents): Remove obsolete function
+ minibuffer-completion-contents.
+
+ * variables.texi (Defining Variables): Note that defvar acts
+ always on the dynamic value.
+
+ * customize.texi (Variable Definitions): Likewise.
+
2014-01-05 Paul Eggert <address@hidden>
Document vconcat and the empty vector (Bug#16246).
=== modified file 'doc/lispref/backups.texi'
--- a/doc/lispref/backups.texi 2014-01-01 07:43:34 +0000
+++ b/doc/lispref/backups.texi 2014-01-05 23:36:13 +0000
@@ -57,13 +57,15 @@
saving the buffer the first time.
If a backup was made by renaming, the return value is a cons cell of
-the form (@var{modes} @var{context} @var{backupname}), where
+the form (@var{modes} @var{extra-alist} @var{backupname}), where
@var{modes} are the mode bits of the original file, as returned by
address@hidden (@pxref{File Attributes,, Other Information about
-Files}), @var{context} is a list describing the original file's
-SELinux context (@pxref{File Attributes}), and @var{backupname} is the
-name of the backup. In all other cases, that is, if a backup was made
-by copying or if no backup was made, this function returns @code{nil}.
address@hidden (@pxref{Testing Accessibility}), @var{extra-alist}
+is an alist describing the original file's extended attributes, as
+returned by @code{file-extended-attributes} (@pxref{Extended
+Attributes}), and @var{backupname} is the name of the backup.
+
+In all other cases (i.e., if a backup was made by copying or if no
+backup was made), this function returns @code{nil}.
@end defun
@defvar buffer-backed-up
=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2014-01-01 07:43:34 +0000
+++ b/doc/lispref/commands.texi 2014-01-05 23:36:13 +0000
@@ -108,13 +108,26 @@
The special form @code{interactive} turns a Lisp function into a
command. The @code{interactive} form must be located at top-level in
-the function body (usually as the first form in the body), or in the
address@hidden property of the function symbol. When the
address@hidden form is located in the function body, it does
-nothing when actually executed. Its presence serves as a flag, which
-tells the Emacs command loop that the function can be called
-interactively. The argument of the @code{interactive} form controls
-the reading of arguments for an interactive call.
+the function body, usually as the first form in the body; this applies
+to both lambda expressions (@pxref{Lambda Expressions}) and
address@hidden forms (@pxref{Defining Functions}). This form does
+nothing during the actual execution of the function; its presence
+serves as a flag, telling the Emacs command loop that the function can
+be called interactively. The argument of the @code{interactive} form
+specifies how the arguments for an interactive call should be read.
+
address@hidden @code{interactive-form} property
+ Alternatively, an @code{interactive} form may be specified in a
+function symbol's @code{interactive-form} property. A address@hidden
+value for this property takes precedence over any @code{interactive}
+form in the function body itself. This feature is seldom used.
+
address@hidden @code{interactive-only} property
+ Sometimes, a named command is only intended to be called
+interactively, never directly from Lisp. In that case, give it a
address@hidden @code{interactive-only} property. In that case, the
+byte compiler will print a warning message if the command is called
+from Lisp.
@menu
* Using Interactive:: General rules for @code{interactive}.
=== modified file 'doc/lispref/compile.texi'
--- a/doc/lispref/compile.texi 2014-01-03 05:49:06 +0000
+++ b/doc/lispref/compile.texi 2014-01-05 23:36:13 +0000
@@ -430,29 +430,35 @@
@section Compiler Errors
@cindex compiler errors
- Byte compilation outputs all errors and warnings into the buffer
address@hidden The messages include file names and line
-numbers that identify the location of the problem. The usual Emacs
-commands for operating on compiler diagnostics work properly on these
+ Error and warning messages from byte compilation are printed in a
+buffer named @file{*Compile-Log*}. These messages include file names
+and line numbers identifying the location of the problem. The usual
+Emacs commands for operating on compiler output can be used on these
messages.
When an error is due to invalid syntax in the program, the byte
compiler might get confused about the errors' exact location. One way
-to investigate is to switch to the buffer @address@hidden *Compiler Input*}}.
-(This buffer name starts with a space, so it does not show up in
address@hidden list-buffers}.) This buffer contains the program being
+to investigate is to switch to the buffer @address@hidden *Compiler
+Input*}}. (This buffer name starts with a space, so it does not show
+up in the Buffer Menu.) This buffer contains the program being
compiled, and point shows how far the byte compiler was able to read;
the cause of the error might be nearby. @xref{Syntax Errors}, for
some tips for locating syntax errors.
- When the byte compiler warns about functions that were used but not
-defined, it always reports the line number for the end of the file,
-not the locations where the missing functions were called. To find
-the latter, you must search for the function names.
-
- You can suppress the compiler warning for calling an undefined
-function @var{func} by conditionalizing the function call on an
address@hidden test, like this:
+ A common type of warning issued by the byte compiler is for
+functions and variables that were used but not defined. Such warnings
+report the line number for the end of the file, not the locations
+where the missing functions or variables were used; to find these, you
+must search the file manually.
+
+ If you are sure that a warning message about a missing function or
+variable is unjustified, there are several ways to suppress it:
+
address@hidden @bullet
address@hidden
+You can suppress the warning for a specific call to a function
address@hidden by conditionalizing it on an @code{fboundp} test, like
+this:
@example
(if (fboundp '@var{func}) ...(@var{func} ...)...)
@@ -463,14 +469,10 @@
@code{if}, and @var{func} must appear quoted in the call to
@code{fboundp}. (This feature operates for @code{cond} as well.)
- You can tell the compiler that a function is defined using
address@hidden (@pxref{Declaring Functions}). Likewise, you
-can tell the compiler that a variable is defined using @code{defvar}
-with no initial value.
-
- You can suppress the compiler warning for a specific use of an
-undefined variable @var{variable} by conditionalizing its use on a
address@hidden test, like this:
address@hidden
+Likewise, you can suppress the warning for a specific use of a
+variable @var{variable} by conditionalizing it on a @code{boundp}
+test:
@example
(if (boundp '@var{variable}) address@hidden)
@@ -481,7 +483,17 @@
@code{if}, and @var{variable} must appear quoted in the call to
@code{boundp}.
- You can suppress any and all compiler warnings within a certain
address@hidden
+You can tell the compiler that a function is defined using
address@hidden @xref{Declaring Functions}.
+
address@hidden
+Likewise, you can tell the compiler that a variable is defined using
address@hidden with no initial value. (Note that this marks the
+variable as special.) @xref{Defining Variables}.
address@hidden itemize
+
+ You can also suppress any and all compiler warnings within a certain
expression using the construct @code{with-no-warnings}:
@c This is implemented with a defun, but conceptually it is
@@ -497,8 +509,9 @@
one you intend to suppress.
@end defspec
- More precise control of warnings is possible by setting the variable
address@hidden
+ Byte compiler warnings can be controlled more precisely by setting
+the variable @code{byte-compile-warnings}. See its documentation
+string for details.
@node Byte-Code Objects
@section Byte-Code Function Objects
=== modified file 'doc/lispref/customize.texi'
--- a/doc/lispref/customize.texi 2014-01-01 07:43:34 +0000
+++ b/doc/lispref/customize.texi 2014-01-05 23:36:13 +0000
@@ -287,13 +287,17 @@
The argument @var{standard} is an expression that specifies the
standard value for @var{option}. Evaluating the @code{defcustom} form
-evaluates @var{standard}, but does not necessarily install the
-standard value. If @var{option} already has a default value,
address@hidden does not change it. If the user has saved a
-customization for @var{option}, @code{defcustom} installs the user's
-customized value as @var{option}'s default value. If neither of those
-cases applies, @code{defcustom} installs the result of evaluating
address@hidden as the default value.
+evaluates @var{standard}, but does not necessarily bind the option to
+that value. If @var{option} already has a default value, it is left
+unchanged. If the user has already saved a customization for
address@hidden, the user's customized value is installed as the default
+value. Otherwise, the result of evaluating @var{standard} is
+installed as the default value.
+
+Like @code{defvar}, this macro marks @code{option} as a special
+variable, meaning that it should always be dynamically bound. If
address@hidden is already lexically bound, that lexical binding remains
+in effect until the binding construct exits. @xref{Variable Scoping}.
The expression @var{standard} can be evaluated at various other times,
too---whenever the customization facility needs to know @var{option}'s
=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi 2014-01-01 08:31:29 +0000
+++ b/doc/lispref/elisp.texi 2014-01-05 23:36:13 +0000
@@ -951,7 +951,8 @@
* Testing Accessibility:: Is a given file readable? Writable?
* Kinds of Files:: Is it a directory? A symbolic link?
* Truenames:: Eliminating symbolic links from a file name.
-* File Attributes:: How large is it? Any other names? Etc.
+* File Attributes:: File sizes, modification times, etc.
+* Extended Attributes:: Extended file attributes for access control.
* Locating Files:: How to find a file in standard places.
File Names
=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi 2014-01-01 07:43:34 +0000
+++ b/doc/lispref/files.texi 2014-01-05 23:36:13 +0000
@@ -7,21 +7,21 @@
@chapter Files
This chapter describes the Emacs Lisp functions and variables to
-find, create, view, save, and otherwise work with files and file
+find, create, view, save, and otherwise work with files and
directories. A few other file-related functions are described in
@ref{Buffers}, and those related to backups and auto-saving are
described in @ref{Backups and Auto-Saving}.
Many of the file functions take one or more arguments that are file
-names. A file name is actually a string. Most of these functions
-expand file name arguments by calling @code{expand-file-name}, so that
+names. A file name is a string. Most of these functions expand file
+name arguments using the function @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
address@hidden/}). @xref{File Name Expansion}.
address@hidden/}). @xref{File Name Expansion}.
In addition, certain @dfn{magic} file names are handled specially.
For example, when a remote file name is specified, Emacs accesses the
-file over the network via an appropriate protocol (@pxref{Remote
-Files,, Remote Files, emacs, The GNU Emacs Manual}). This handling is
+file over the network via an appropriate protocol. @xref{Remote
+Files,, Remote Files, emacs, The GNU Emacs Manual}. This handling is
done at a very low level, so you may assume that all the functions
described in this chapter accept magic file names as file name
arguments, except where noted. @xref{Magic File Names}, for details.
@@ -58,22 +58,21 @@
file ``the visited file'' of the buffer.
A file and a buffer are two different things. A file is information
-recorded permanently in the computer (unless you delete it). A buffer,
-on the other hand, is information inside of Emacs that will vanish at
-the end of the editing session (or when you kill the buffer). Usually,
-a buffer contains information that you have copied from a file; then we
-say the buffer is visiting that file. The copy in the buffer is what
-you modify with editing commands. Such changes to the buffer do not
-change the file; therefore, to make the changes permanent, you must
address@hidden the buffer, which means copying the altered buffer contents
-back into the file.
+recorded permanently in the computer (unless you delete it). A
+buffer, on the other hand, is information inside of Emacs that will
+vanish at the end of the editing session (or when you kill the
+buffer). When a buffer is visiting a file, it contains information
+copied from the file. The copy in the buffer is what you modify with
+editing commands. Changes to the buffer do not change the file; to
+make the changes permanent, you must @dfn{save} the buffer, which
+means copying the altered buffer contents back into the file.
- In spite of the distinction between files and buffers, people often
-refer to a file when they mean a buffer and vice-versa. Indeed, we say,
-``I am editing a file'', rather than, ``I am editing a buffer that I
-will soon save as a file of the same name''. Humans do not usually need
-to make the distinction explicit. When dealing with a computer program,
-however, it is good to keep the distinction in mind.
+ Despite the distinction between files and buffers, people often
+refer to a file when they mean a buffer and vice-versa. Indeed, we
+say, ``I am editing a file'', rather than, ``I am editing a buffer
+that I will soon save as a file of the same name''. Humans do not
+usually need to make the distinction explicit. When dealing with a
+computer program, however, it is good to keep the distinction in mind.
@menu
* Visiting Functions:: The usual interface functions for visiting.
@@ -507,9 +506,9 @@
@section Reading from Files
@cindex reading from files
- You can copy a file from the disk and insert it into a buffer
-using the @code{insert-file-contents} function. Don't use the user-level
-command @code{insert-file} in a Lisp program, as that sets the mark.
+ To copy the contents of a file into a buffer, use the function
address@hidden (Don't use the command
address@hidden in a Lisp program, as that sets the mark.)
@defun insert-file-contents filename &optional visit beg end replace
This function inserts the contents of file @var{filename} into the
@@ -769,26 +768,24 @@
@section Information about Files
@cindex file, information about
- The functions described in this section all operate on strings that
-designate file names. With a few exceptions, all the functions have
-names that begin with the word @samp{file}. These functions all
-return information about actual files or directories, so their
-arguments must all exist as actual files or directories unless
-otherwise noted.
+ This section describes the functions for retrieving various types of
+information about files (or directories or symbolic links), such as
+whether a file is readable or writable, and its size. These functions
+all take arguments which are file names. Except where noted, these
+arguments need to specify existing files, or an error is signaled.
@cindex file names, trailing whitespace
@cindex trailing blanks in file names
-Be careful with file names that end in blanks: some filesystems
-(notably, MS-Windows) will ignore trailing whitespace in file names,
-and return information about the file after stripping those blanks
-from the name, not about the file whose name you passed to the
-functions described in this section.
+ Be careful with file names that end in spaces. On some filesystems
+(notably, MS-Windows), trailing whitespace characters in file names
+are silently and automatically ignored.
@menu
* Testing Accessibility:: Is a given file readable? Writable?
* Kinds of Files:: Is it a directory? A symbolic link?
* Truenames:: Eliminating symbolic links from a file name.
-* File Attributes:: How large is it? Any other names? Etc.
+* File Attributes:: File sizes, modification times, etc.
+* Extended Attributes:: Extended file attributes for access control.
* Locating Files:: How to find a file in standard places.
@end menu
@@ -797,10 +794,16 @@
@cindex accessibility of a file
@cindex file accessibility
- These functions test for permission to access a file in specific
-ways. Unless explicitly stated otherwise, they recursively follow
-symbolic links for their file name arguments, at all levels (at the
-level of the file itself and at all levels of parent directories).
+ These functions test for permission to access a file for reading,
+writing, or execution. Unless explicitly stated otherwise, they
+recursively follow symbolic links for their file name arguments, at
+all levels (at the level of the file itself and at all levels of
+parent directories).
+
+ On some operating systems, more complex sets of access permissions
+can be specified, via mechanisms such as Access Control Lists (ACLs).
address@hidden Attributes}, for how to query and set those
+permissions.
@defun file-exists-p filename
This function returns @code{t} if a file named @var{filename} appears
@@ -810,9 +813,8 @@
containing directories, regardless of the permissions of the file
itself.)
-If the file does not exist, or if fascist access control policies
-prevent you from finding the attributes of the file, this function
-returns @code{nil}.
+If the file does not exist, or if access control policies prevent you
+from finding its attributes, this function returns @code{nil}.
Directories are files, so @code{file-exists-p} returns @code{t} when
given a directory name. However, symbolic links are treated
@@ -823,24 +825,8 @@
@defun file-readable-p filename
This function returns @code{t} if a file named @var{filename} exists
and you can read it. It returns @code{nil} otherwise.
-
address@hidden
address@hidden
-(file-readable-p "files.texi")
- @result{} t
address@hidden group
address@hidden
-(file-exists-p "/usr/spool/mqueue")
- @result{} t
address@hidden group
address@hidden
-(file-readable-p "/usr/spool/mqueue")
- @result{} nil
address@hidden group
address@hidden example
@end defun
address@hidden Emacs 19 feature
@defun file-executable-p filename
This function returns @code{t} if a file named @var{filename} exists and
you can execute it. It returns @code{nil} otherwise. On Unix and
@@ -856,27 +842,18 @@
but the specified directory does exist and you can write in that
directory.
-In the third example below, @file{foo} is not writable because the
-parent directory does not exist, even though the user could create such
-a directory.
+In the example below, @file{foo} is not writable because the parent
+directory does not exist, even though the user could create such a
+directory.
@example
@group
-(file-writable-p "~/foo")
- @result{} t
address@hidden group
address@hidden
-(file-writable-p "/foo")
- @result{} nil
address@hidden group
address@hidden
(file-writable-p "~/no-such-dir/foo")
@result{} nil
@end group
@end example
@end defun
address@hidden Emacs 19 feature
@defun file-accessible-directory-p dirname
This function returns @code{t} if you have permission to open existing
files in the directory whose name as a file is @var{dirname};
@@ -885,16 +862,13 @@
@file{/foo/}) or the file name of a file which is a directory
(such as @file{/foo}, without the final slash).
-Example: after the following,
+For example, from the following we deduce that any attempt to read a
+file in @file{/foo/} will give an error:
@example
(file-accessible-directory-p "/foo")
@result{} nil
@end example
-
address@hidden
-we can deduce that any attempt to read a file in @file{/foo/} will
-give an error.
@end defun
@defun access-file filename string
@@ -917,39 +891,59 @@
follow symbolic links at all levels of parent directories.
@end defun
address@hidden file-newer-than-file-p filename1 filename2
address@hidden file age
address@hidden file modification time
-This function returns @code{t} if the file @var{filename1} is
-newer than file @var{filename2}. If @var{filename1} does not
-exist, it returns @code{nil}. If @var{filename1} does exist, but
address@hidden does not, it returns @code{t}.
-
-In the following example, assume that the file @file{aug-19} was written
-on the 19th, @file{aug-20} was written on the 20th, and the file
address@hidden doesn't exist at all.
address@hidden file-modes filename
address@hidden mode bits
address@hidden file permissions
address@hidden permissions, file
address@hidden file modes
+This function returns the @dfn{mode bits} of @var{filename}---an
+integer summarizing its read, write, and execution permissions.
+Symbolic links in @var{filename} are recursively followed at all
+levels. If the file does not exist, the return value is @code{nil}.
+
address@hidden permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+Manual}, for a description of mode bits. For example, if the
+low-order bit is 1, the file is executable by all users; if the
+second-lowest-order bit is 1, the file is writable by all users; etc.
+The highest possible value is 4095 (7777 octal), meaning that everyone
+has read, write, and execute permission, the @acronym{SUID} bit is set
+for both others and group, and the sticky bit is set.
+
address@hidden Files}, for the @code{set-file-modes} function, which
+can be used to set these permissions.
@example
@group
-(file-newer-than-file-p "aug-19" "aug-20")
- @result{} nil
address@hidden group
address@hidden
-(file-newer-than-file-p "aug-20" "aug-19")
- @result{} t
address@hidden group
address@hidden
-(file-newer-than-file-p "aug-19" "no-file")
- @result{} t
address@hidden group
address@hidden
-(file-newer-than-file-p "no-file" "aug-19")
- @result{} nil
+(file-modes "~/junk/diffs")
+ @result{} 492 ; @r{Decimal integer.}
address@hidden group
address@hidden
+(format "%o" 492)
+ @result{} "754" ; @r{Convert to octal.}
address@hidden group
+
address@hidden
+(set-file-modes "~/junk/diffs" #o666)
+ @result{} nil
address@hidden group
+
address@hidden
+$ ls -l diffs
+-rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs
@end group
@end example
-You can use @code{file-attributes} to get a file's last modification
-time as a list of four integers. @xref{File Attributes}.
address@hidden MS-DOS and file modes
address@hidden file modes and MS-DOS
address@hidden note:} On MS-DOS, there is no such thing as an
+``executable'' file mode bit. So @code{file-modes} considers a file
+executable if its name ends in one of the standard executable
+extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some
+others. Files that begin with the Unix-standard @samp{#!} signature,
+such as shell and Perl scripts, are also considered executable.
+Directories are also reported as executable, for compatibility with
+Unix. These conventions are also followed by @code{file-attributes}
+(@pxref{File Attributes}).
@end defun
@node Kinds of Files
@@ -987,8 +981,6 @@
@result{} "/pub/bin"
@end group
@end example
-
address@hidden !!! file-symlink-p: should show output of ls -l for comparison
@end defun
The next two functions recursively follow symbolic links at
@@ -1029,21 +1021,6 @@
other I/O device).
@end defun
address@hidden file-equal-p file1 file2
-This function returns @code{t} if the files @var{file1} and
address@hidden name the same file. If @var{file1} or @var{file2} does
-not exist, the return value is unspecified.
address@hidden defun
-
address@hidden file-in-directory-p file dir
-This function returns @code{t} if @var{file} is a file in directory
address@hidden, or in a subdirectory of @var{dir}. It also returns
address@hidden if @var{file} and @var{dir} are the same directory. It
-compares the @code{file-truename} values of the two directories
-(@pxref{Truenames}). If @var{dir} does not name an existing
-directory, the return value is @code{nil}.
address@hidden defun
-
@node Truenames
@subsection Truenames
@cindex truename (of file)
@@ -1066,14 +1043,14 @@
substitute-in-file-name}.
If you may need to follow symbolic links preceding @samp{..}@:
-appearing as a name component, you should make sure to call
address@hidden without prior direct or indirect calls to
address@hidden, as otherwise the file name component
-immediately preceding @samp{..} will be ``simplified away'' before
address@hidden is called. To eliminate the need for a call to
address@hidden, @code{file-truename} handles @samp{~} in the
-same way that @code{expand-file-name} does. @xref{File Name
-Expansion,, Functions that Expand Filenames}.
+appearing as a name component, call @code{file-truename} without prior
+direct or indirect calls to @code{expand-file-name}. Otherwise, the
+file name component immediately preceding @samp{..} will be
+``simplified away'' before @code{file-truename} is called. To
+eliminate the need for a call to @code{expand-file-name},
address@hidden handles @samp{~} in the same way that
address@hidden does. @xref{File Name Expansion,, Functions
+that Expand Filenames}.
@end defun
@defun file-chase-links filename &optional limit
@@ -1102,70 +1079,61 @@
@result{} "/home/foo/hello"
@end example
- @xref{Buffer File Name}, for related information.
address@hidden file-equal-p file1 file2
+This function returns @code{t} if the files @var{file1} and
address@hidden name the same file. This is similar to comparing their
+truenames, except that remote file names are also handled in an
+appropriate manner. If @var{file1} or @var{file2} does not exist, the
+return value is unspecified.
address@hidden defun
+
address@hidden file-in-directory-p file dir
+This function returns @code{t} if @var{file} is a file in directory
address@hidden, or in a subdirectory of @var{dir}. It also returns
address@hidden if @var{file} and @var{dir} are the same directory. It
+compares the truenames of the two directories. If @var{dir} does not
+name an existing directory, the return value is @code{nil}.
address@hidden defun
@node File Attributes
address@hidden Other Information about Files
address@hidden File Attributes
address@hidden file attributes
This section describes the functions for getting detailed
-information about a file, other than its contents. This information
-includes the mode bits that control access permissions, the owner and
-group numbers, the number of names, the inode number, the size, and
-the times of access and modification.
-
address@hidden file-modes filename
address@hidden file permissions
address@hidden permissions, file
address@hidden file attributes
address@hidden file modes
-This function returns the @dfn{mode bits} describing the @dfn{file
-permissions} of @var{filename}, as an integer. It recursively follows
-symbolic links in @var{filename} at all levels. If @var{filename}
-does not exist, the return value is @code{nil}.
-
address@hidden permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
-Manual}, for a description of mode bits. If the low-order bit is 1,
-then the file is executable by all users, if the second-lowest-order
-bit is 1, then the file is writable by all users, etc. The highest
-value returnable is 4095 (7777 octal), meaning that everyone has read,
-write, and execute permission, that the @acronym{SUID} bit is set for
-both others and group, and that the sticky bit is set.
+information about a file, including the owner and group numbers, the
+number of names, the inode number, the size, and the times of access
+and modification.
+
address@hidden file-newer-than-file-p filename1 filename2
address@hidden file age
address@hidden file modification time
+This function returns @code{t} if the file @var{filename1} is
+newer than file @var{filename2}. If @var{filename1} does not
+exist, it returns @code{nil}. If @var{filename1} does exist, but
address@hidden does not, it returns @code{t}.
+
+In the following example, assume that the file @file{aug-19} was written
+on the 19th, @file{aug-20} was written on the 20th, and the file
address@hidden doesn't exist at all.
@example
@group
-(file-modes "~/junk/diffs")
- @result{} 492 ; @r{Decimal integer.}
address@hidden group
address@hidden
-(format "%o" 492)
- @result{} "754" ; @r{Convert to octal.}
address@hidden group
-
address@hidden
-(set-file-modes "~/junk/diffs" #o666)
- @result{} nil
address@hidden group
-
address@hidden
-$ ls -l diffs
--rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs
+(file-newer-than-file-p "aug-19" "aug-20")
+ @result{} nil
address@hidden group
address@hidden
+(file-newer-than-file-p "aug-20" "aug-19")
+ @result{} t
address@hidden group
address@hidden
+(file-newer-than-file-p "aug-19" "no-file")
+ @result{} t
address@hidden group
address@hidden
+(file-newer-than-file-p "no-file" "aug-19")
+ @result{} nil
@end group
@end example
-
address@hidden Files}, for functions that change file permissions,
-such as @code{set-file-modes}.
-
address@hidden MS-DOS and file modes
address@hidden file modes and MS-DOS
address@hidden note:} On MS-DOS, there is no such thing as an
-``executable'' file mode bit. So @code{file-modes} considers a file
-executable if its name ends in one of the standard executable
-extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some
-others. Files that begin with the Unix-standard @samp{#!} signature,
-such as shell and Perl scripts, are also considered executable.
-Directories are also reported as executable, for compatibility with
-Unix. These conventions are also followed by @code{file-attributes},
-below.
@end defun
If the @var{filename} argument to the next two functions is a
@@ -1173,31 +1141,6 @@
target. However, they both recursively follow symbolic links at all
levels of parent directories.
address@hidden file-nlinks filename
-This function returns the number of names (i.e., hard links) that
-file @var{filename} has. If the file does not exist, this function
-returns @code{nil}. Note that symbolic links have no effect on this
-function, because they are not considered to be names of the files
-they link to.
-
address@hidden
address@hidden
-$ ls -l foo*
--rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo
--rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1
address@hidden group
-
address@hidden
-(file-nlinks "foo")
- @result{} 2
address@hidden group
address@hidden
-(file-nlinks "doesnt-exist")
- @result{} nil
address@hidden group
address@hidden example
address@hidden defun
-
@defun file-attributes filename &optional id-format
@anchor{Definition of file-attributes}
This function returns a list of attributes of file @var{filename}. If
@@ -1339,52 +1282,99 @@
@end table
@end defun
address@hidden SELinux context
- SELinux is a Linux kernel feature which provides more sophisticated
-file access controls than ordinary ``Unix-style'' file permissions.
-If Emacs has been compiled with SELinux support on a system with
-SELinux enabled, you can use the function @code{file-selinux-context}
-to retrieve a file's SELinux security context. For the function
address@hidden, see @ref{Changing Files}.
-
address@hidden file-selinux-context filename
-This function returns the SELinux security context of the file
address@hidden This return value is a list of the form
address@hidden(@var{user} @var{role} @var{type} @var{range})}, whose elements
-are the context's user, role, type, and range respectively, as Lisp
-strings. See the SELinux documentation for details about what these
-actually mean.
-
-If the file does not exist or is inaccessible, or if the system does
-not support SELinux, or if Emacs was not compiled with SELinux
-support, then the return value is @code{(nil nil nil nil)}.
address@hidden file-nlinks filename
+This function returns the number of names (i.e., hard links) that
+file @var{filename} has. If the file does not exist, this function
+returns @code{nil}. Note that symbolic links have no effect on this
+function, because they are not considered to be names of the files
+they link to.
+
address@hidden
address@hidden
+$ ls -l foo*
+-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo
+-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1
address@hidden group
+
address@hidden
+(file-nlinks "foo")
+ @result{} 2
address@hidden group
address@hidden
+(file-nlinks "doesnt-exist")
+ @result{} nil
address@hidden group
address@hidden example
@end defun
address@hidden Extended Attributes
address@hidden Extended File Attributes
address@hidden extended file attributes
+
+On some operating systems, each file can be associated with arbitrary
address@hidden file attributes}. At present, Emacs supports querying
+and setting two specific sets of extended file attributes: Access
+Control Lists (ACLs) and SELinux contexts. These extended file
+attributes are used, on some systems, to impose more sophisticated
+file access controls than the basic ``Unix-style'' permissions
+discussed in the previous sections.
+
@cindex access control list
@cindex ACL entries
- If Emacs has been compiled with @dfn{ACL} (access control list)
-support, you can use the function @code{file-acl} to retrieve a file's
-ACL entries. The interface implementation is platform-specific; on
-GNU/Linux and BSD, Emacs uses the POSIX ACL interface, while on
-MS-Windows Emacs emulates the POSIX ACL interface with native file
-security APIs.
address@hidden SELinux context
+ A detailed explanation of ACLs and SELinux is beyond the scope of
+this manual. For our purposes, each file can be associated with an
address@hidden, which specifies its properties under an ACL-based file
+control system, and/or an @dfn{SELinux context}, which specifies its
+properties under the SELinux system.
@defun file-acl filename
-This function returns the ACL entries of the file @var{filename}. The
-return value is a platform-dependent object containing some
-representation of the ACL entries. Don't use it for anything except
-passing it to the @code{set-file-acl} function (@pxref{Changing Files,
-set-file-acl}).
-
-If the file does not exist or is inaccessible, or if Emacs was unable to
-determine the ACL entries, then the return value is @code{nil}. The
-latter can happen for local files if Emacs was not compiled with ACL
-support, or for remote files if the file handler returns nil for the
-file's ACL entries.
+This function returns the ACL for the file @var{filename}. The exact
+Lisp representation of the ACL is unspecified (and may change in
+future Emacs versions), but it is the same as what @code{set-file-acl}
+takes for its @var{acl} argument (@pxref{Changing Files}).
+
+The underlying ACL implementation is platform-specific; on GNU/Linux
+and BSD, Emacs uses the POSIX ACL interface, while on MS-Windows Emacs
+emulates the POSIX ACL interface with native file security APIs.
+
+If Emacs was not compiled with ACL support, or the file does not exist
+or is inaccessible, or Emacs was unable to determine the ACL entries
+for any other reason, then the return value is @code{nil}.
address@hidden defun
+
address@hidden file-selinux-context filename
+This function returns the SELinux context of the file @var{filename},
+as a list of the form @code{(@var{user} @var{role} @var{type}
address@hidden)}. The list elements are the context's user, role, type,
+and range respectively, as Lisp strings; see the SELinux documentation
+for details about what these actually mean. The return value has the
+same form as what @code{set-file-selinux-context} takes for its
address@hidden argument (@pxref{Changing Files}).
+
+If Emacs was not compiled with SELinux support, or the file does not
+exist or is inaccessible, or if the system does not support SELinux,
+then the return value is @code{(nil nil nil nil)}.
address@hidden defun
+
address@hidden file-extended-attributes filename
+This function returns an alist of the Emacs-recognized extended
+attributes of file @var{filename}. Currently, it serves as a
+convenient way to retrieve both the ACL and SELinux context; you can
+then call the function @code{set-file-extended-attributes}, with the
+returned alist as its second argument, to apply the same file access
+attributes to another file (@pxref{Changing Files}).
+
+One of the elements is @code{(acl . @var{acl})}, where @var{acl} has
+the same form returned by @code{file-acl}.
+
+Another element is @code{(selinux-context . @var{context})}, where
address@hidden is the SELinux context, in the same form returned by
address@hidden
@end defun
@node Locating Files
address@hidden How to Locate Files in Standard Places
address@hidden Locating Files in Standard Places
@cindex locate file in path
@cindex find file in path
@@ -1571,10 +1561,11 @@
the correct permissions to do so.
If the optional argument @var{preserve-permissions} is address@hidden,
-this function copies the file's permissions, such as its file modes,
-its SELinux context, and ACL entries (@pxref{File Attributes}).
-Otherwise, if the destination is created its file permission bits are
-those of the source, masked by the default file permissions.
+this function copies the file modes (or ``permissions''), as well as
+its Access Control List and SELinux context (if any).
address@hidden about Files}. Otherwise, if the destination is
+created its file permission bits are those of the source, masked by
+the default file permissions.
@end deffn
@deffn Command make-symbolic-link filename newname &optional ok-if-exists
@@ -1616,7 +1607,7 @@
@cindex permissions, file
@cindex file modes, setting
@deffn Command set-file-modes filename mode
-This function sets the @dfn{file mode} (or @dfn{file permissions}) of
+This function sets the @dfn{file mode} (or @dfn{permissions}) of
@var{filename} to @var{mode}. It recursively follows symbolic links
at all levels for @var{filename}.
@@ -1705,25 +1696,31 @@
(@pxref{Time of Day}).
@end defun
address@hidden set-file-extended-attributes filename attribute-alist
+This function sets the Emacs-recognized extended file attributes for
address@hidden The second argument @var{attribute-alist} should be
+an alist of the same form returned by @code{file-extended-attributes}.
address@hidden Attributes}.
address@hidden defun
+
@defun set-file-selinux-context filename context
-This function sets the SELinux security context of the file
address@hidden to @var{context}. @xref{File Attributes}, for a brief
-description of SELinux contexts. The @var{context} argument should be
-a list @code{(@var{user} @var{role} @var{type} @var{range})}, like the
-return value of @code{file-selinux-context}. The function returns
address@hidden if it succeeds to set the SELinux security context of
address@hidden, @code{nil} otherwise. The function does nothing and
-returns @code{nil} if SELinux is disabled, or if Emacs was compiled
-without SELinux support.
+This function sets the SELinux security context for @var{filename} to
address@hidden The @var{context} argument should be a list
address@hidden(@var{user} @var{role} @var{type} @var{range})}, where each
+element is a string. @xref{Extended Attributes}.
+
+The function returns @code{t} if it succeeds in setting the SELinux
+context of @var{filename}. It returns @code{nil} if the context was
+not set (e.g., if SELinux is disabled, or if Emacs was compiled
+without SELinux support).
@end defun
address@hidden set-file-acl filename acl-string
-This function sets the ACL entries of the file @var{filename} to
address@hidden @xref{File Attributes}, for a brief description of
-ACLs. The @var{acl-string} argument should be a string containing the
-textual representation of the desired ACL entries as returned by
address@hidden (@pxref{File Attributes, file-acl}). The function
-returns @code{t} if it succeeds to set the ACL entries of
address@hidden set-file-acl filename acl
+This function sets the Access Control List for @var{filename} to
address@hidden The @var{acl} argument should have the same form returned
+by the function @code{file-acl}. @xref{Extended Attributes}.
+
+The function returns @code{t} if it successfully sets the ACL of
@var{filename}, @code{nil} otherwise.
@end defun
=== modified file 'doc/lispref/minibuf.texi'
--- a/doc/lispref/minibuf.texi 2014-01-01 07:43:34 +0000
+++ b/doc/lispref/minibuf.texi 2014-01-05 23:36:13 +0000
@@ -2224,12 +2224,6 @@
properties, just the characters themselves. @xref{Text Properties}.
@end defun
address@hidden minibuffer-completion-contents
-This is like @code{minibuffer-contents}, except that it returns only
-the contents before point. That is the part that completion commands
-operate on. @xref{Minibuffer Completion}.
address@hidden defun
-
@defun delete-minibuffer-contents
This function erases the editable contents of the minibuffer (that is,
everything except the prompt), if a minibuffer is current. Otherwise,
=== modified file 'doc/lispref/variables.texi'
--- a/doc/lispref/variables.texi 2014-01-01 07:43:34 +0000
+++ b/doc/lispref/variables.texi 2014-01-05 23:36:13 +0000
@@ -416,18 +416,23 @@
@dfn{special}, meaning that it should always be dynamically bound
(@pxref{Variable Scoping}).
-If @var{symbol} is void and @var{value} is specified, @code{defvar}
-evaluates @var{value} and sets @var{symbol} to the result. But if
address@hidden already has a value (i.e., it is not void), @var{value}
-is not even evaluated, and @var{symbol}'s value remains unchanged. If
address@hidden is omitted, the value of @var{symbol} is not changed in
-any case.
+If @var{value} is specified, and @var{symbol} is void (i.e., it has no
+dynamically bound value; @pxref{Void Variables}), then @var{value} is
+evaluated and @var{symbol} is set to the result. But if @var{symbol}
+is not void, @var{value} is not evaluated, and @var{symbol}'s value is
+left unchanged. If @var{value} is omitted, the value of @var{symbol}
+is not changed in any case.
If @var{symbol} has a buffer-local binding in the current buffer,
address@hidden operates on the default value, which is buffer-independent,
-not the current (buffer-local) binding. It sets the default value if
address@hidden acts on the default value, which is buffer-independent,
+rather than the buffer-local binding. It sets the default value if
the default value is void. @xref{Buffer-Local Variables}.
+If @var{symbol} is already lexically bound (e.g., if the @code{defvar}
+form occurs in a @code{let} form with lexical binding enabled), then
address@hidden sets the dynamic value. The lexical binding remains in
+effect until its binding construct exits. @xref{Variable Scoping}.
+
When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
Emacs Lisp mode (@code{eval-defun}), a special feature of
@code{eval-defun} arranges to set the variable unconditionally, without
=== modified file 'etc/NEWS'
--- a/etc/NEWS 2014-01-05 06:10:52 +0000
+++ b/etc/NEWS 2014-01-05 23:36:13 +0000
@@ -904,6 +904,7 @@
** `(input-pending-p)' no longer runs other timers which are ready to
run. The new optional CHECK-TIMERS param allows for the prior behavior.
++++
** `defvar' and `defcustom' in a let-binding affect the "external" default.
---
@@ -958,6 +959,7 @@
when lexical binding is enabled. Previously, VAR was bound to nil,
which often led to spurious unused-variable warnings.
++++
** The return value of `backup-buffer' has changed.
The second argument is no longer an SELinux context, instead it is an
alist of extended attributes as returned by the new function
@@ -1083,6 +1085,7 @@
*** `string-remove-prefix'
*** `string-remove-suffix'
++++
** Obsoleted functions:
*** `log10'
*** `dont-compile'
@@ -1100,8 +1103,10 @@
*** `completion-in-region-function' obsoletes `completion-in-region-functions'.
*** `filter-buffer-substring-function' obsoletes
`filter-buffer-substring-functions'.
++++
** `byte-compile-interactive-only-functions' is now obsolete.
-It has been replaced by the symbol property 'interactive-only.
+To specify that a command should only be called interactively, give it
+a non-nil `interactive-only' property.
+++
** `split-string' now takes an optional argument TRIM.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] trunk r115880: More doc updates.,
Chong Yidong <=