Function: file-attributes

file-attributes is a function defined in dired.c.

Signature

(file-attributes FILENAME &optional ID-FORMAT)

Documentation

Return a list of attributes of file FILENAME.

Value is nil if specified file does not exist.

ID-FORMAT specifies the preferred format of attributes uid and gid (see below) - 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.

To access the elements returned, the following access functions are provided: file-attribute-type, file-attribute-link-number, file-attribute-user-id, file-attribute-group-id, file-attribute-access-time, file-attribute-modification-time, file-attribute-status-change-time, file-attribute-size, file-attribute-modes, file-attribute-inode-number, and file-attribute-device-number.

Elements of the attribute list are:
 0. t for directory, string (name linked to) for symbolic link, or nil.
 1. Number of links to file.
 2. File uid as a string or (if ID-FORMAT is integer or a string value
  cannot be looked up) as an integer.
 3. File gid, likewise.
 4. Last access time, in the style of current-time.
  (See a note below about access time on FAT-based filesystems.)
 5. Last modification time, likewise. This is the time of the last
  change to the file's contents.
 6. Last status change time, likewise. This is the time of last change
  to the file's attributes: owner and group, access mode bits, etc.
 7. Size in bytes, as an integer.
 8. File modes, as a string of ten letters or dashes as in ls -l.
 9. An unspecified value, present only for backward compatibility.
10. inode number, as a nonnegative integer.
11. Filesystem device identifier, as an integer or a cons cell of integers.

Large integers are bignums, so eq might not work on them. On most filesystems, the combination of the inode and the device identifier uniquely identifies the file. This unique file identification is provided by the access function file-attribute-file-identifier.

On MS-Windows, performance depends on w32-get-true-file-attributes, which see.

On some FAT-based filesystems, only the date of last access is recorded, so last access time will always be midnight of that day.

Other relevant functions are documented in the file group.

View in manual

Probably introduced at or before Emacs version 18.

Shortdoc

;; file
(file-attributes "/tmp")
    -> [it depends]

Source Code

// Defined in /usr/src/emacs/src/dired.c
{
  Lisp_Object encoded;
  Lisp_Object handler;

  filename = internal_condition_case_2 (Fexpand_file_name, filename, Qnil,
					Qt, Fidentity);
  if (!STRINGP (filename))
    return Qnil;

  /* If the file name has special constructs in it,
     call the corresponding file name handler.  */
  handler = Ffind_file_name_handler (filename, Qfile_attributes);
  if (!NILP (handler))
    { /* Only pass the extra arg if it is used to help backward
	 compatibility with old file name handlers which do not
	 implement the new arg.  --Stef */
      if (NILP (id_format))
	return call2 (handler, Qfile_attributes, filename);
      else
	return call3 (handler, Qfile_attributes, filename, id_format);
    }

  encoded = ENCODE_FILE (filename);
  return file_attributes (AT_FDCWD, SSDATA (encoded), Qnil, filename,
			  id_format);
}