elisp: File Attributes
24.6.4 File Attributes
----------------------
This section describes the functions for getting detailed 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.
-- Function: file-newer-than-file-p filename1 filename2
This function returns ‘t’ if the file FILENAME1 is newer than file
FILENAME2. If FILENAME1 does not exist, it returns ‘nil’. If
FILENAME1 does exist, but FILENAME2 does not, it returns ‘t’.
In the following example, assume that the file ‘aug-19’ was written
on the 19th, ‘aug-20’ was written on the 20th, and the file
‘no-file’ doesn’t exist at all.
(file-newer-than-file-p "aug-19" "aug-20")
⇒ nil
(file-newer-than-file-p "aug-20" "aug-19")
⇒ t
(file-newer-than-file-p "aug-19" "no-file")
⇒ t
(file-newer-than-file-p "no-file" "aug-19")
⇒ nil
If the FILENAME argument to the next two functions is a symbolic
link, then these function do _not_ replace it with its target. However,
they both recursively follow symbolic links at all levels of parent
directories.
-- Function: file-attributes filename &optional id-format
This function returns a list of attributes of file FILENAME. If
the specified file cannot be opened, it returns ‘nil’. The
optional parameter ID-FORMAT specifies the preferred format of
attributes UID and GID (see below)—the valid values are ‘'string’
and ‘'integer’. The latter is the default, but we plan to change
that, so you should specify a non-‘nil’ value for ID-FORMAT if you
use the returned UID or GID.
The elements of the list, in order, are:
0. ‘t’ for a directory, a string for a symbolic link (the name
linked to), or ‘nil’ for a text file.
1. The number of names the file has. Alternate names, also known
as hard links, can be created by using the ‘add-name-to-file’
function (Changing Files).
2. The file’s UID, normally as a string. However, if it does not
correspond to a named user, the value is a number.
3. The file’s GID, likewise.
4. The time of last access, as a list of four integers ‘(SEC-HIGH
SEC-LOW MICROSEC PICOSEC)’. (This is similar to the value of
‘current-time’; see Time of Day.) Note that on some
FAT-based filesystems, only the date of last access is
recorded, so this time will always hold the midnight of the
day of last access.
5. The time of last modification as a list of four integers (as
above). This is the last time when the file’s contents were
modified.
6. The time of last status change as a list of four integers (as
above). This is the time of the last change to the file’s
access mode bits, its owner and group, and other information
recorded in the filesystem for the file, beyond the file’s
contents.
7. The size of the file in bytes. This is floating point if the
size is too large to fit in a Lisp integer.
8. The file’s modes, as a string of ten letters or dashes, as in
‘ls -l’.
9. An unspecified value, present for backward compatibility.
10. The file’s inode number. If possible, this is an integer.
If the inode number is too large to be represented as an
integer in Emacs Lisp but dividing it by 2^{16} yields a
representable integer, then the value has the form ‘(HIGH .
LOW)’, where LOW holds the low 16 bits. If the inode number
is too wide for even that, the value is of the form ‘(HIGH
MIDDLE . LOW)’, where ‘high’ holds the high bits, MIDDLE the
middle 24 bits, and LOW the low 16 bits.
11. The filesystem number of the device that the file is on.
Depending on the magnitude of the value, this can be either an
integer or a cons cell, in the same manner as the inode
number. This element and the file’s inode number together
give enough information to distinguish any two files on the
system—no two files can have the same values for both of these
numbers.
For example, here are the file attributes for ‘files.texi’:
(file-attributes "files.texi" 'string)
⇒ (nil 1 "lh" "users"
(20614 64019 50040 152000)
(20000 23 0 0)
(20614 64555 902289 872000)
122295 "-rw-rw-rw-"
t (5888 2 . 43978)
(15479 . 46724))
and here is how the result is interpreted:
‘nil’
is neither a directory nor a symbolic link.
‘1’
has only one name (the name ‘files.texi’ in the current
default directory).
‘"lh"’
is owned by the user with name ‘lh’.
‘"users"’
is in the group with name ‘users’.
‘(20614 64019 50040 152000)’
was last accessed on October 23, 2012, at 20:12:03.050040152
UTC.
‘(20000 23 0 0)’
was last modified on July 15, 2001, at 08:53:43 UTC.
‘(20614 64555 902289 872000)’
last had its status changed on October 23, 2012, at
20:20:59.902289872 UTC.
‘122295’
is 122295 bytes long. (It may not contain 122295 characters,
though, if some of the bytes belong to multibyte sequences,
and also if the end-of-line format is CR-LF.)
‘"-rw-rw-rw-"’
has a mode of read and write access for the owner, group, and
world.
‘t’
is merely a placeholder; it carries no information.
‘(5888 2 . 43978)’
has an inode number of 6473924464520138.
‘(15479 . 46724)’
is on the file-system device whose number is 1014478468.
-- Function: file-nlinks filename
This function returns the number of names (i.e., hard links) that
file FILENAME has. If the file does not exist, this function
returns ‘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.
$ 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
(file-nlinks "foo")
⇒ 2
(file-nlinks "doesnt-exist")
⇒ nil