diff options
Diffstat (limited to 'doc/lispref/files.texi')
| -rw-r--r-- | doc/lispref/files.texi | 81 |
1 files changed, 69 insertions, 12 deletions
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 08677f789a5..986fb22c75b 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -581,9 +581,12 @@ contents of the file. This is better than simply deleting the buffer contents and inserting the whole file, because (1) it preserves some marker positions and (2) it puts less data in the undo list. -It is possible to read a special file (such as a FIFO or an I/O device) -with @code{insert-file-contents}, as long as @var{replace} and -@var{visit} are @code{nil}. +It is possible to read a special file (such as a FIFO or an I/O +device) with @code{insert-file-contents}, as long as @var{replace}, +and @var{visit} and @var{beg} are @code{nil}. However, you should +normally use an @var{end} argument for these files to avoid inserting +(potentially) unlimited data into the buffer (for instance, when +inserting data from @file{/dev/urandom}). @end defun @defun insert-file-contents-literally filename &optional visit beg end replace @@ -1314,6 +1317,20 @@ on the 19th, @file{aug-20} was written on the 20th, and the file @end example @end defun +@defun file-has-changed-p filename tag +This function returns non-@code{nil} if the time stamp of +@var{filename} has changed since the last call. When called for the +first time for some @var{filename}, it records the last modification +time and size of the file, and returns non-@code{nil} when +@var{filename} exists. Thereafter, when called for the same +@var{filename}, it compares the current time stamp and size with the +recorded ones, and returns non-@code{nil} only if either the time +stamp or the size (or both) are different. This is useful when a Lisp +program wants to re-read a file whenever it changes. With an optional +argument @var{tag}, which must be a symbol, the size and modification +time comparisons are limited to calls with the same tag. +@end 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 @@ -1436,13 +1453,19 @@ is owned by the user with name @samp{lh}. is in the group with name @samp{users}. @item (20614 64019 50040 152000) -was last accessed on October 23, 2012, at 20:12:03.050040152 UTC. +was last accessed on October 23, 2012, at 20:12:03.050040152 UTC@. +(This timestamp is @code{(1351023123050040152 . 1000000000)} +if @code{current-time-list} is @code{nil}.) @item (20000 23 0 0) -was last modified on July 15, 2001, at 08:53:43 UTC. +was last modified on July 15, 2001, at 08:53:43.000000000 UTC@. +(This timestamp is @code{(1310720023000000000 . 1000000000)} +if @code{current-time-list} is @code{nil}.) @item (20614 64555 902289 872000) -last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC. +last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC@. +(This timestamp is @code{(1351023659902289872 . 1000000000)} +if @code{current-time-list} is @code{nil}.) @item 122295 is 122295 bytes long. (It may not contain 122295 characters, though, @@ -2083,6 +2106,9 @@ directory. Therefore, Emacs considers a file name as having two main parts: the @dfn{directory name} part, and the @dfn{nondirectory} part (or @dfn{file name within the directory}). Either part may be empty. Concatenating these two parts reproduces the original file name. +@footnote{Emacs follows the GNU convention to use the term @emph{file name} +instead of the term @emph{pathname}. We use the term @emph{path} only for +search paths, which are lists of directory names.} On most systems, the directory part is everything up to and including the last slash (backslash is also allowed in input on MS-DOS or @@ -2227,6 +2253,19 @@ and @code{file-name-nondirectory}. For example, @end example @end defun +@defun file-name-split filename +This function splits a file name into its components, and can be +thought of as the inverse of @code{string-join} with the appropriate +directory separator. For example, + +@example +(file-name-split "/tmp/foo.txt") + @result{} ("" "tmp" "foo.txt") +(string-join (file-name-split "/tmp/foo.txt") "/") + @result{} "/tmp/foo.txt" +@end example +@end defun + @node Relative File Names @subsection Absolute and Relative File Names @cindex absolute file name @@ -2406,6 +2445,15 @@ You can use this function for directory names and for file names, because it recognizes abbreviations even as part of the name. @end defun +@defun file-parent-directory filename +This function returns the directory name of the parent directory of +@var{filename}. If @var{filename} is at the root directory of the +filesystem, it returns @code{nil}. A relative @var{filename} is +assumed to be relative to @code{default-directory}, and the return +value will also be relative in that case. If the return value is +non-@code{nil}, it ends in a slash. +@end defun + @node File Name Expansion @subsection Functions that Expand Filenames @cindex expansion of file names @@ -3076,10 +3124,16 @@ except those two. It is useful as the @var{match-regexp} argument to returns @code{nil}, if directory @samp{/foo} is empty. @end defvr -@defun file-expand-wildcards pattern &optional full +@defun file-expand-wildcards pattern &optional full regexp This function expands the wildcard pattern @var{pattern}, returning a list of file names that match it. +@var{pattern} is, by default, a ``glob''/wildcard string, e.g., +@samp{"/tmp/*.png"} or @samp{"/*/*/foo.png"}, but can also be a +regular expression if the optional @var{regexp} parameter is non-nil. +In any case, the matches are applied per sub-directory, so a match +can't span a parent/sub directory. + If @var{pattern} is written as an absolute file name, the values are absolute also. @@ -3278,8 +3332,8 @@ first, before handlers for jobs such as remote file access. @ifnottex @noindent -@code{access-file}, @code{add-name-to-file}, -@code{byte-compiler-base-file-name},@* +@code{abbreviate-file-name}, @code{access-file}, +@code{add-name-to-file}, @code{byte-compiler-base-file-name},@* @code{copy-directory}, @code{copy-file}, @code{delete-directory}, @code{delete-file}, @code{diff-latest-backup-file}, @@ -3314,6 +3368,7 @@ first, before handlers for jobs such as remote file access. @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents},@* +@code{list-system-processes}, @code{load}, @code{lock-file}, @code{make-auto-save-file-name}, @code{make-directory}, @@ -3322,7 +3377,7 @@ first, before handlers for jobs such as remote file access. @code{make-nearby-temp-file}, @code{make-process}, @code{make-symbolic-link},@* -@code{process-file}, +@code{process-attributes}, @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @code{set-file-selinux-context}, @code{set-file-times}, @code{set-visited-file-modtime}, @code{shell-command}, @@ -3338,7 +3393,8 @@ first, before handlers for jobs such as remote file access. @iftex @noindent @flushleft -@code{access-file}, @code{add-name-to-file}, +@code{abbreviate-file-name}, @code{access-file}, +@code{add-name-to-file}, @code{byte-com@discretionary{}{}{}piler-base-file-name}, @code{copy-directory}, @code{copy-file}, @code{delete-directory}, @code{delete-file}, @@ -3374,6 +3430,7 @@ first, before handlers for jobs such as remote file access. @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents}, +@code{list-system-processes}, @code{load}, @code{lock-file}, @code{make-auto-save-file-name}, @code{make-direc@discretionary{}{}{}tory}, @@ -3382,7 +3439,7 @@ first, before handlers for jobs such as remote file access. @code{make-nearby-temp-file}, @code{make-process}, @code{make-symbolic-link}, -@code{process-file}, +@code{process-attributes}, @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @code{set-file-selinux-context}, @code{set-file-times}, @code{set-visited-file-modtime}, @code{shell-command}, |