From unknown Wed Sep 10 09:37:43 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#4638 <4638@debbugs.gnu.org> To: bug#4638 <4638@debbugs.gnu.org> Subject: Status: 23.1; doc string and Elisp manual descriptions of file-attributes Reply-To: bug#4638 <4638@debbugs.gnu.org> Date: Wed, 10 Sep 2025 16:37:43 +0000 retitle 4638 23.1; doc string and Elisp manual descriptions of file-attribu= tes reassign 4638 emacs submitter 4638 "Drew Adams" severity 4638 normal thanks From drew.adams@oracle.com Sun Oct 4 17:58:44 2009 Received: (at submit) by emacsbugs.donarmstrong.com; 5 Oct 2009 00:58:44 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.4 required=4.0 tests=AWL,FOURLA autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n950whOs000542 for ; Sun, 4 Oct 2009 17:58:44 -0700 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MubuV-0001T5-1o for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 20:58:43 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MubuP-0001St-IH for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 20:58:41 -0400 Received: from [199.232.76.173] (port=52759 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MubuP-0001Sq-E6 for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 20:58:37 -0400 Received: from rcsinet11.oracle.com ([148.87.113.123]:40383 helo=rgminet11.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MubuO-00089p-RD for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 20:58:37 -0400 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rgminet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n950xdpD015769 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 5 Oct 2009 00:59:40 GMT Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n94NXKmu013142 for ; Mon, 5 Oct 2009 00:59:18 GMT Received: from abhmt021.oracle.com by acsmt355.oracle.com with ESMTP id 20193103071254704284; Sun, 04 Oct 2009 17:58:04 -0700 Received: from dradamslap1 (/24.5.184.158) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 04 Oct 2009 17:58:04 -0700 From: "Drew Adams" To: Subject: 23.1; doc string and Elisp manual descriptions of file-attributes Date: Sun, 4 Oct 2009 17:58:15 -0700 Message-ID: <1ECFBF8A2C4348C3B763D29276A04BC5@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcpFVuu8NRWvDEVKT32s8PpsR5RcFA== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: acsmt356.oracle.com [141.146.40.156] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090201.4AC944B7.00E9:SCFMA4539814,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) >From the doc string: 1. Number of links to file. Please state that it is an integer value. 2. File uid as a string or a number. If a string value cannot be looked up, a numeric value, either an integer or a float, is returned. Can we say how long the string is (fixed length or max)? 10. inode number. If inode number is larger than the Emacs integer... Should presumably say "than the _largest_ Emacs integer". Also, #10 contradicts what is said in the Elisp manual, node `File Attributes'. Which is correct? The doc string speaks of a cons cell containing possibly 3 integers. (And how can a single cons cell contain 3 integers? Not clear.) The manual speaks of a (single) cons cell with car and cdr integers. 11. Device number. If it is larger than the Emacs integer, this is a cons cell, similar to the inode number. Again, it should presumably say _largest_ Emacs integer. Also, it's not clear what "device number" means, and the Elisp manual describes this differently, as "the file system number of the file system that the file is in". Neither description is understandable, but they especially do not seem to correspond, at least not in a self-evident way. These desciptions need to be improved, at the very least by referring to the original terminology (UNIX) or reference. The following note is referenced only from #4, but #5 and #6 say "likewise". The note speaks of "access time". It is not clear whether the note applies only to #4 (access time) or also to #5 and #6. If it applies only to #4, then it should just be moved to #4. Otherwise, things should be rephrased to make clear what is meant (not necessarily access time). On some FAT-based filesystems, only the date of last access is recorded, so last access time will always be midnight of that day. It is important to get these descriptions right. How can we expect someone to write code that depends on these values, if s?he cannot even know what forms they can take? In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600) of 2009-07-29 on SOFT-MJASON Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (4.4)' From drew.adams@oracle.com Sun Oct 4 18:13:24 2009 Received: (at submit) by emacsbugs.donarmstrong.com; 5 Oct 2009 01:13:24 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-3.9 required=4.0 tests=AWL,HAS_BUG_NUMBER autolearn=unavailable version=3.2.5-bugs.debian.org_2005_01_02 Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n951DNqI003841 for ; Sun, 4 Oct 2009 18:13:24 -0700 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Muc8g-0005jb-He for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 21:13:22 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Muc8b-0005dE-Cp for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 21:13:21 -0400 Received: from [199.232.76.173] (port=43426 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Muc8b-0005d0-8U for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 21:13:17 -0400 Received: from acsinet12.oracle.com ([141.146.126.234]:43190) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1Muc8a-0001jR-VT for bug-gnu-emacs@gnu.org; Sun, 04 Oct 2009 21:13:17 -0400 Received: from rgminet13.oracle.com (rcsinet13.oracle.com [148.87.113.125]) by acsinet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n951Ba2I026697 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 5 Oct 2009 01:11:38 GMT Received: from acsmt355.oracle.com (acsmt355.oracle.com [141.146.40.155]) by rgminet13.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n94LxHap003389; Mon, 5 Oct 2009 01:13:36 GMT Received: from abhmt016.oracle.com by acsmt356.oracle.com with ESMTP id 20192431181254705157; Sun, 04 Oct 2009 18:12:37 -0700 Received: from dradamslap1 (/24.5.184.158) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 04 Oct 2009 18:12:36 -0700 From: "Drew Adams" To: <4638@debbugs.gnu.org>, References: <1ECFBF8A2C4348C3B763D29276A04BC5@us.oracle.com> Subject: RE: bug#4638: 23.1;doc string and Elisp manual descriptions of file-attributes Date: Sun, 4 Oct 2009 18:12:48 -0700 Message-ID: <669A019D2D1843FABD0C17D5463FF918@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <1ECFBF8A2C4348C3B763D29276A04BC5@us.oracle.com> Thread-Index: AcpFVuu8NRWvDEVKT32s8PpsR5RcFAAAafHA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: acsmt355.oracle.com [141.146.40.155] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090206.4AC94821.0081:SCFMA4539814,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) I forgot to mention that #6 is unclear in both doc string and manual: What does "status change" mean? Does it mean change of mode (rwx), owner, group,...? From eliz@gnu.org Mon Oct 5 01:49:14 2009 Received: (at 4638-done) by emacsbugs.donarmstrong.com; 5 Oct 2009 08:49:14 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-4.7 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mtaout3.012.net.il (mtaout4.012.net.il [84.95.2.10]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n958nC0w016476 for <4638-done@emacsbugs.donarmstrong.com>; Mon, 5 Oct 2009 01:49:13 -0700 Received: from conversion-daemon.i_mtaout3.012.net.il by i_mtaout3.012.net.il (HyperSendmail v2004.12) id <0KR1005009O4QB00@i_mtaout3.012.net.il> for 4638-done@emacsbugs.donarmstrong.com; Mon, 05 Oct 2009 10:49:05 +0200 (IST) Received: from HOME-C4E4A596F7 ([84.229.44.55]) by i_mtaout3.012.net.il (HyperSendmail v2004.12) with ESMTPA id <0KR1004YY9TT4E00@i_mtaout3.012.net.il>; Mon, 05 Oct 2009 10:49:05 +0200 (IST) Date: Mon, 05 Oct 2009 10:47:03 +0200 From: Eli Zaretskii Subject: Re: bug#4638: 23.1; doc string and Elisp manual descriptions of file-attributes In-reply-to: <1ECFBF8A2C4348C3B763D29276A04BC5@us.oracle.com> X-012-Sender: halo1@inter.net.il To: Drew Adams , 4638-done@debbugs.gnu.org Reply-to: Eli Zaretskii Message-id: <83ocomns6w.fsf@gnu.org> References: <1ECFBF8A2C4348C3B763D29276A04BC5@us.oracle.com> > From: "Drew Adams" > Date: Sun, 4 Oct 2009 17:58:15 -0700 > Cc: > > From the doc string: > > 1. Number of links to file. > > Please state that it is an integer value. I don't think this is important. A "number" means what `numberp' will return non-nil for. Stating that it's an integer is a maintenance burden, because, like other attributes in this function, it may evolve from an integer to a float. (Other attributes in the doc say specifically that they can be floats because in the past the doc string stated they are integers.) > 2. File uid as a string or a number. If a string value cannot be > looked up, a numeric value, either an integer or a float, is > returned. > > Can we say how long the string is (fixed length or max)? There's no limit, as far as Emacs is concerned (except that every string is inherently limited by the size of an Emacs integer), so no, we can't state any useful limitation. > 10. inode number. If inode number is larger than the Emacs integer... > > Should presumably say "than the _largest_ Emacs integer". Changed this to say "is larger than what Emacs integer can hold". > Also, #10 contradicts what is said in the Elisp manual, node `File > Attributes'. Which is correct? The doc string speaks of a cons cell > containing possibly 3 integers. The manual speaks of a (single) cons > cell with car and cdr integers. The manual is wrong, I fixed it. > (And how can a single cons cell contain 3 integers? Not clear.) "M-: (cons 'a (cons 'b 'c)) RET" Anyway, I changed the text not to use ``cons cell'' in this case. > 11. Device number. If it is larger than the Emacs integer, this is > a cons cell, similar to the inode number. > > Again, it should presumably say _largest_ Emacs integer. > > Also, it's not clear what "device number" means, and the Elisp manual > describes this differently, as "the file system number of the file > system that the file is in". Neither description is understandable, > but they especially do not seem to correspond, at least not in a > self-evident way. These desciptions need to be improved, at the very > least by referring to the original terminology (UNIX) or reference. The doc string now says 11. Filesystem device number. If it is larger than what the Emacs integer can hold, this is a cons cell, similar to the inode number. A more detailed description already existed in the manual. I don't think the Unix terminology will help here, btw, because we want this documentation to be as system independent as possible, and the Unix meaning is wrong on Windows. The important part is this: On most filesystems, the combination of the inode and the device number uniquely identifies the file. which I added to the doc string (it was already in the manual, albeit in slightly different wording). > The following note is referenced only from #4, but #5 and #6 say > "likewise". The note speaks of "access time". It is not clear whether > the note applies only to #4 (access time) or also to #5 and #6. If it > applies only to #4, then it should just be moved to #4. Otherwise, > things should be rephrased to make clear what is meant (not > necessarily access time). > > On some FAT-based filesystems, only the date of last > access is recorded, so last access time will always be > midnight of that day. It applies only to the last access time. The note now says (See a note below about access time on FAT-based filesystems.) I don't think it's a good idea to have the note right at #4 because this is an obscure misfeature of an old DOS/Windows filesystem, so it should be near the end of the doc string. > What does "status change" mean? Does it mean change of mode (rwx), > owner, group,...? I hope this new text is more clear: 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. > How can we expect someone to write code that depends on these > values, if s?he cannot even know what forms they can take? I don't think the situation was quite that bad, and I hope it is better now. From drew.adams@oracle.com Mon Oct 5 07:27:35 2009 Received: (at 4638-done) by emacsbugs.donarmstrong.com; 5 Oct 2009 14:27:36 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-3.9 required=4.0 tests=AWL,FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from acsinet11.oracle.com (acsinet11.oracle.com [141.146.126.233]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n95ERXav010161 for <4638-done@emacsbugs.donarmstrong.com>; Mon, 5 Oct 2009 07:27:35 -0700 Received: from rgminet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by acsinet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n95ERbKC019005 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 5 Oct 2009 14:27:38 GMT Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by rgminet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n94MNEsM014286; Mon, 5 Oct 2009 14:27:25 GMT Received: from abhmt012.oracle.com by acsmt358.oracle.com with ESMTP id 20204259371254752842; Mon, 05 Oct 2009 09:27:22 -0500 Received: from dradamslap1 (/24.5.184.158) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 05 Oct 2009 07:27:22 -0700 From: "Drew Adams" To: "'Eli Zaretskii'" , <4638-done@debbugs.gnu.org> References: <1ECFBF8A2C4348C3B763D29276A04BC5@us.oracle.com> <83ocomns6w.fsf@gnu.org> Subject: RE: bug#4638: 23.1; doc string and Elisp manual descriptions of file-attributes Date: Mon, 5 Oct 2009 07:27:36 -0700 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcpFmLSN8yYMDwq7SWKPNFitQS7ITwALpqnQ In-Reply-To: <83ocomns6w.fsf@gnu.org> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 X-Source-IP: acsmt357.oracle.com [141.146.40.157] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090208.4ACA024D.010B:SCFMA4539814,ss=1,fgs=0 > > 1. Number of links to file. > > > > Please state that it is an integer value. > > I don't think this is important. A "number" means what `numberp' will > return non-nil for. Stating that it's an integer is a maintenance > burden, because, like other attributes in this function, it may evolve > from an integer to a float. (Other attributes in the doc say > specifically that they can be floats because in the past the doc > string stated they are integers.) OK. > > 2. File uid as a string or a number. If a string value cannot be > > looked up, a numeric value, either an integer or a float, is > > returned. > > > > Can we say how long the string is (fixed length or max)? > > There's no limit, as far as Emacs is concerned (except that every > string is inherently limited by the size of an Emacs integer), so no, > we can't state any useful limitation. OK. > > 10. inode number. If inode number is larger than the > Emacs integer... > > > > Should presumably say "than the _largest_ Emacs integer". > > Changed this to say "is larger than what Emacs integer can hold". OK. > > Also, #10 contradicts what is said in the Elisp manual, node `File > > Attributes'. Which is correct? The doc string speaks of a cons cell > > containing possibly 3 integers. The manual speaks of a (single) cons > > cell with car and cdr integers. > > The manual is wrong, I fixed it. Thx. > > (And how can a single cons cell contain 3 integers? Not clear.) > > "M-: (cons 'a (cons 'b 'c)) RET" That's two cons cells. > Anyway, I changed the text not to use ``cons cell'' in this case. OK. > > 11. Device number. If it is larger than the Emacs integer, this is > > a cons cell, similar to the inode number. > > > > Again, it should presumably say _largest_ Emacs integer. > > > > Also, it's not clear what "device number" means, and the > Elisp manual > > describes this differently, as "the file system number of the file > > system that the file is in". Neither description is understandable, > > but they especially do not seem to correspond, at least not in a > > self-evident way. These desciptions need to be improved, at the very > > least by referring to the original terminology (UNIX) or reference. > > The doc string now says > > 11. Filesystem device number. If it is larger than what the Emacs > integer can hold, this is a cons cell, similar to the > inode number. OK. > A more detailed description already existed in the manual. I don't > think the Unix terminology will help here, btw, because we want this > documentation to be as system independent as possible, and the Unix > meaning is wrong on Windows. The important part is this: > > On most filesystems, the combination of the inode and the device > number uniquely identifies the file. > > which I added to the doc string (it was already in the manual, albeit > in slightly different wording). Good. > > The following note is referenced only from #4, but #5 and #6 say > > "likewise". The note speaks of "access time". It is not > clear whether > > the note applies only to #4 (access time) or also to #5 and > #6. If it > > applies only to #4, then it should just be moved to #4. Otherwise, > > things should be rephrased to make clear what is meant (not > > necessarily access time). > > > > On some FAT-based filesystems, only the date of last > > access is recorded, so last access time will always be > > midnight of that day. > > It applies only to the last access time. The note now says > > (See a note below about access time on FAT-based filesystems.) OK. > I don't think it's a good idea to have the note right at #4 because > this is an obscure misfeature of an old DOS/Windows filesystem, so > it should be near the end of the doc string. OK. > > What does "status change" mean? Does it mean change of mode (rwx), > > owner, group,...? > > I hope this new text is more clear: > > 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. Good. > > How can we expect someone to write code that depends on these > > values, if s?he cannot even know what forms they can take? > > I don't think the situation was quite that bad, and I hope it is > better now. Thanks. From unknown Wed Sep 10 09:37:43 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Mon, 02 Nov 2009 15:24:13 +0000 User-Agent: Fakemail v42.6.9 # A New Hope # A long time ago, in a galaxy far, far away # something happened. # # Magically this resulted in the following # action being taken, but this fake control # message doesn't tell you why it happened # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator