From: Lars Ingebrigtsen Date: Fri, 4 Mar 2016 13:39:07 +0000 (+0000) Subject: Add accessors for `file-attributes' X-Git-Tag: emacs-26.0.90~2373 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=2d5b20f68c194e7fec7b9602935fd95149e9b7c6;p=emacs.git Add accessors for `file-attributes' * doc/lispref/files.texi (File Attributes): Mention the accessors. * lisp/files.el (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-change-time, file-attribute-size) (file-attribute-modes, file-attribute-inode-number) (file-attribute-device-number): New functions. * src/dired.c (Ffile_attributes): Mention the accessors (bug#22890). --- diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 6b7ee19d5f3..8a6cb7beaad 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1195,73 +1195,83 @@ the default, but we plan to change that, so you should specify a non-@code{nil} value for @var{id-format} if you use the returned @acronym{UID} or @acronym{GID}. +Accessor functions are provided to access the elements in this list. +The accessors are mentioned along with the descriptions of the +elements below. + The elements of the list, in order, are: @enumerate 0 @item @code{t} for a directory, a string for a symbolic link (the name -linked to), or @code{nil} for a text file. +linked to), or @code{nil} for a text file +(@code{file-attribute-type}). @c Wordy so as to prevent an overfull hbox. --rjc 15mar92 @item -The number of names the file has. Alternate names, also known as hard -links, can be created by using the @code{add-name-to-file} function -(@pxref{Changing Files}). +The number of names the file has (@code{file-attribute-link-number}). +Alternate names, also known as hard links, can be created by using the +@code{add-name-to-file} function (@pxref{Changing Files}). @item -The file's @acronym{UID}, normally as a string. However, if it does -not correspond to a named user, the value is a number. +The file's @acronym{UID}, normally as a string +(@code{file-attribute-user-id}). However, if it does not correspond +to a named user, the value is a number. @item -The file's @acronym{GID}, likewise. +The file's @acronym{GID}, likewise (@code{file-attribute-group-id}). @item -The time of last access, as a list of four integers @code{(@var{sec-high} -@var{sec-low} @var{microsec} @var{picosec})}. (This is similar to the -value of @code{current-time}; see @ref{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. +The time of last access, as a list of four integers +@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})} +(@code{file-attribute-access-time}). (This is similar to the value of +@code{current-time}; see @ref{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. @cindex modification time of file @item -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. +The time of last modification as a list of four integers (as above) +(@code{file-attribute-modification-time}). This is the last time when +the file's contents were modified. @item -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. +The time of last status change as a list of four integers (as above) +(code{file-attribute-status-change-time}). 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. @item -The size of the file in bytes. This is floating point if the size is -too large to fit in a Lisp integer. +The size of the file in bytes (@code{file-attribute-size}). This is +floating point if the size is too large to fit in a Lisp integer. @item -The file's modes, as a string of ten letters or dashes, -as in @samp{ls -l}. +The file's modes, as a string of ten letters or dashes, as in +@samp{ls -l} (@code{file-attribute-modes}). @item An unspecified value, present for backward compatibility. @item -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 @math{2^{16}} yields a representable integer, -then the value has the +The file's inode number (@code{file-attribute-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 +@math{2^{16}} yields a representable integer, then the value has the form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 -bits. If the inode number is too wide for even that, the value is of the form -@code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds -the high bits, @var{middle} the middle 24 bits, and @var{low} the low -16 bits. +bits. If the inode number is too wide for even that, the value is of +the form @code{(@var{high} @var{middle} . @var{low})}, where +@code{high} holds the high bits, @var{middle} the middle 24 bits, and +@var{low} the low 16 bits. @item -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. +The filesystem number of the device that the file is on +@code{file-attribute-device-number}). 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. @end enumerate For example, here are the file attributes for @file{files.texi}: diff --git a/etc/NEWS b/etc/NEWS index d7e1b839895..b29d460b19a 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -40,6 +40,16 @@ erc-emacs-build-time. * Changes in Emacs 25.2 ++++ +** A number of accessors for the value returned by `file-attributes' +has been added. They are: `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' + --- ** `align-regexp' has a separate history for its interactive argument `align-regexp' no longer shares its history with all other diff --git a/lisp/files.el b/lisp/files.el index aca7b3593d9..c892ab4e219 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -7083,6 +7083,78 @@ Otherwise, trash FILENAME using the freedesktop.org conventions, (let ((delete-by-moving-to-trash nil)) (rename-file fn new-fn))))))))) +(defsubst file-attribute-type (attributes) + "The type field in ATTRIBUTES returned by `file-attribute'. +The value is either t for directory, string (name linked to) for +symbolic link, or nil." + (nth 0 attributes)) + +(defsubst file-attribute-link-number (attributes) + "Return the number of links in ATTRIBUTES returned by `file-attribute'." + (nth 1 attributes)) + +(defsubst file-attribute-user-id (attributes) + "The UID field in ATTRIBUTES returned by `file-attribute'. +This is either a string or a number. If a string value cannot be +looked up, a numeric value, either an integer or a float, is +returned." + (ntf 2 attributes)) + +(defsubst file-attribute-group-id (attributes) + "The GID field in ATTRIBUTES returned by `file-attribute'. +This is either a string or a number. If a string value cannot be +looked up, a numeric value, either an integer or a float, is +returned." + (ntf 3 attributes)) + +(defsubst file-attribute-access-time (attributes) + "The last access time in ATTRIBUTES returned by `file-attribute'. +This a list of integers (HIGH LOW USEC PSEC) in the same style +as (current-time)." + (ntf 4 attributes)) + +(defsubst file-attribute-modification-time (attributes) + "The modification time in ATTRIBUTES returned by `file-attribute'. +This is the time of the last change to the file's contents, and +is a list of integers (HIGH LOW USEC PSEC) in the same style +as (current-time)." + (ntf 5 attributes)) + +(defsubst file-attribute-status-change-time (attributes) + "The status modification time in ATTRIBUTES returned by `file-attribute'. +This is the time of last change to the file's attributes: owner +and group, access mode bits, etc, and is a list of integers (HIGH +LOW USEC PSEC) in the same style as (current-time)." + (ntf 6 attributes)) + +(defsubst file-attribute-size (attributes) + "The size (in bytes) in ATTRIBUTES returned by `file-attribute'. +This is a floating point number if the size is too large for an integer." + (ntf 7 attributes)) + +(defsubst file-attribute-modes (attributes) + "The file modes in ATTRIBUTES returned by `file-attribute'. +This is a string of ten letters or dashes as in ls -l." + (ntf 8 attributes)) + +(defsubst file-attribute-inode-number (attributes) + "The inode number in ATTRIBUTES returned by `file-attribute'. +If it is larger than what an Emacs integer can hold, this is of +the form (HIGH . LOW): first the high bits, then the low 16 bits. +If even HIGH is too large for an Emacs integer, this is instead +of the form (HIGH MIDDLE . LOW): first the high bits, then the +middle 24 bits, and finally the low 16 bits." + (ntf 10 attributes)) + +(defsubst file-attribute-device-number (attributes) + "The file system device number in ATTRIBUTES returned by `file-attribute'. +If it is larger than what an Emacs integer can hold, this is of +the form (HIGH . LOW): first the high bits, then the low 16 bits. +If even HIGH is too large for an Emacs integer, this is instead +of the form (HIGH MIDDLE . LOW): first the high bits, then the +middle 24 bits, and finally the low 16 bits." + (ntf 11 attributes)) + (define-key ctl-x-map "\C-f" 'find-file) (define-key ctl-x-map "\C-r" 'find-file-read-only) diff --git a/src/dired.c b/src/dired.c index 97fefaefffd..fd5f142d0b5 100644 --- a/src/dired.c +++ b/src/dired.c @@ -861,6 +861,14 @@ 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.