* Improving inode number documentation
@ 2025-05-25 10:33 Pali Rohár
2025-05-25 23:30 ` Alejandro Colomar
0 siblings, 1 reply; 24+ messages in thread
From: Pali Rohár @ 2025-05-25 10:33 UTC (permalink / raw)
To: Alejandro Colomar, linux-man
Hello Alex,
I would like to ask you, could you improve documentation about inode
numbers returned by readdir()/getdents() and stat()/statx() functions?
https://man7.org/linux/man-pages/man3/readdir.3.html
https://man7.org/linux/man-pages/man2/readdir.2.html
https://man7.org/linux/man-pages/man2/getdents.2.html
https://man7.org/linux/man-pages/man2/stat.2.html
https://man7.org/linux/man-pages/man2/statx.2.html
https://man7.org/linux/man-pages/man3/stat.3type.html
https://man7.org/linux/man-pages/man7/inode.7.html
The missing information in those documentations is the fact that the
dirent.d_ino does not have to be same as stat.st_ino/statx.stx_ino for
the same file or dir.
stat.st_ino number belongs to the stat.st_dev but dirent.d_ino belongs
to the st_dev of the directory on which was called opendir().
So for the mount points these two numbers are different. readdir()
returns the inode number of the underlying directory (which belongs to
the parent filesystem), but the stat() returns the inode number of the
root directory of the upper/mounted filesystem.
And I think same applies for mount-binded files, not just for mounted
directories.
Note that this Linux behavior (when readdir and stat returns different
inode numbers) is in POSIX readdir() specification called "historical"
and is described in RATIONALE section of POSIX readdir:
https://pubs.opengroup.org/onlinepubs/9799919799/functions/readdir.html
Therefore it would be nice to mention the fact in Linux readdir(3)
documentation, that Linux conforms to POSIX "historical implementation".
Pali
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Improving inode number documentation
2025-05-25 10:33 Improving inode number documentation Pali Rohár
@ 2025-05-25 23:30 ` Alejandro Colomar
2025-05-28 18:25 ` Pali Rohár
0 siblings, 1 reply; 24+ messages in thread
From: Alejandro Colomar @ 2025-05-25 23:30 UTC (permalink / raw)
To: Pali Rohár; +Cc: linux-man
[-- Attachment #1: Type: text/plain, Size: 2091 bytes --]
Hi Pali!
On Sun, May 25, 2025 at 12:33:44PM +0200, Pali Rohár wrote:
> Hello Alex,
>
> I would like to ask you, could you improve documentation about inode
> numbers returned by readdir()/getdents() and stat()/statx() functions?
I'd love to do that. I do not feel experienced enough in this matter to
write the text myself, but I could try to learn about it. On the other
hand, if you want to send patches yourself, we can go much faster.
Would you mind sending some patches?
Have a lovely night!
Alex
> https://man7.org/linux/man-pages/man3/readdir.3.html
> https://man7.org/linux/man-pages/man2/readdir.2.html
> https://man7.org/linux/man-pages/man2/getdents.2.html
> https://man7.org/linux/man-pages/man2/stat.2.html
> https://man7.org/linux/man-pages/man2/statx.2.html
> https://man7.org/linux/man-pages/man3/stat.3type.html
> https://man7.org/linux/man-pages/man7/inode.7.html
>
> The missing information in those documentations is the fact that the
> dirent.d_ino does not have to be same as stat.st_ino/statx.stx_ino for
> the same file or dir.
>
> stat.st_ino number belongs to the stat.st_dev but dirent.d_ino belongs
> to the st_dev of the directory on which was called opendir().
>
> So for the mount points these two numbers are different. readdir()
> returns the inode number of the underlying directory (which belongs to
> the parent filesystem), but the stat() returns the inode number of the
> root directory of the upper/mounted filesystem.
>
> And I think same applies for mount-binded files, not just for mounted
> directories.
>
> Note that this Linux behavior (when readdir and stat returns different
> inode numbers) is in POSIX readdir() specification called "historical"
> and is described in RATIONALE section of POSIX readdir:
> https://pubs.opengroup.org/onlinepubs/9799919799/functions/readdir.html
>
> Therefore it would be nice to mention the fact in Linux readdir(3)
> documentation, that Linux conforms to POSIX "historical implementation".
>
> Pali
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Improving inode number documentation
2025-05-25 23:30 ` Alejandro Colomar
@ 2025-05-28 18:25 ` Pali Rohár
2025-05-28 19:03 ` Alejandro Colomar
0 siblings, 1 reply; 24+ messages in thread
From: Pali Rohár @ 2025-05-28 18:25 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man
Hello!
On Monday 26 May 2025 01:30:43 Alejandro Colomar wrote:
> Hi Pali!
>
> On Sun, May 25, 2025 at 12:33:44PM +0200, Pali Rohár wrote:
> > Hello Alex,
> >
> > I would like to ask you, could you improve documentation about inode
> > numbers returned by readdir()/getdents() and stat()/statx() functions?
>
> I'd love to do that. I do not feel experienced enough in this matter to
> write the text myself, but I could try to learn about it. On the other
> hand, if you want to send patches yourself, we can go much faster.
> Would you mind sending some patches?
Well, as it affects at least 7 man pages, I do not know how such
information should be ideally structured. Whether to be described just
in the readdir(3) and referenced from all others. Or split across all of
them. So I do not think that I'm the one who can prepare patches.
But I will try at least to propose how the changes could look like:
readdir(3) change:
d_ino - This is the inode number of the directory entry, which belongs
to the filesystem st_dev of the directory on which was readdir() called.
If the directory entry is the mount point then the d_ino differs from
the stat's st_ino. d_ino is the inode number of the underlying mount
point, rather than of the inode number of mounted file system. According
to POSIX this Linux behavior is considered to be a bug but conforms as
"historical implementations".
stat(3type) change:
st_ino - This field contains the file's inode number, which belongs to
the st_dev. If the stat() was called on the mount point then st_ino
differs from the readdir's d_ino. st_ino contains the inode number of
mounted file system, whether readdir's d_ino contains the inode number
of the underlying mount point.
So I suggest if somebody else look at it and prepare improvements
including how should be this information structured.
>
> Have a lovely night!
> Alex
>
> > https://man7.org/linux/man-pages/man3/readdir.3.html
> > https://man7.org/linux/man-pages/man2/readdir.2.html
> > https://man7.org/linux/man-pages/man2/getdents.2.html
> > https://man7.org/linux/man-pages/man2/stat.2.html
> > https://man7.org/linux/man-pages/man2/statx.2.html
> > https://man7.org/linux/man-pages/man3/stat.3type.html
> > https://man7.org/linux/man-pages/man7/inode.7.html
> >
> > The missing information in those documentations is the fact that the
> > dirent.d_ino does not have to be same as stat.st_ino/statx.stx_ino for
> > the same file or dir.
> >
> > stat.st_ino number belongs to the stat.st_dev but dirent.d_ino belongs
> > to the st_dev of the directory on which was called opendir().
> >
> > So for the mount points these two numbers are different. readdir()
> > returns the inode number of the underlying directory (which belongs to
> > the parent filesystem), but the stat() returns the inode number of the
> > root directory of the upper/mounted filesystem.
> >
> > And I think same applies for mount-binded files, not just for mounted
> > directories.
> >
> > Note that this Linux behavior (when readdir and stat returns different
> > inode numbers) is in POSIX readdir() specification called "historical"
> > and is described in RATIONALE section of POSIX readdir:
> > https://pubs.opengroup.org/onlinepubs/9799919799/functions/readdir.html
> >
> > Therefore it would be nice to mention the fact in Linux readdir(3)
> > documentation, that Linux conforms to POSIX "historical implementation".
> >
> > Pali
>
> --
> <https://www.alejandro-colomar.es/>
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Improving inode number documentation
2025-05-28 18:25 ` Pali Rohár
@ 2025-05-28 19:03 ` Alejandro Colomar
2025-05-28 19:41 ` Pali Rohár
0 siblings, 1 reply; 24+ messages in thread
From: Alejandro Colomar @ 2025-05-28 19:03 UTC (permalink / raw)
To: Pali Rohár; +Cc: linux-man
[-- Attachment #1: Type: text/plain, Size: 4543 bytes --]
Hi Pali!
On Wed, May 28, 2025 at 08:25:19PM +0200, Pali Rohár wrote:
> > > I would like to ask you, could you improve documentation about inode
> > > numbers returned by readdir()/getdents() and stat()/statx() functions?
> >
> > I'd love to do that. I do not feel experienced enough in this matter to
> > write the text myself, but I could try to learn about it. On the other
> > hand, if you want to send patches yourself, we can go much faster.
> > Would you mind sending some patches?
>
> Well, as it affects at least 7 man pages, I do not know how such
> information should be ideally structured. Whether to be described just
> in the readdir(3) and referenced from all others. Or split across all of
> them. So I do not think that I'm the one who can prepare patches.
>
> But I will try at least to propose how the changes could look like:
>
> readdir(3) change:
>
> d_ino - This is the inode number of the directory entry, which belongs
> to the filesystem st_dev of the directory on which was readdir() called.
> If the directory entry is the mount point then the d_ino differs from
> the stat's st_ino. d_ino is the inode number of the underlying mount
> point, rather than of the inode number of mounted file system.
I guess the last sentence applies only as a clarification of the
previous one, right? If so, I'd separate the sentences with ':' instead
of '.'.
> According
> to POSIX this Linux behavior is considered to be a bug but conforms as
> "historical implementations".
>
> stat(3type) change:
>
> st_ino - This field contains the file's inode number, which belongs to
> the st_dev. If the stat() was called on the mount point then st_ino
> differs from the readdir's d_ino. st_ino contains the inode number of
> mounted file system, whether readdir's d_ino contains the inode number
> of the underlying mount point.
These two paragraphs in two pages sound reasonable. I've prepared a
patch, and pushed a new branch to the git repo where we can continue
working on it.
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=ino>
>
> So I suggest if somebody else look at it and prepare improvements
> including how should be this information structured.
Here's the change I propose based on your suggestions:
commit c27a2d7f80c7824918abe5958be6b5eb2dbe8278 (HEAD -> ino, korg/ino)
Author: Alejandro Colomar <alx@kernel.org>
Date: Wed May 28 20:59:11 2025 +0200
man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
Suggested-by: Pali Rohár <pali@kernel.org>
Co-authored-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
index b9150160b..ad9c76595 100644
--- a/man/man3/readdir.3
+++ b/man/man3/readdir.3
@@ -58,7 +58,27 @@ .SH DESCRIPTION
structure are as follows:
.TP
.I .d_ino
-This is the inode number of the file.
+This is the inode number of the file,
+which belongs to the filesystem
+.I .st_dev
+(see
+.BR stat (3type))
+of the directory on which
+.BR readdir ()
+was called.
+If the directory entry is the mount point,
+then
+.I .d_ino
+differs from
+.IR .st_ino :
+.I .d_ino
+is the inode number of the underlying mount point,
+while
+.I .st_ino
+is the inode number of the mounted file system.
+According to POSIX,
+this Linux behavior is considered to be a bug,
+but is nevertheless conforming.
.TP
.I .d_off
The value returned in
diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
index ee801bcec..835626775 100644
--- a/man/man3type/stat.3type
+++ b/man/man3type/stat.3type
@@ -66,7 +66,21 @@ .SH DESCRIPTION
macros may be useful to decompose the device ID in this field.)
.TP
.I .st_ino
-This field contains the file's inode number.
+This field contains the file's inode number,
+which belongs to the
+.IR .st_dev .
+If
+.BR stat (2)
+was called on the mount point,
+then
+.I .d_ino
+differs from
+.IR .st_ino :
+.I .d_ino
+is the inode number of the underlying mount point,
+while
+.I .st_ino
+is the inode number of the mounted file system.
.TP
.I .st_mode
This field contains the file type and mode.
Does it look good to you? Would you do anything else? Please sign the
patch if it looks good to you.
Have a lovely day!
Alex
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Improving inode number documentation
2025-05-28 19:03 ` Alejandro Colomar
@ 2025-05-28 19:41 ` Pali Rohár
2025-05-28 19:59 ` Alejandro Colomar
0 siblings, 1 reply; 24+ messages in thread
From: Pali Rohár @ 2025-05-28 19:41 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man
On Wednesday 28 May 2025 21:03:04 Alejandro Colomar wrote:
> Hi Pali!
>
> On Wed, May 28, 2025 at 08:25:19PM +0200, Pali Rohár wrote:
> > > > I would like to ask you, could you improve documentation about inode
> > > > numbers returned by readdir()/getdents() and stat()/statx() functions?
> > >
> > > I'd love to do that. I do not feel experienced enough in this matter to
> > > write the text myself, but I could try to learn about it. On the other
> > > hand, if you want to send patches yourself, we can go much faster.
> > > Would you mind sending some patches?
> >
> > Well, as it affects at least 7 man pages, I do not know how such
> > information should be ideally structured. Whether to be described just
> > in the readdir(3) and referenced from all others. Or split across all of
> > them. So I do not think that I'm the one who can prepare patches.
> >
> > But I will try at least to propose how the changes could look like:
> >
> > readdir(3) change:
> >
> > d_ino - This is the inode number of the directory entry, which belongs
> > to the filesystem st_dev of the directory on which was readdir() called.
> > If the directory entry is the mount point then the d_ino differs from
> > the stat's st_ino. d_ino is the inode number of the underlying mount
> > point, rather than of the inode number of mounted file system.
>
> I guess the last sentence applies only as a clarification of the
> previous one, right? If so, I'd separate the sentences with ':' instead
> of '.'.
Yes, it is a clarification.
> > According
> > to POSIX this Linux behavior is considered to be a bug but conforms as
> > "historical implementations".
> >
> > stat(3type) change:
> >
> > st_ino - This field contains the file's inode number, which belongs to
> > the st_dev. If the stat() was called on the mount point then st_ino
> > differs from the readdir's d_ino. st_ino contains the inode number of
> > mounted file system, whether readdir's d_ino contains the inode number
> > of the underlying mount point.
>
> These two paragraphs in two pages sound reasonable. I've prepared a
> patch, and pushed a new branch to the git repo where we can continue
> working on it.
>
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=ino>
>
>
> >
> > So I suggest if somebody else look at it and prepare improvements
> > including how should be this information structured.
>
> Here's the change I propose based on your suggestions:
> ...
>
> Does it look good to you? Would you do anything else? Please sign the
> patch if it looks good to you.
>
>
> Have a lovely day!
> Alex
>
> --
> <https://www.alejandro-colomar.es/>
As I said I'm not feeling comfortable with it. So I would really like if
somebody else ideally more skilled recheck it and improve it. Maybe
asking linux-fsdevel for help?
What is missing updating also the statx information (because this is
also syscall which returns inode number) and updating also readdir(2)
and getdents(2). In the first email I sent list of manpages which are
affected. It could be quite surprising for people reading documentation
why old stat syscall has something regarding to inodes and new statx
syscall does not have.
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: Improving inode number documentation
2025-05-28 19:41 ` Pali Rohár
@ 2025-05-28 19:59 ` Alejandro Colomar
2025-05-28 21:31 ` [RFC v1] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino Alejandro Colomar
` (2 more replies)
0 siblings, 3 replies; 24+ messages in thread
From: Alejandro Colomar @ 2025-05-28 19:59 UTC (permalink / raw)
To: Pali Rohár; +Cc: linux-man, linux-fsdevel
[-- Attachment #1: Type: text/plain, Size: 4092 bytes --]
[CC += linux-fsdevel@]
Hi Pali,
On Wed, May 28, 2025 at 09:41:05PM +0200, Pali Rohár wrote:
> On Wednesday 28 May 2025 21:03:04 Alejandro Colomar wrote:
> > Hi Pali!
> >
> > On Wed, May 28, 2025 at 08:25:19PM +0200, Pali Rohár wrote:
> > > > > I would like to ask you, could you improve documentation about inode
> > > > > numbers returned by readdir()/getdents() and stat()/statx() functions?
> > > >
> > > > I'd love to do that. I do not feel experienced enough in this matter to
> > > > write the text myself, but I could try to learn about it. On the other
> > > > hand, if you want to send patches yourself, we can go much faster.
> > > > Would you mind sending some patches?
> > >
> > > Well, as it affects at least 7 man pages, I do not know how such
> > > information should be ideally structured. Whether to be described just
> > > in the readdir(3) and referenced from all others. Or split across all of
> > > them. So I do not think that I'm the one who can prepare patches.
> > >
> > > But I will try at least to propose how the changes could look like:
> > >
> > > readdir(3) change:
> > >
> > > d_ino - This is the inode number of the directory entry, which belongs
> > > to the filesystem st_dev of the directory on which was readdir() called.
> > > If the directory entry is the mount point then the d_ino differs from
> > > the stat's st_ino. d_ino is the inode number of the underlying mount
> > > point, rather than of the inode number of mounted file system.
> >
> > I guess the last sentence applies only as a clarification of the
> > previous one, right? If so, I'd separate the sentences with ':' instead
> > of '.'.
>
> Yes, it is a clarification.
>
> > > According
> > > to POSIX this Linux behavior is considered to be a bug but conforms as
> > > "historical implementations".
> > >
> > > stat(3type) change:
> > >
> > > st_ino - This field contains the file's inode number, which belongs to
> > > the st_dev. If the stat() was called on the mount point then st_ino
> > > differs from the readdir's d_ino. st_ino contains the inode number of
> > > mounted file system, whether readdir's d_ino contains the inode number
> > > of the underlying mount point.
> >
> > These two paragraphs in two pages sound reasonable. I've prepared a
> > patch, and pushed a new branch to the git repo where we can continue
> > working on it.
> >
> > <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=ino>
> >
> >
> > >
> > > So I suggest if somebody else look at it and prepare improvements
> > > including how should be this information structured.
> >
> > Here's the change I propose based on your suggestions:
> > ...
> >
> > Does it look good to you? Would you do anything else? Please sign the
> > patch if it looks good to you.
> >
> >
> > Have a lovely day!
> > Alex
> >
> > --
> > <https://www.alejandro-colomar.es/>
>
> As I said I'm not feeling comfortable with it. So I would really like if
> somebody else ideally more skilled recheck it and improve it. Maybe
> asking linux-fsdevel for help?
Sure, let's add them to CC. I will send the patches as a response to
this thread, so that they can comment. The full thread of this
discussion can be found at
<https://lore.kernel.org/linux-man/20250528194105.dqc2bgfck6n3xfya@pali/T/#t>.
>
> What is missing updating also the statx information (because this is
> also syscall which returns inode number) and updating also readdir(2)
> and getdents(2). In the first email I sent list of manpages which are
> affected. It could be quite surprising for people reading documentation
> why old stat syscall has something regarding to inodes and new statx
> syscall does not have.
We can improve it incrementally. As long as what we add is correct, we
don't need to make it perfect at once. But I'll keep it in a branch for
now, so we can iterate a bit without committing anything.
Have a lovely night!
Alex
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 24+ messages in thread
* [RFC v1] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-05-28 19:59 ` Alejandro Colomar
@ 2025-05-28 21:31 ` Alejandro Colomar
2025-05-28 22:54 ` G. Branden Robinson
2025-10-28 23:15 ` [PATCH v2] " Alejandro Colomar
2025-10-31 10:44 ` [PATCH v3] " Alejandro Colomar
2 siblings, 1 reply; 24+ messages in thread
From: Alejandro Colomar @ 2025-05-28 21:31 UTC (permalink / raw)
To: linux-man; +Cc: Alejandro Colomar, linux-fsdevel, Pali Rohár
Suggested-by: Pali Rohár <pali@kernel.org>
Co-authored-by: Pali Rohár <pali@kernel.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
man/man3/readdir.3 | 22 +++++++++++++++++++++-
man/man3type/stat.3type | 16 +++++++++++++++-
2 files changed, 36 insertions(+), 2 deletions(-)
diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
index b9150160b..ad9c76595 100644
--- a/man/man3/readdir.3
+++ b/man/man3/readdir.3
@@ -58,7 +58,27 @@ .SH DESCRIPTION
structure are as follows:
.TP
.I .d_ino
-This is the inode number of the file.
+This is the inode number of the file,
+which belongs to the filesystem
+.I .st_dev
+(see
+.BR stat (3type))
+of the directory on which
+.BR readdir ()
+was called.
+If the directory entry is the mount point,
+then
+.I .d_ino
+differs from
+.IR .st_ino :
+.I .d_ino
+is the inode number of the underlying mount point,
+while
+.I .st_ino
+is the inode number of the mounted file system.
+According to POSIX,
+this Linux behavior is considered to be a bug,
+but is nevertheless conforming.
.TP
.I .d_off
The value returned in
diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
index ee801bcec..835626775 100644
--- a/man/man3type/stat.3type
+++ b/man/man3type/stat.3type
@@ -66,7 +66,21 @@ .SH DESCRIPTION
macros may be useful to decompose the device ID in this field.)
.TP
.I .st_ino
-This field contains the file's inode number.
+This field contains the file's inode number,
+which belongs to the
+.IR .st_dev .
+If
+.BR stat (2)
+was called on the mount point,
+then
+.I .d_ino
+differs from
+.IR .st_ino :
+.I .d_ino
+is the inode number of the underlying mount point,
+while
+.I .st_ino
+is the inode number of the mounted file system.
.TP
.I .st_mode
This field contains the file type and mode.
Range-diff against v0:
-: --------- > 1: c27a2d7f8 man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
--
2.49.0
^ permalink raw reply related [flat|nested] 24+ messages in thread
* Re: [RFC v1] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-05-28 21:31 ` [RFC v1] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino Alejandro Colomar
@ 2025-05-28 22:54 ` G. Branden Robinson
0 siblings, 0 replies; 24+ messages in thread
From: G. Branden Robinson @ 2025-05-28 22:54 UTC (permalink / raw)
To: linux-man, linux-fsdevel
[-- Attachment #1: Type: text/plain, Size: 2158 bytes --]
At 2025-05-28T23:31:29+0200, Alejandro Colomar wrote:
[snip]
> diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
[snip]
> +If the directory entry is the mount point,
> +then
> +.I .d_ino
> +differs from
> +.IR .st_ino :
> +.I .d_ino
> +is the inode number of the underlying mount point,
> +while
> +.I .st_ino
> +is the inode number of the mounted file system.
> +According to POSIX,
> +this Linux behavior is considered to be a bug,
> +but is nevertheless conforming.
> .TP
> .I .d_off
> The value returned in
Can someone add a *roff comment supporting the claim in the second
sentence? For example, could we have a citation to an Austin Group
mailing list post or a ticket in the group's Mantis bug tracker?
I've followed the Austin Group mailing list for years and, to me, it
sounds uncharacteristic of the POSIX developers to decree an
implementation as "conforming but buggy".
I've checked Draft 4 (the final draft) of the 2024 standard, and see
nothing to support this claim in its dirent.h or readdir() pages.
Typically, if an implementation is "getting away with" something that
the Austin Group finds objectionable, they anticipate and give notice of
a potential change in semantics or of a planned interface removal in the
"Future Directions" sections of their entries.
It's possible I overlooked something. I used text search rather than
reading all 4,101 pages of the standard at a sitting. (I count only 9
total matches for `d_ino`; all are in the aforementioned 2 entries, or
[new to Issue 8] posix_getdents().)
There may be something analogous to the mount point situation in the
case of symbolic links, which the standard _does_ contemplate:
"The value of the [dirent] structure's _d_ino_ member shall be set to
the file serial number of the file named by the _d_name_ member. If the
_d_name_ member names a symbolic link, the value of the _d_ino_ member
shall be set to the file serial number of the symbolic link itself."
(p. 1858, lines 61297-61299)
...which leads me to wonder what an implementation--Linux,
specifically--decides the right thing is when one readdir()s a symbolic
link to a mount point.
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 24+ messages in thread
* [PATCH v2] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-05-28 19:59 ` Alejandro Colomar
2025-05-28 21:31 ` [RFC v1] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino Alejandro Colomar
@ 2025-10-28 23:15 ` Alejandro Colomar
2025-10-28 23:53 ` Pali Rohár
2025-10-30 11:58 ` Jan Kara
2025-10-31 10:44 ` [PATCH v3] " Alejandro Colomar
2 siblings, 2 replies; 24+ messages in thread
From: Alejandro Colomar @ 2025-10-28 23:15 UTC (permalink / raw)
To: linux-man, Jan Kara
Cc: Alejandro Colomar, Pali Rohár, G. Branden Robinson
Suggested-by: Pali Rohár <pali@kernel.org>
Co-authored-by: Pali Rohár <pali@kernel.org>
Cc: "G. Branden Robinson" <branden@debian.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
Hi Jan,
Would you mind reviewing this? The thread started here:
<https://lore.kernel.org/linux-man/20250525103344.fe27ugiytfyoadz5@pali/T/#u>.
Hi Branden,
I wasn't able to do anything after your request from
<https://lore.kernel.org/linux-man/20250525103344.fe27ugiytfyoadz5@pali/T/#m1bd706844fd322b2b0f9090ceac68e7ba29200eb>.
Pali will probably be better placed to do that, since he authored that
text.
Hi Pali,
Sorry for being so slow with this! I wasn't able to work on this until
now.
Have a lovely night!
Alex
man/man3/readdir.3 | 22 +++++++++++++++++++++-
man/man3type/stat.3type | 16 +++++++++++++++-
2 files changed, 36 insertions(+), 2 deletions(-)
diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
index e1c7d2a6a..368e98e6e 100644
--- a/man/man3/readdir.3
+++ b/man/man3/readdir.3
@@ -58,7 +58,27 @@ .SH DESCRIPTION
structure are as follows:
.TP
.I .d_ino
-This is the inode number of the file.
+This is the inode number of the file,
+which belongs to the filesystem
+.I .st_dev
+(see
+.BR stat (3type))
+of the directory on which
+.BR readdir ()
+was called.
+If the directory entry is the mount point,
+then
+.I .d_ino
+differs from
+.IR .st_ino :
+.I .d_ino
+is the inode number of the underlying mount point,
+while
+.I .st_ino
+is the inode number of the mounted file system.
+According to POSIX,
+this Linux behavior is considered to be a bug,
+but is nevertheless conforming.
.TP
.I .d_off
The value returned in
diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
index f3c312bf0..b87195766 100644
--- a/man/man3type/stat.3type
+++ b/man/man3type/stat.3type
@@ -66,7 +66,21 @@ .SH DESCRIPTION
macros may be useful to decompose the device ID in this field.)
.TP
.I .st_ino
-This field contains the file's inode number.
+This field contains the file's inode number,
+which belongs to the
+.IR .st_dev .
+If
+.BR stat (2)
+was called on the mount point,
+then
+.I .d_ino
+differs from
+.IR .st_ino :
+.I .d_ino
+is the inode number of the underlying mount point,
+while
+.I .st_ino
+is the inode number of the mounted file system.
.TP
.I .st_mode
This field contains the file type and mode.
base-commit: abac986a3283e679b6b323f58ab6677bc49a05e0
--
2.51.0
^ permalink raw reply related [flat|nested] 24+ messages in thread
* Re: [PATCH v2] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-10-28 23:15 ` [PATCH v2] " Alejandro Colomar
@ 2025-10-28 23:53 ` Pali Rohár
2025-10-29 7:00 ` G. Branden Robinson
2025-10-30 11:58 ` Jan Kara
1 sibling, 1 reply; 24+ messages in thread
From: Pali Rohár @ 2025-10-28 23:53 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: linux-man, Jan Kara, Alejandro Colomar
On Wednesday 29 October 2025 00:15:31 Alejandro Colomar wrote:
> Hi Jan,
>
> Would you mind reviewing this? The thread started here:
> <https://lore.kernel.org/linux-man/20250525103344.fe27ugiytfyoadz5@pali/T/#u>.
>
> Hi Branden,
>
> I wasn't able to do anything after your request from
> <https://lore.kernel.org/linux-man/20250525103344.fe27ugiytfyoadz5@pali/T/#m1bd706844fd322b2b0f9090ceac68e7ba29200eb>.
> Pali will probably be better placed to do that, since he authored that
> text.
>
> Hi Pali,
>
> Sorry for being so slow with this! I wasn't able to work on this until
> now.
>
>
> Have a lovely night!
> Alex
Hello Branden, I'm sorry but I have not received your message because
I'm not subscribed to the list. Otherwise I would have replied to you
earlier. If you are referring to the "bug" then it is written in
informative part in RATIONALE section of readdir / POSIX.1-2024. I wrote
in my first email in that email thread which Alejandro linked above.
Here is direct link to POSIX spec and below is quoted part:
https://pubs.opengroup.org/onlinepubs/9799919799/functions/readdir.html
"When returning a directory entry for the root of a mounted file system,
some historical implementations of readdir() returned the file serial
number of the underlying mount point, rather than of the root of the
mounted file system. This behavior is considered to be a bug, since the
underlying file serial number has no significance to applications."
That part is in the "informative" section. I have not found anything in
normative sections which would disallow usage of that "historical"
behavior, so my understanding was that "historical" behavior is
conforming too.
Please correct me if I'm wrong here, or if it should be understood in
different way.
Also I have not read all those 4000 pages, so maybe there is something
hidden. It is quite hard to find information about this topic and that
is why I think this should be documented in Linux manpages.
Pali
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v2] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-10-28 23:53 ` Pali Rohár
@ 2025-10-29 7:00 ` G. Branden Robinson
2025-10-29 19:34 ` Pali Rohár
0 siblings, 1 reply; 24+ messages in thread
From: G. Branden Robinson @ 2025-10-29 7:00 UTC (permalink / raw)
To: Pali Rohár; +Cc: linux-man, Jan Kara, Alejandro Colomar
[-- Attachment #1: Type: text/plain, Size: 3977 bytes --]
Hi Pali,
Thanks for following up.
At 2025-10-29T00:53:06+0100, Pali Rohár wrote:
> Hello Branden, I'm sorry but I have not received your message because
> I'm not subscribed to the list. Otherwise I would have replied to you
> earlier.
No worries--it's a risk I take when forgetting to CC people's accounts.
> If you are referring to the "bug" then it is written in informative
> part in RATIONALE section of readdir / POSIX.1-2024. I wrote in my
> first email in that email thread which Alejandro linked above.
>
> Here is direct link to POSIX spec and below is quoted part:
> https://pubs.opengroup.org/onlinepubs/9799919799/functions/readdir.html
>
> "When returning a directory entry for the root of a mounted file
> system, some historical implementations of readdir() returned the file
> serial number of the underlying mount point, rather than of the root
> of the mounted file system. This behavior is considered to be a bug,
> since the underlying file serial number has no significance to
> applications."
Thanks--this is precisely what I was asking for!
> That part is in the "informative" section. I have not found anything
> in normative sections which would disallow usage of that "historical"
> behavior, so my understanding was that "historical" behavior is
> conforming too.
>
> Please correct me if I'm wrong here, or if it should be understood in
> different way.
I can't speak for the Austin Group, but I don't read the text quite the
same way. I interpret it as saying that some historical implementations
of readdir() would _not_ "return a pointer to a structure representing
the directory entry at the current position in the directory stream
specified by the argument dirp, and position the directory stream at the
next entry." But I suspect that's not what it _intends_ to say.
Instead, these implementations "returned [sic] the file serial number of
the underlying mount point", which I interpret to mean that they would
return a pointer to a _dirent_ struct whose _d_ino_ member was not the
file serial number of the file (of directory type) named by the _d_name_
member but a pointer to a _dirent_ struct whose _d_ino_ member was the
file serial number of the underlying mount point.
I think there are two conclusions we can reach here.
1. POSIX.1-2024 might be a little sloppy in the wording of its
"RATIONALE" for this interface. Presumably no historical
implementation's readdir() returned a _d_ino_ number directly.
(Though with all the exuberant integer/pointer punning that used to
go in Unix, I'd wouldn't bet a lot of money that *no* implementation
ever did.) I'll wager a nickel that readdir() has always, on every
implementation, returned a pointer to a _dirent_ struct, and it is
only the value of the _d_ino_ member of the pointed-to struct that
some implementations have populated inconsistently when the entry is
a directory that is a mount point.
If I'm right, this is an example of the common linguistic error of
synecdoche: confusing a container with (a subset of) its contents.
2. The behavior POSIX describes as buggy is, in fact, nonconforming.
> Also I have not read all those 4000 pages, so maybe there is something
> hidden. It is quite hard to find information about this topic and that
> is why I think this should be documented in Linux manpages.
I reckon someone should open a Mantis ticket with the Austin Group's
issue tracker to get clarity on what I characterized as "sloppy"
wording. Either it is and we can get the standard clarified, or I'm
wrong and an authority can point out how. (Maybe both!)
I'm subscribed to the austin-group-l reflector and will take an action
item to file this ticket. I'll try to do within a week. (I have a lot
of old Unix books and would like to rummage around in them for any
documented land mines in this area.)
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v2] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-10-29 7:00 ` G. Branden Robinson
@ 2025-10-29 19:34 ` Pali Rohár
2025-11-21 21:10 ` Pali Rohár
0 siblings, 1 reply; 24+ messages in thread
From: Pali Rohár @ 2025-10-29 19:34 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: linux-man, Jan Kara, Alejandro Colomar
Hello Branden,
On Wednesday 29 October 2025 02:00:39 G. Branden Robinson wrote:
> Hi Pali,
>
> Thanks for following up.
>
> At 2025-10-29T00:53:06+0100, Pali Rohár wrote:
> > Hello Branden, I'm sorry but I have not received your message because
> > I'm not subscribed to the list. Otherwise I would have replied to you
> > earlier.
>
> No worries--it's a risk I take when forgetting to CC people's accounts.
>
> > If you are referring to the "bug" then it is written in informative
> > part in RATIONALE section of readdir / POSIX.1-2024. I wrote in my
> > first email in that email thread which Alejandro linked above.
> >
> > Here is direct link to POSIX spec and below is quoted part:
> > https://pubs.opengroup.org/onlinepubs/9799919799/functions/readdir.html
> >
> > "When returning a directory entry for the root of a mounted file
> > system, some historical implementations of readdir() returned the file
> > serial number of the underlying mount point, rather than of the root
> > of the mounted file system. This behavior is considered to be a bug,
> > since the underlying file serial number has no significance to
> > applications."
>
> Thanks--this is precisely what I was asking for!
>
> > That part is in the "informative" section. I have not found anything
> > in normative sections which would disallow usage of that "historical"
> > behavior, so my understanding was that "historical" behavior is
> > conforming too.
> >
> > Please correct me if I'm wrong here, or if it should be understood in
> > different way.
>
> I can't speak for the Austin Group, but I don't read the text quite the
> same way. I interpret it as saying that some historical implementations
> of readdir() would _not_ "return a pointer to a structure representing
> the directory entry at the current position in the directory stream
> specified by the argument dirp, and position the directory stream at the
> next entry." But I suspect that's not what it _intends_ to say.
>
> Instead, these implementations "returned [sic] the file serial number of
> the underlying mount point", which I interpret to mean that they would
> return a pointer to a _dirent_ struct whose _d_ino_ member was not the
> file serial number of the file (of directory type) named by the _d_name_
> member but a pointer to a _dirent_ struct whose _d_ino_ member was the
> file serial number of the underlying mount point.
>
> I think there are two conclusions we can reach here.
>
> 1. POSIX.1-2024 might be a little sloppy in the wording of its
> "RATIONALE" for this interface. Presumably no historical
> implementation's readdir() returned a _d_ino_ number directly.
> (Though with all the exuberant integer/pointer punning that used to
> go in Unix, I'd wouldn't bet a lot of money that *no* implementation
> ever did.) I'll wager a nickel that readdir() has always, on every
> implementation, returned a pointer to a _dirent_ struct, and it is
> only the value of the _d_ino_ member of the pointed-to struct that
> some implementations have populated inconsistently when the entry is
> a directory that is a mount point.
>
> If I'm right, this is an example of the common linguistic error of
> synecdoche: confusing a container with (a subset of) its contents.
>
> 2. The behavior POSIX describes as buggy is, in fact, nonconforming.
Only two? I can image that somebody come up with another conclusion.
(just a joke)
Anyway, I think that it is important to document the existing Linux
behavior and whether it is POSIX-conforming or not is then second step.
We can drop the information about POSIX conformity from manpage until we
figure out how it is.
> > Also I have not read all those 4000 pages, so maybe there is something
> > hidden. It is quite hard to find information about this topic and that
> > is why I think this should be documented in Linux manpages.
>
> I reckon someone should open a Mantis ticket with the Austin Group's
> issue tracker to get clarity on what I characterized as "sloppy"
> wording. Either it is and we can get the standard clarified, or I'm
> wrong and an authority can point out how. (Maybe both!)
>
> I'm subscribed to the austin-group-l reflector and will take an action
> item to file this ticket. I'll try to do within a week. (I have a lot
> of old Unix books and would like to rummage around in them for any
> documented land mines in this area.)
>
> Regards,
> Branden
Thanks for taking that part. It would be really nice if austin group can
clarify how the whole situation is in a non-confusing way.
Anyway, inode number is always connected to the specific mounted
filesystem. So when the application is doing something with inodes, it
always needs a pair (dev_t, ino_t) unless inodes belongs to same fs dev.
readdir() and getdents() returns just ino_t, and without knowledge of
dev_t, applications cannot use returned ino_t for anything useful.
On "historical" implementations, the dev_t can be fetched for example by
one fstat(dir_fd, &st) call as dev_t would be same for all readdir and
getdents entries. But on non-"historical" implementation, it would be
needed to call stat() on every one entry. For example /mnt/ directory
which usually contains just mountpoints, will contain entries where
each one has inode number 2 (common inode number for root of fs).
I looked into archives and I have found that this problem was already
discussed in the past. Here are some email threads from coreutils:
https://lore.kernel.org/lkml/87y6oyhkz8.fsf@meyering.net/t/#u
https://public-inbox.org/bug-coreutils/8763c5wcgn.fsf@meyering.net/t/#u
https://public-inbox.org/bug-coreutils/87iqvi2j0q.fsf@rho.meyering.net/t/#u
https://public-inbox.org/bug-coreutils/87verkborm.fsf@rho.meyering.net/
https://public-inbox.org/bug-coreutils/022320061637.4398.43FDE4D7000110830000112E22007507440A050E040D0C079D0A@comcast.net/
Maybe they could be a good reference for future discussion by austin group.
Just my personal idea: If there would be some xgetdents syscall (like
there statx over stat), it could return both inode numbers with dev_t
and application can take which it wants.
For example, NFS4's readdir can return both inode numbers (depending
what is client asking). NFSv4.1 spec has nicely documented this problem
with UNIX background of mount point crossing:
https://www.rfc-editor.org/rfc/rfc8881.html#section-5.8.2.23
Pali
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v2] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-10-28 23:15 ` [PATCH v2] " Alejandro Colomar
2025-10-28 23:53 ` Pali Rohár
@ 2025-10-30 11:58 ` Jan Kara
1 sibling, 0 replies; 24+ messages in thread
From: Jan Kara @ 2025-10-30 11:58 UTC (permalink / raw)
To: Alejandro Colomar
Cc: linux-man, Jan Kara, Pali Rohár, G. Branden Robinson
On Wed 29-10-25 00:15:31, Alejandro Colomar wrote:
> Suggested-by: Pali Rohár <pali@kernel.org>
> Co-authored-by: Pali Rohár <pali@kernel.org>
> Cc: "G. Branden Robinson" <branden@debian.org>
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
>
> Hi Jan,
>
> Would you mind reviewing this? The thread started here:
> <https://lore.kernel.org/linux-man/20250525103344.fe27ugiytfyoadz5@pali/T/#u>.
The changes look correct to me but the wording is a bit confusing. Let me
try to suggest some improvements.
...
> diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
> index e1c7d2a6a..368e98e6e 100644
> --- a/man/man3/readdir.3
> +++ b/man/man3/readdir.3
> @@ -58,7 +58,27 @@ .SH DESCRIPTION
> structure are as follows:
> .TP
> .I .d_ino
> -This is the inode number of the file.
> +This is the inode number of the file,
> +which belongs to the filesystem
> +.I .st_dev
> +(see
> +.BR stat (3type))
> +of the directory on which
> +.BR readdir ()
> +was called.
> +If the directory entry is the mount point,
> +then
> +.I .d_ino
> +differs from
> +.IR .st_ino :
> +.I .d_ino
> +is the inode number of the underlying mount point,
> +while
> +.I .st_ino
> +is the inode number of the mounted file system.
> +According to POSIX,
> +this Linux behavior is considered to be a bug,
> +but is nevertheless conforming.
I'd suggest:
This is the inode number of the file in the file system containing the
directory on which readdir() was called. If the directory entry is the
mount point, then .d_ino differs from .st_ino returned by stat(3type) on
this file: .d_ino is the inode number of the mount point, while .st_ino is
the inode number of the root directory of the mounted file system.
According to POSIX, this Linux behavior is considered to be a bug, but is
nevertheless conforming.
> diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
> index f3c312bf0..b87195766 100644
> --- a/man/man3type/stat.3type
> +++ b/man/man3type/stat.3type
> @@ -66,7 +66,21 @@ .SH DESCRIPTION
> macros may be useful to decompose the device ID in this field.)
> .TP
> .I .st_ino
> -This field contains the file's inode number.
> +This field contains the file's inode number,
> +which belongs to the
> +.IR .st_dev .
> +If
> +.BR stat (2)
> +was called on the mount point,
> +then
> +.I .d_ino
> +differs from
> +.IR .st_ino :
> +.I .d_ino
> +is the inode number of the underlying mount point,
> +while
> +.I .st_ino
> +is the inode number of the mounted file system.
Here I'd suggest:
This field contains the file's inode number in the file system on .st_dev.
If stat(2) was called on the mount point, then .st_ino differs from .d_ino
returned by readdir(3) for the corresponding directory entry in the parent
directory. In this case .st_ino is the inode number of the root directory
of the mounted file system while .d_ino is the inode number of the mount
point in the parent file system.
Honza
--
Jan Kara <jack@suse.com>
SUSE Labs, CR
^ permalink raw reply [flat|nested] 24+ messages in thread
* [PATCH v3] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-05-28 19:59 ` Alejandro Colomar
2025-05-28 21:31 ` [RFC v1] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino Alejandro Colomar
2025-10-28 23:15 ` [PATCH v2] " Alejandro Colomar
@ 2025-10-31 10:44 ` Alejandro Colomar
2025-10-31 10:56 ` Jan Kara
2025-10-31 15:25 ` Darrick J. Wong
2 siblings, 2 replies; 24+ messages in thread
From: Alejandro Colomar @ 2025-10-31 10:44 UTC (permalink / raw)
To: linux-man
Cc: Alejandro Colomar, Pali Rohár, Jan Kara, G. Branden Robinson,
linux-fsdevel
Suggested-by: Pali Rohár <pali@kernel.org>
Co-authored-by: Pali Rohár <pali@kernel.org>
Co-authored-by: Jan Kara <jack@suse.cz>
Cc: "G. Branden Robinson" <branden@debian.org>
Cc: <linux-fsdevel@vger.kernel.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
Hi Jan,
I've put your suggestions into the patch. I've also removed the
sentence about POSIX, as Pali discussed with Branden.
At the bottom of the email is the range-diff against the previous
version.
Have a lovely day!
Alex
man/man3/readdir.3 | 19 ++++++++++++++++++-
man/man3type/stat.3type | 20 +++++++++++++++++++-
2 files changed, 37 insertions(+), 2 deletions(-)
diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
index e1c7d2a6a..220643795 100644
--- a/man/man3/readdir.3
+++ b/man/man3/readdir.3
@@ -58,7 +58,24 @@ .SH DESCRIPTION
structure are as follows:
.TP
.I .d_ino
-This is the inode number of the file.
+This is the inode number of the file
+in the filesystem containing
+the directory on which
+.BR readdir ()
+was called.
+If the directory entry is the mount point,
+then
+.I .d_ino
+differs from
+.I .st_ino
+returned by
+.BR stat (2)
+on this file:
+.I .d_ino
+is the inode number of the mount point,
+while
+.I .st_ino
+is the inode number of the root directory of the mounted filesystem.
.TP
.I .d_off
The value returned in
diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
index 76ee3765d..ea9acc5ec 100644
--- a/man/man3type/stat.3type
+++ b/man/man3type/stat.3type
@@ -66,7 +66,25 @@ .SH DESCRIPTION
macros may be useful to decompose the device ID in this field.)
.TP
.I .st_ino
-This field contains the file's inode number.
+This field contains the file's inode number
+in the filesystem on
+.IR .st_dev .
+If
+.BR stat (2)
+was called on the mount point,
+then
+.I .st_ino
+differs from
+.I .d_ino
+returned by
+.BR readdir (3)
+for the corresponding directory entry in the parent directory.
+In this case,
+.I .st_ino
+is the inode number of the root directory of the mounted filesystem,
+while
+.I .d_ino
+is the inode number of the mount point in the parent filesystem.
.TP
.I .st_mode
This field contains the file type and mode.
Range-diff against v2:
1: d3eeebe81 ! 1: bfa7e72ea man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
@@ Commit message
Suggested-by: Pali Rohár <pali@kernel.org>
Co-authored-by: Pali Rohár <pali@kernel.org>
+ Co-authored-by: Jan Kara <jack@suse.cz>
Cc: "G. Branden Robinson" <branden@debian.org>
Cc: <linux-fsdevel@vger.kernel.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
@@ man/man3/readdir.3: .SH DESCRIPTION
.TP
.I .d_ino
-This is the inode number of the file.
-+This is the inode number of the file,
-+which belongs to the filesystem
-+.I .st_dev
-+(see
-+.BR stat (3type))
-+of the directory on which
++This is the inode number of the file
++in the filesystem containing
++the directory on which
+.BR readdir ()
+was called.
+If the directory entry is the mount point,
+then
+.I .d_ino
+differs from
-+.IR .st_ino :
++.I .st_ino
++returned by
++.BR stat (2)
++on this file:
+.I .d_ino
-+is the inode number of the underlying mount point,
++is the inode number of the mount point,
+while
+.I .st_ino
-+is the inode number of the mounted file system.
-+According to POSIX,
-+this Linux behavior is considered to be a bug,
-+but is nevertheless conforming.
++is the inode number of the root directory of the mounted filesystem.
.TP
.I .d_off
The value returned in
@@ man/man3type/stat.3type: .SH DESCRIPTION
.TP
.I .st_ino
-This field contains the file's inode number.
-+This field contains the file's inode number,
-+which belongs to the
++This field contains the file's inode number
++in the filesystem on
+.IR .st_dev .
+If
+.BR stat (2)
+was called on the mount point,
+then
-+.I .d_ino
-+differs from
-+.IR .st_ino :
-+.I .d_ino
-+is the inode number of the underlying mount point,
-+while
+.I .st_ino
-+is the inode number of the mounted file system.
++differs from
++.I .d_ino
++returned by
++.BR readdir (3)
++for the corresponding directory entry in the parent directory.
++In this case,
++.I .st_ino
++is the inode number of the root directory of the mounted filesystem,
++while
++.I .d_ino
++is the inode number of the mount point in the parent filesystem.
.TP
.I .st_mode
This field contains the file type and mode.
base-commit: f305f7647d5cf62e7e764fb7a25c4926160c594f
--
2.51.0
^ permalink raw reply related [flat|nested] 24+ messages in thread
* Re: [PATCH v3] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-10-31 10:44 ` [PATCH v3] " Alejandro Colomar
@ 2025-10-31 10:56 ` Jan Kara
2025-10-31 11:31 ` Alejandro Colomar
2025-10-31 15:25 ` Darrick J. Wong
1 sibling, 1 reply; 24+ messages in thread
From: Jan Kara @ 2025-10-31 10:56 UTC (permalink / raw)
To: Alejandro Colomar
Cc: linux-man, Pali Rohár, Jan Kara, G. Branden Robinson,
linux-fsdevel
On Fri 31-10-25 11:44:14, Alejandro Colomar wrote:
> Suggested-by: Pali Rohár <pali@kernel.org>
> Co-authored-by: Pali Rohár <pali@kernel.org>
> Co-authored-by: Jan Kara <jack@suse.cz>
> Cc: "G. Branden Robinson" <branden@debian.org>
> Cc: <linux-fsdevel@vger.kernel.org>
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
>
> Hi Jan,
>
> I've put your suggestions into the patch. I've also removed the
> sentence about POSIX, as Pali discussed with Branden.
>
> At the bottom of the email is the range-diff against the previous
> version.
Thanks! The patch looks good. Feel free to add:
Reviewed-by: Jan Kara <jack@suse.cz>
Honza
>
>
> Have a lovely day!
> Alex
>
> man/man3/readdir.3 | 19 ++++++++++++++++++-
> man/man3type/stat.3type | 20 +++++++++++++++++++-
> 2 files changed, 37 insertions(+), 2 deletions(-)
>
> diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
> index e1c7d2a6a..220643795 100644
> --- a/man/man3/readdir.3
> +++ b/man/man3/readdir.3
> @@ -58,7 +58,24 @@ .SH DESCRIPTION
> structure are as follows:
> .TP
> .I .d_ino
> -This is the inode number of the file.
> +This is the inode number of the file
> +in the filesystem containing
> +the directory on which
> +.BR readdir ()
> +was called.
> +If the directory entry is the mount point,
> +then
> +.I .d_ino
> +differs from
> +.I .st_ino
> +returned by
> +.BR stat (2)
> +on this file:
> +.I .d_ino
> +is the inode number of the mount point,
> +while
> +.I .st_ino
> +is the inode number of the root directory of the mounted filesystem.
> .TP
> .I .d_off
> The value returned in
> diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
> index 76ee3765d..ea9acc5ec 100644
> --- a/man/man3type/stat.3type
> +++ b/man/man3type/stat.3type
> @@ -66,7 +66,25 @@ .SH DESCRIPTION
> macros may be useful to decompose the device ID in this field.)
> .TP
> .I .st_ino
> -This field contains the file's inode number.
> +This field contains the file's inode number
> +in the filesystem on
> +.IR .st_dev .
> +If
> +.BR stat (2)
> +was called on the mount point,
> +then
> +.I .st_ino
> +differs from
> +.I .d_ino
> +returned by
> +.BR readdir (3)
> +for the corresponding directory entry in the parent directory.
> +In this case,
> +.I .st_ino
> +is the inode number of the root directory of the mounted filesystem,
> +while
> +.I .d_ino
> +is the inode number of the mount point in the parent filesystem.
> .TP
> .I .st_mode
> This field contains the file type and mode.
>
> Range-diff against v2:
> 1: d3eeebe81 ! 1: bfa7e72ea man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
> @@ Commit message
>
> Suggested-by: Pali Rohár <pali@kernel.org>
> Co-authored-by: Pali Rohár <pali@kernel.org>
> + Co-authored-by: Jan Kara <jack@suse.cz>
> Cc: "G. Branden Robinson" <branden@debian.org>
> Cc: <linux-fsdevel@vger.kernel.org>
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> @@ man/man3/readdir.3: .SH DESCRIPTION
> .TP
> .I .d_ino
> -This is the inode number of the file.
> -+This is the inode number of the file,
> -+which belongs to the filesystem
> -+.I .st_dev
> -+(see
> -+.BR stat (3type))
> -+of the directory on which
> ++This is the inode number of the file
> ++in the filesystem containing
> ++the directory on which
> +.BR readdir ()
> +was called.
> +If the directory entry is the mount point,
> +then
> +.I .d_ino
> +differs from
> -+.IR .st_ino :
> ++.I .st_ino
> ++returned by
> ++.BR stat (2)
> ++on this file:
> +.I .d_ino
> -+is the inode number of the underlying mount point,
> ++is the inode number of the mount point,
> +while
> +.I .st_ino
> -+is the inode number of the mounted file system.
> -+According to POSIX,
> -+this Linux behavior is considered to be a bug,
> -+but is nevertheless conforming.
> ++is the inode number of the root directory of the mounted filesystem.
> .TP
> .I .d_off
> The value returned in
> @@ man/man3type/stat.3type: .SH DESCRIPTION
> .TP
> .I .st_ino
> -This field contains the file's inode number.
> -+This field contains the file's inode number,
> -+which belongs to the
> ++This field contains the file's inode number
> ++in the filesystem on
> +.IR .st_dev .
> +If
> +.BR stat (2)
> +was called on the mount point,
> +then
> -+.I .d_ino
> -+differs from
> -+.IR .st_ino :
> -+.I .d_ino
> -+is the inode number of the underlying mount point,
> -+while
> +.I .st_ino
> -+is the inode number of the mounted file system.
> ++differs from
> ++.I .d_ino
> ++returned by
> ++.BR readdir (3)
> ++for the corresponding directory entry in the parent directory.
> ++In this case,
> ++.I .st_ino
> ++is the inode number of the root directory of the mounted filesystem,
> ++while
> ++.I .d_ino
> ++is the inode number of the mount point in the parent filesystem.
> .TP
> .I .st_mode
> This field contains the file type and mode.
>
> base-commit: f305f7647d5cf62e7e764fb7a25c4926160c594f
> --
> 2.51.0
>
--
Jan Kara <jack@suse.com>
SUSE Labs, CR
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v3] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-10-31 10:56 ` Jan Kara
@ 2025-10-31 11:31 ` Alejandro Colomar
2025-10-31 17:10 ` Pali Rohár
0 siblings, 1 reply; 24+ messages in thread
From: Alejandro Colomar @ 2025-10-31 11:31 UTC (permalink / raw)
To: Jan Kara; +Cc: linux-man, Pali Rohár, G. Branden Robinson, linux-fsdevel
[-- Attachment #1: Type: text/plain, Size: 6159 bytes --]
Hi Jan, Pali,
On Fri, Oct 31, 2025 at 11:56:19AM +0100, Jan Kara wrote:
> On Fri 31-10-25 11:44:14, Alejandro Colomar wrote:
> > Suggested-by: Pali Rohár <pali@kernel.org>
> > Co-authored-by: Pali Rohár <pali@kernel.org>
> > Co-authored-by: Jan Kara <jack@suse.cz>
> > Cc: "G. Branden Robinson" <branden@debian.org>
> > Cc: <linux-fsdevel@vger.kernel.org>
> > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > ---
> >
> > Hi Jan,
> >
> > I've put your suggestions into the patch. I've also removed the
> > sentence about POSIX, as Pali discussed with Branden.
> >
> > At the bottom of the email is the range-diff against the previous
> > version.
>
> Thanks! The patch looks good. Feel free to add:
>
> Reviewed-by: Jan Kara <jack@suse.cz>
Thanks!
Pali, would you mind signing the patch? One you do, I'll merge.
Cheers,
Alex
>
> Honza
>
> >
> >
> > Have a lovely day!
> > Alex
> >
> > man/man3/readdir.3 | 19 ++++++++++++++++++-
> > man/man3type/stat.3type | 20 +++++++++++++++++++-
> > 2 files changed, 37 insertions(+), 2 deletions(-)
> >
> > diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
> > index e1c7d2a6a..220643795 100644
> > --- a/man/man3/readdir.3
> > +++ b/man/man3/readdir.3
> > @@ -58,7 +58,24 @@ .SH DESCRIPTION
> > structure are as follows:
> > .TP
> > .I .d_ino
> > -This is the inode number of the file.
> > +This is the inode number of the file
> > +in the filesystem containing
> > +the directory on which
> > +.BR readdir ()
> > +was called.
> > +If the directory entry is the mount point,
> > +then
> > +.I .d_ino
> > +differs from
> > +.I .st_ino
> > +returned by
> > +.BR stat (2)
> > +on this file:
> > +.I .d_ino
> > +is the inode number of the mount point,
> > +while
> > +.I .st_ino
> > +is the inode number of the root directory of the mounted filesystem.
> > .TP
> > .I .d_off
> > The value returned in
> > diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
> > index 76ee3765d..ea9acc5ec 100644
> > --- a/man/man3type/stat.3type
> > +++ b/man/man3type/stat.3type
> > @@ -66,7 +66,25 @@ .SH DESCRIPTION
> > macros may be useful to decompose the device ID in this field.)
> > .TP
> > .I .st_ino
> > -This field contains the file's inode number.
> > +This field contains the file's inode number
> > +in the filesystem on
> > +.IR .st_dev .
> > +If
> > +.BR stat (2)
> > +was called on the mount point,
> > +then
> > +.I .st_ino
> > +differs from
> > +.I .d_ino
> > +returned by
> > +.BR readdir (3)
> > +for the corresponding directory entry in the parent directory.
> > +In this case,
> > +.I .st_ino
> > +is the inode number of the root directory of the mounted filesystem,
> > +while
> > +.I .d_ino
> > +is the inode number of the mount point in the parent filesystem.
> > .TP
> > .I .st_mode
> > This field contains the file type and mode.
> >
> > Range-diff against v2:
> > 1: d3eeebe81 ! 1: bfa7e72ea man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
> > @@ Commit message
> >
> > Suggested-by: Pali Rohár <pali@kernel.org>
> > Co-authored-by: Pali Rohár <pali@kernel.org>
> > + Co-authored-by: Jan Kara <jack@suse.cz>
> > Cc: "G. Branden Robinson" <branden@debian.org>
> > Cc: <linux-fsdevel@vger.kernel.org>
> > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > @@ man/man3/readdir.3: .SH DESCRIPTION
> > .TP
> > .I .d_ino
> > -This is the inode number of the file.
> > -+This is the inode number of the file,
> > -+which belongs to the filesystem
> > -+.I .st_dev
> > -+(see
> > -+.BR stat (3type))
> > -+of the directory on which
> > ++This is the inode number of the file
> > ++in the filesystem containing
> > ++the directory on which
> > +.BR readdir ()
> > +was called.
> > +If the directory entry is the mount point,
> > +then
> > +.I .d_ino
> > +differs from
> > -+.IR .st_ino :
> > ++.I .st_ino
> > ++returned by
> > ++.BR stat (2)
> > ++on this file:
> > +.I .d_ino
> > -+is the inode number of the underlying mount point,
> > ++is the inode number of the mount point,
> > +while
> > +.I .st_ino
> > -+is the inode number of the mounted file system.
> > -+According to POSIX,
> > -+this Linux behavior is considered to be a bug,
> > -+but is nevertheless conforming.
> > ++is the inode number of the root directory of the mounted filesystem.
> > .TP
> > .I .d_off
> > The value returned in
> > @@ man/man3type/stat.3type: .SH DESCRIPTION
> > .TP
> > .I .st_ino
> > -This field contains the file's inode number.
> > -+This field contains the file's inode number,
> > -+which belongs to the
> > ++This field contains the file's inode number
> > ++in the filesystem on
> > +.IR .st_dev .
> > +If
> > +.BR stat (2)
> > +was called on the mount point,
> > +then
> > -+.I .d_ino
> > -+differs from
> > -+.IR .st_ino :
> > -+.I .d_ino
> > -+is the inode number of the underlying mount point,
> > -+while
> > +.I .st_ino
> > -+is the inode number of the mounted file system.
> > ++differs from
> > ++.I .d_ino
> > ++returned by
> > ++.BR readdir (3)
> > ++for the corresponding directory entry in the parent directory.
> > ++In this case,
> > ++.I .st_ino
> > ++is the inode number of the root directory of the mounted filesystem,
> > ++while
> > ++.I .d_ino
> > ++is the inode number of the mount point in the parent filesystem.
> > .TP
> > .I .st_mode
> > This field contains the file type and mode.
> >
> > base-commit: f305f7647d5cf62e7e764fb7a25c4926160c594f
> > --
> > 2.51.0
> >
> --
> Jan Kara <jack@suse.com>
> SUSE Labs, CR
--
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v3] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-10-31 10:44 ` [PATCH v3] " Alejandro Colomar
2025-10-31 10:56 ` Jan Kara
@ 2025-10-31 15:25 ` Darrick J. Wong
2025-11-02 21:17 ` Alejandro Colomar
1 sibling, 1 reply; 24+ messages in thread
From: Darrick J. Wong @ 2025-10-31 15:25 UTC (permalink / raw)
To: Alejandro Colomar
Cc: linux-man, Pali Rohár, Jan Kara, G. Branden Robinson,
linux-fsdevel
On Fri, Oct 31, 2025 at 11:44:14AM +0100, Alejandro Colomar wrote:
> Suggested-by: Pali Rohár <pali@kernel.org>
> Co-authored-by: Pali Rohár <pali@kernel.org>
> Co-authored-by: Jan Kara <jack@suse.cz>
> Cc: "G. Branden Robinson" <branden@debian.org>
> Cc: <linux-fsdevel@vger.kernel.org>
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
>
> Hi Jan,
>
> I've put your suggestions into the patch. I've also removed the
> sentence about POSIX, as Pali discussed with Branden.
>
> At the bottom of the email is the range-diff against the previous
> version.
>
>
> Have a lovely day!
> Alex
>
> man/man3/readdir.3 | 19 ++++++++++++++++++-
> man/man3type/stat.3type | 20 +++++++++++++++++++-
> 2 files changed, 37 insertions(+), 2 deletions(-)
>
> diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
> index e1c7d2a6a..220643795 100644
> --- a/man/man3/readdir.3
> +++ b/man/man3/readdir.3
> @@ -58,7 +58,24 @@ .SH DESCRIPTION
> structure are as follows:
> .TP
> .I .d_ino
> -This is the inode number of the file.
> +This is the inode number of the file
> +in the filesystem containing
> +the directory on which
> +.BR readdir ()
> +was called.
> +If the directory entry is the mount point,
nitpicking english:
"...is a mount point," ?
--D
> +then
> +.I .d_ino
> +differs from
> +.I .st_ino
> +returned by
> +.BR stat (2)
> +on this file:
> +.I .d_ino
> +is the inode number of the mount point,
> +while
> +.I .st_ino
> +is the inode number of the root directory of the mounted filesystem.
> .TP
> .I .d_off
> The value returned in
> diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
> index 76ee3765d..ea9acc5ec 100644
> --- a/man/man3type/stat.3type
> +++ b/man/man3type/stat.3type
> @@ -66,7 +66,25 @@ .SH DESCRIPTION
> macros may be useful to decompose the device ID in this field.)
> .TP
> .I .st_ino
> -This field contains the file's inode number.
> +This field contains the file's inode number
> +in the filesystem on
> +.IR .st_dev .
> +If
> +.BR stat (2)
> +was called on the mount point,
> +then
> +.I .st_ino
> +differs from
> +.I .d_ino
> +returned by
> +.BR readdir (3)
> +for the corresponding directory entry in the parent directory.
> +In this case,
> +.I .st_ino
> +is the inode number of the root directory of the mounted filesystem,
> +while
> +.I .d_ino
> +is the inode number of the mount point in the parent filesystem.
> .TP
> .I .st_mode
> This field contains the file type and mode.
>
> Range-diff against v2:
> 1: d3eeebe81 ! 1: bfa7e72ea man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
> @@ Commit message
>
> Suggested-by: Pali Rohár <pali@kernel.org>
> Co-authored-by: Pali Rohár <pali@kernel.org>
> + Co-authored-by: Jan Kara <jack@suse.cz>
> Cc: "G. Branden Robinson" <branden@debian.org>
> Cc: <linux-fsdevel@vger.kernel.org>
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> @@ man/man3/readdir.3: .SH DESCRIPTION
> .TP
> .I .d_ino
> -This is the inode number of the file.
> -+This is the inode number of the file,
> -+which belongs to the filesystem
> -+.I .st_dev
> -+(see
> -+.BR stat (3type))
> -+of the directory on which
> ++This is the inode number of the file
> ++in the filesystem containing
> ++the directory on which
> +.BR readdir ()
> +was called.
> +If the directory entry is the mount point,
> +then
> +.I .d_ino
> +differs from
> -+.IR .st_ino :
> ++.I .st_ino
> ++returned by
> ++.BR stat (2)
> ++on this file:
> +.I .d_ino
> -+is the inode number of the underlying mount point,
> ++is the inode number of the mount point,
> +while
> +.I .st_ino
> -+is the inode number of the mounted file system.
> -+According to POSIX,
> -+this Linux behavior is considered to be a bug,
> -+but is nevertheless conforming.
> ++is the inode number of the root directory of the mounted filesystem.
> .TP
> .I .d_off
> The value returned in
> @@ man/man3type/stat.3type: .SH DESCRIPTION
> .TP
> .I .st_ino
> -This field contains the file's inode number.
> -+This field contains the file's inode number,
> -+which belongs to the
> ++This field contains the file's inode number
> ++in the filesystem on
> +.IR .st_dev .
> +If
> +.BR stat (2)
> +was called on the mount point,
> +then
> -+.I .d_ino
> -+differs from
> -+.IR .st_ino :
> -+.I .d_ino
> -+is the inode number of the underlying mount point,
> -+while
> +.I .st_ino
> -+is the inode number of the mounted file system.
> ++differs from
> ++.I .d_ino
> ++returned by
> ++.BR readdir (3)
> ++for the corresponding directory entry in the parent directory.
> ++In this case,
> ++.I .st_ino
> ++is the inode number of the root directory of the mounted filesystem,
> ++while
> ++.I .d_ino
> ++is the inode number of the mount point in the parent filesystem.
> .TP
> .I .st_mode
> This field contains the file type and mode.
>
> base-commit: f305f7647d5cf62e7e764fb7a25c4926160c594f
> --
> 2.51.0
>
>
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v3] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-10-31 11:31 ` Alejandro Colomar
@ 2025-10-31 17:10 ` Pali Rohár
0 siblings, 0 replies; 24+ messages in thread
From: Pali Rohár @ 2025-10-31 17:10 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Jan Kara, linux-man, G. Branden Robinson, linux-fsdevel
On Friday 31 October 2025 12:31:41 Alejandro Colomar wrote:
> Hi Jan, Pali,
>
> On Fri, Oct 31, 2025 at 11:56:19AM +0100, Jan Kara wrote:
> > On Fri 31-10-25 11:44:14, Alejandro Colomar wrote:
> > > Suggested-by: Pali Rohár <pali@kernel.org>
> > > Co-authored-by: Pali Rohár <pali@kernel.org>
> > > Co-authored-by: Jan Kara <jack@suse.cz>
> > > Cc: "G. Branden Robinson" <branden@debian.org>
> > > Cc: <linux-fsdevel@vger.kernel.org>
> > > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > > ---
> > >
> > > Hi Jan,
> > >
> > > I've put your suggestions into the patch. I've also removed the
> > > sentence about POSIX, as Pali discussed with Branden.
> > >
> > > At the bottom of the email is the range-diff against the previous
> > > version.
> >
> > Thanks! The patch looks good. Feel free to add:
> >
> > Reviewed-by: Jan Kara <jack@suse.cz>
>
> Thanks!
>
> Pali, would you mind signing the patch? One you do, I'll merge.
Hello, yes, that this fine.
Reviewed-by: Pali Rohár <pali@kernel.org>
For future improvements, it would be nice to adjust also other manpages
which refers to inode numbers:
git grep -E '\<st_ino\>|\<stx_ino\>|\<d_ino\>'
>
> Cheers,
> Alex
>
> >
> > Honza
> >
> > >
> > >
> > > Have a lovely day!
> > > Alex
> > >
> > > man/man3/readdir.3 | 19 ++++++++++++++++++-
> > > man/man3type/stat.3type | 20 +++++++++++++++++++-
> > > 2 files changed, 37 insertions(+), 2 deletions(-)
> > >
> > > diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
> > > index e1c7d2a6a..220643795 100644
> > > --- a/man/man3/readdir.3
> > > +++ b/man/man3/readdir.3
> > > @@ -58,7 +58,24 @@ .SH DESCRIPTION
> > > structure are as follows:
> > > .TP
> > > .I .d_ino
> > > -This is the inode number of the file.
> > > +This is the inode number of the file
> > > +in the filesystem containing
> > > +the directory on which
> > > +.BR readdir ()
> > > +was called.
> > > +If the directory entry is the mount point,
> > > +then
> > > +.I .d_ino
> > > +differs from
> > > +.I .st_ino
> > > +returned by
> > > +.BR stat (2)
> > > +on this file:
> > > +.I .d_ino
> > > +is the inode number of the mount point,
> > > +while
> > > +.I .st_ino
> > > +is the inode number of the root directory of the mounted filesystem.
> > > .TP
> > > .I .d_off
> > > The value returned in
> > > diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
> > > index 76ee3765d..ea9acc5ec 100644
> > > --- a/man/man3type/stat.3type
> > > +++ b/man/man3type/stat.3type
> > > @@ -66,7 +66,25 @@ .SH DESCRIPTION
> > > macros may be useful to decompose the device ID in this field.)
> > > .TP
> > > .I .st_ino
> > > -This field contains the file's inode number.
> > > +This field contains the file's inode number
> > > +in the filesystem on
> > > +.IR .st_dev .
> > > +If
> > > +.BR stat (2)
> > > +was called on the mount point,
> > > +then
> > > +.I .st_ino
> > > +differs from
> > > +.I .d_ino
> > > +returned by
> > > +.BR readdir (3)
> > > +for the corresponding directory entry in the parent directory.
> > > +In this case,
> > > +.I .st_ino
> > > +is the inode number of the root directory of the mounted filesystem,
> > > +while
> > > +.I .d_ino
> > > +is the inode number of the mount point in the parent filesystem.
> > > .TP
> > > .I .st_mode
> > > This field contains the file type and mode.
> > >
> > > Range-diff against v2:
> > > 1: d3eeebe81 ! 1: bfa7e72ea man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
> > > @@ Commit message
> > >
> > > Suggested-by: Pali Rohár <pali@kernel.org>
> > > Co-authored-by: Pali Rohár <pali@kernel.org>
> > > + Co-authored-by: Jan Kara <jack@suse.cz>
> > > Cc: "G. Branden Robinson" <branden@debian.org>
> > > Cc: <linux-fsdevel@vger.kernel.org>
> > > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > > @@ man/man3/readdir.3: .SH DESCRIPTION
> > > .TP
> > > .I .d_ino
> > > -This is the inode number of the file.
> > > -+This is the inode number of the file,
> > > -+which belongs to the filesystem
> > > -+.I .st_dev
> > > -+(see
> > > -+.BR stat (3type))
> > > -+of the directory on which
> > > ++This is the inode number of the file
> > > ++in the filesystem containing
> > > ++the directory on which
> > > +.BR readdir ()
> > > +was called.
> > > +If the directory entry is the mount point,
> > > +then
> > > +.I .d_ino
> > > +differs from
> > > -+.IR .st_ino :
> > > ++.I .st_ino
> > > ++returned by
> > > ++.BR stat (2)
> > > ++on this file:
> > > +.I .d_ino
> > > -+is the inode number of the underlying mount point,
> > > ++is the inode number of the mount point,
> > > +while
> > > +.I .st_ino
> > > -+is the inode number of the mounted file system.
> > > -+According to POSIX,
> > > -+this Linux behavior is considered to be a bug,
> > > -+but is nevertheless conforming.
> > > ++is the inode number of the root directory of the mounted filesystem.
> > > .TP
> > > .I .d_off
> > > The value returned in
> > > @@ man/man3type/stat.3type: .SH DESCRIPTION
> > > .TP
> > > .I .st_ino
> > > -This field contains the file's inode number.
> > > -+This field contains the file's inode number,
> > > -+which belongs to the
> > > ++This field contains the file's inode number
> > > ++in the filesystem on
> > > +.IR .st_dev .
> > > +If
> > > +.BR stat (2)
> > > +was called on the mount point,
> > > +then
> > > -+.I .d_ino
> > > -+differs from
> > > -+.IR .st_ino :
> > > -+.I .d_ino
> > > -+is the inode number of the underlying mount point,
> > > -+while
> > > +.I .st_ino
> > > -+is the inode number of the mounted file system.
> > > ++differs from
> > > ++.I .d_ino
> > > ++returned by
> > > ++.BR readdir (3)
> > > ++for the corresponding directory entry in the parent directory.
> > > ++In this case,
> > > ++.I .st_ino
> > > ++is the inode number of the root directory of the mounted filesystem,
> > > ++while
> > > ++.I .d_ino
> > > ++is the inode number of the mount point in the parent filesystem.
> > > .TP
> > > .I .st_mode
> > > This field contains the file type and mode.
> > >
> > > base-commit: f305f7647d5cf62e7e764fb7a25c4926160c594f
> > > --
> > > 2.51.0
> > >
> > --
> > Jan Kara <jack@suse.com>
> > SUSE Labs, CR
>
> --
> <https://www.alejandro-colomar.es>
> Use port 80 (that is, <...:80/>).
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v3] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-10-31 15:25 ` Darrick J. Wong
@ 2025-11-02 21:17 ` Alejandro Colomar
2025-11-03 11:28 ` Jan Kara
0 siblings, 1 reply; 24+ messages in thread
From: Alejandro Colomar @ 2025-11-02 21:17 UTC (permalink / raw)
To: Darrick J. Wong
Cc: linux-man, Pali Rohár, Jan Kara, G. Branden Robinson,
linux-fsdevel
[-- Attachment #1: Type: text/plain, Size: 6132 bytes --]
Hi Darrick,
On Fri, Oct 31, 2025 at 08:25:31AM -0700, Darrick J. Wong wrote:
> On Fri, Oct 31, 2025 at 11:44:14AM +0100, Alejandro Colomar wrote:
> > Suggested-by: Pali Rohár <pali@kernel.org>
> > Co-authored-by: Pali Rohár <pali@kernel.org>
> > Co-authored-by: Jan Kara <jack@suse.cz>
> > Cc: "G. Branden Robinson" <branden@debian.org>
> > Cc: <linux-fsdevel@vger.kernel.org>
> > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > ---
> >
> > Hi Jan,
> >
> > I've put your suggestions into the patch. I've also removed the
> > sentence about POSIX, as Pali discussed with Branden.
> >
> > At the bottom of the email is the range-diff against the previous
> > version.
> >
> >
> > Have a lovely day!
> > Alex
> >
> > man/man3/readdir.3 | 19 ++++++++++++++++++-
> > man/man3type/stat.3type | 20 +++++++++++++++++++-
> > 2 files changed, 37 insertions(+), 2 deletions(-)
> >
> > diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
> > index e1c7d2a6a..220643795 100644
> > --- a/man/man3/readdir.3
> > +++ b/man/man3/readdir.3
> > @@ -58,7 +58,24 @@ .SH DESCRIPTION
> > structure are as follows:
> > .TP
> > .I .d_ino
> > -This is the inode number of the file.
> > +This is the inode number of the file
> > +in the filesystem containing
> > +the directory on which
> > +.BR readdir ()
> > +was called.
> > +If the directory entry is the mount point,
>
> nitpicking english:
>
> "...is a mount point," ?
I think you're right. Unless Jan and Pali meant something more
specific. Jan, Pali, can you please confirm?
Have a lovely night!
Alex
>
> --D
>
> > +then
> > +.I .d_ino
> > +differs from
> > +.I .st_ino
> > +returned by
> > +.BR stat (2)
> > +on this file:
> > +.I .d_ino
> > +is the inode number of the mount point,
> > +while
> > +.I .st_ino
> > +is the inode number of the root directory of the mounted filesystem.
> > .TP
> > .I .d_off
> > The value returned in
> > diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type
> > index 76ee3765d..ea9acc5ec 100644
> > --- a/man/man3type/stat.3type
> > +++ b/man/man3type/stat.3type
> > @@ -66,7 +66,25 @@ .SH DESCRIPTION
> > macros may be useful to decompose the device ID in this field.)
> > .TP
> > .I .st_ino
> > -This field contains the file's inode number.
> > +This field contains the file's inode number
> > +in the filesystem on
> > +.IR .st_dev .
> > +If
> > +.BR stat (2)
> > +was called on the mount point,
> > +then
> > +.I .st_ino
> > +differs from
> > +.I .d_ino
> > +returned by
> > +.BR readdir (3)
> > +for the corresponding directory entry in the parent directory.
> > +In this case,
> > +.I .st_ino
> > +is the inode number of the root directory of the mounted filesystem,
> > +while
> > +.I .d_ino
> > +is the inode number of the mount point in the parent filesystem.
> > .TP
> > .I .st_mode
> > This field contains the file type and mode.
> >
> > Range-diff against v2:
> > 1: d3eeebe81 ! 1: bfa7e72ea man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
> > @@ Commit message
> >
> > Suggested-by: Pali Rohár <pali@kernel.org>
> > Co-authored-by: Pali Rohár <pali@kernel.org>
> > + Co-authored-by: Jan Kara <jack@suse.cz>
> > Cc: "G. Branden Robinson" <branden@debian.org>
> > Cc: <linux-fsdevel@vger.kernel.org>
> > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > @@ man/man3/readdir.3: .SH DESCRIPTION
> > .TP
> > .I .d_ino
> > -This is the inode number of the file.
> > -+This is the inode number of the file,
> > -+which belongs to the filesystem
> > -+.I .st_dev
> > -+(see
> > -+.BR stat (3type))
> > -+of the directory on which
> > ++This is the inode number of the file
> > ++in the filesystem containing
> > ++the directory on which
> > +.BR readdir ()
> > +was called.
> > +If the directory entry is the mount point,
> > +then
> > +.I .d_ino
> > +differs from
> > -+.IR .st_ino :
> > ++.I .st_ino
> > ++returned by
> > ++.BR stat (2)
> > ++on this file:
> > +.I .d_ino
> > -+is the inode number of the underlying mount point,
> > ++is the inode number of the mount point,
> > +while
> > +.I .st_ino
> > -+is the inode number of the mounted file system.
> > -+According to POSIX,
> > -+this Linux behavior is considered to be a bug,
> > -+but is nevertheless conforming.
> > ++is the inode number of the root directory of the mounted filesystem.
> > .TP
> > .I .d_off
> > The value returned in
> > @@ man/man3type/stat.3type: .SH DESCRIPTION
> > .TP
> > .I .st_ino
> > -This field contains the file's inode number.
> > -+This field contains the file's inode number,
> > -+which belongs to the
> > ++This field contains the file's inode number
> > ++in the filesystem on
> > +.IR .st_dev .
> > +If
> > +.BR stat (2)
> > +was called on the mount point,
> > +then
> > -+.I .d_ino
> > -+differs from
> > -+.IR .st_ino :
> > -+.I .d_ino
> > -+is the inode number of the underlying mount point,
> > -+while
> > +.I .st_ino
> > -+is the inode number of the mounted file system.
> > ++differs from
> > ++.I .d_ino
> > ++returned by
> > ++.BR readdir (3)
> > ++for the corresponding directory entry in the parent directory.
> > ++In this case,
> > ++.I .st_ino
> > ++is the inode number of the root directory of the mounted filesystem,
> > ++while
> > ++.I .d_ino
> > ++is the inode number of the mount point in the parent filesystem.
> > .TP
> > .I .st_mode
> > This field contains the file type and mode.
> >
> > base-commit: f305f7647d5cf62e7e764fb7a25c4926160c594f
> > --
> > 2.51.0
> >
> >
--
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v3] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-11-02 21:17 ` Alejandro Colomar
@ 2025-11-03 11:28 ` Jan Kara
2025-11-09 12:07 ` Alejandro Colomar
0 siblings, 1 reply; 24+ messages in thread
From: Jan Kara @ 2025-11-03 11:28 UTC (permalink / raw)
To: Alejandro Colomar
Cc: Darrick J. Wong, linux-man, Pali Rohár, Jan Kara,
G. Branden Robinson, linux-fsdevel
On Sun 02-11-25 22:17:06, Alejandro Colomar wrote:
> Hi Darrick,
>
> On Fri, Oct 31, 2025 at 08:25:31AM -0700, Darrick J. Wong wrote:
> > On Fri, Oct 31, 2025 at 11:44:14AM +0100, Alejandro Colomar wrote:
> > > Suggested-by: Pali Rohár <pali@kernel.org>
> > > Co-authored-by: Pali Rohár <pali@kernel.org>
> > > Co-authored-by: Jan Kara <jack@suse.cz>
> > > Cc: "G. Branden Robinson" <branden@debian.org>
> > > Cc: <linux-fsdevel@vger.kernel.org>
> > > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > > ---
> > >
> > > Hi Jan,
> > >
> > > I've put your suggestions into the patch. I've also removed the
> > > sentence about POSIX, as Pali discussed with Branden.
> > >
> > > At the bottom of the email is the range-diff against the previous
> > > version.
> > >
> > >
> > > Have a lovely day!
> > > Alex
> > >
> > > man/man3/readdir.3 | 19 ++++++++++++++++++-
> > > man/man3type/stat.3type | 20 +++++++++++++++++++-
> > > 2 files changed, 37 insertions(+), 2 deletions(-)
> > >
> > > diff --git a/man/man3/readdir.3 b/man/man3/readdir.3
> > > index e1c7d2a6a..220643795 100644
> > > --- a/man/man3/readdir.3
> > > +++ b/man/man3/readdir.3
> > > @@ -58,7 +58,24 @@ .SH DESCRIPTION
> > > structure are as follows:
> > > .TP
> > > .I .d_ino
> > > -This is the inode number of the file.
> > > +This is the inode number of the file
> > > +in the filesystem containing
> > > +the directory on which
> > > +.BR readdir ()
> > > +was called.
> > > +If the directory entry is the mount point,
> >
> > nitpicking english:
> >
> > "...is a mount point," ?
>
> I think you're right. Unless Jan and Pali meant something more
> specific. Jan, Pali, can you please confirm?
Yes, Darrick is right :).
Honza
--
Jan Kara <jack@suse.com>
SUSE Labs, CR
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v3] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-11-03 11:28 ` Jan Kara
@ 2025-11-09 12:07 ` Alejandro Colomar
0 siblings, 0 replies; 24+ messages in thread
From: Alejandro Colomar @ 2025-11-09 12:07 UTC (permalink / raw)
To: Jan Kara
Cc: Darrick J. Wong, linux-man, Pali Rohár, G. Branden Robinson,
linux-fsdevel
[-- Attachment #1: Type: text/plain, Size: 765 bytes --]
Hi Jan, Darrick, Pali,
On Mon, Nov 03, 2025 at 12:28:21PM +0100, Jan Kara wrote:
> On Sun 02-11-25 22:17:06, Alejandro Colomar wrote:
> > On Fri, Oct 31, 2025 at 08:25:31AM -0700, Darrick J. Wong wrote:
> > > On Fri, Oct 31, 2025 at 11:44:14AM +0100, Alejandro Colomar wrote:
> > > > +If the directory entry is the mount point,
> > >
> > > nitpicking english:
> > >
> > > "...is a mount point," ?
> >
> > I think you're right. Unless Jan and Pali meant something more
> > specific. Jan, Pali, can you please confirm?
>
> Yes, Darrick is right :).
Thanks! I've amended the patch with that, added the Reviewed-by tags,
and pushed.
Have a lovely day!
Alex
--
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v2] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-10-29 19:34 ` Pali Rohár
@ 2025-11-21 21:10 ` Pali Rohár
2025-11-21 23:39 ` G. Branden Robinson
0 siblings, 1 reply; 24+ messages in thread
From: Pali Rohár @ 2025-11-21 21:10 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: linux-man, Jan Kara, Alejandro Colomar
On Wednesday 29 October 2025 20:34:13 Pali Rohár wrote:
> Hello Branden,
>
> On Wednesday 29 October 2025 02:00:39 G. Branden Robinson wrote:
> > Hi Pali,
> >
> > Thanks for following up.
> >
> > At 2025-10-29T00:53:06+0100, Pali Rohár wrote:
> > > Hello Branden, I'm sorry but I have not received your message because
> > > I'm not subscribed to the list. Otherwise I would have replied to you
> > > earlier.
> >
> > No worries--it's a risk I take when forgetting to CC people's accounts.
> >
> > > If you are referring to the "bug" then it is written in informative
> > > part in RATIONALE section of readdir / POSIX.1-2024. I wrote in my
> > > first email in that email thread which Alejandro linked above.
> > >
> > > Here is direct link to POSIX spec and below is quoted part:
> > > https://pubs.opengroup.org/onlinepubs/9799919799/functions/readdir.html
> > >
> > > "When returning a directory entry for the root of a mounted file
> > > system, some historical implementations of readdir() returned the file
> > > serial number of the underlying mount point, rather than of the root
> > > of the mounted file system. This behavior is considered to be a bug,
> > > since the underlying file serial number has no significance to
> > > applications."
> >
> > Thanks--this is precisely what I was asking for!
> >
> > > That part is in the "informative" section. I have not found anything
> > > in normative sections which would disallow usage of that "historical"
> > > behavior, so my understanding was that "historical" behavior is
> > > conforming too.
> > >
> > > Please correct me if I'm wrong here, or if it should be understood in
> > > different way.
> >
> > I can't speak for the Austin Group, but I don't read the text quite the
> > same way. I interpret it as saying that some historical implementations
> > of readdir() would _not_ "return a pointer to a structure representing
> > the directory entry at the current position in the directory stream
> > specified by the argument dirp, and position the directory stream at the
> > next entry." But I suspect that's not what it _intends_ to say.
> >
> > Instead, these implementations "returned [sic] the file serial number of
> > the underlying mount point", which I interpret to mean that they would
> > return a pointer to a _dirent_ struct whose _d_ino_ member was not the
> > file serial number of the file (of directory type) named by the _d_name_
> > member but a pointer to a _dirent_ struct whose _d_ino_ member was the
> > file serial number of the underlying mount point.
> >
> > I think there are two conclusions we can reach here.
> >
> > 1. POSIX.1-2024 might be a little sloppy in the wording of its
> > "RATIONALE" for this interface. Presumably no historical
> > implementation's readdir() returned a _d_ino_ number directly.
> > (Though with all the exuberant integer/pointer punning that used to
> > go in Unix, I'd wouldn't bet a lot of money that *no* implementation
> > ever did.) I'll wager a nickel that readdir() has always, on every
> > implementation, returned a pointer to a _dirent_ struct, and it is
> > only the value of the _d_ino_ member of the pointed-to struct that
> > some implementations have populated inconsistently when the entry is
> > a directory that is a mount point.
> >
> > If I'm right, this is an example of the common linguistic error of
> > synecdoche: confusing a container with (a subset of) its contents.
> >
> > 2. The behavior POSIX describes as buggy is, in fact, nonconforming.
>
> Only two? I can image that somebody come up with another conclusion.
> (just a joke)
>
> Anyway, I think that it is important to document the existing Linux
> behavior and whether it is POSIX-conforming or not is then second step.
> We can drop the information about POSIX conformity from manpage until we
> figure out how it is.
>
> > > Also I have not read all those 4000 pages, so maybe there is something
> > > hidden. It is quite hard to find information about this topic and that
> > > is why I think this should be documented in Linux manpages.
> >
> > I reckon someone should open a Mantis ticket with the Austin Group's
> > issue tracker to get clarity on what I characterized as "sloppy"
> > wording. Either it is and we can get the standard clarified, or I'm
> > wrong and an authority can point out how. (Maybe both!)
> >
> > I'm subscribed to the austin-group-l reflector and will take an action
> > item to file this ticket. I'll try to do within a week. (I have a lot
> > of old Unix books and would like to rummage around in them for any
> > documented land mines in this area.)
> >
> > Regards,
> > Branden
>
> Thanks for taking that part. It would be really nice if austin group can
> clarify how the whole situation is in a non-confusing way.
>
> Anyway, inode number is always connected to the specific mounted
> filesystem. So when the application is doing something with inodes, it
> always needs a pair (dev_t, ino_t) unless inodes belongs to same fs dev.
>
> readdir() and getdents() returns just ino_t, and without knowledge of
> dev_t, applications cannot use returned ino_t for anything useful.
> On "historical" implementations, the dev_t can be fetched for example by
> one fstat(dir_fd, &st) call as dev_t would be same for all readdir and
> getdents entries. But on non-"historical" implementation, it would be
> needed to call stat() on every one entry. For example /mnt/ directory
> which usually contains just mountpoints, will contain entries where
> each one has inode number 2 (common inode number for root of fs).
>
> I looked into archives and I have found that this problem was already
> discussed in the past. Here are some email threads from coreutils:
> https://lore.kernel.org/lkml/87y6oyhkz8.fsf@meyering.net/t/#u
> https://public-inbox.org/bug-coreutils/8763c5wcgn.fsf@meyering.net/t/#u
> https://public-inbox.org/bug-coreutils/87iqvi2j0q.fsf@rho.meyering.net/t/#u
> https://public-inbox.org/bug-coreutils/87verkborm.fsf@rho.meyering.net/
> https://public-inbox.org/bug-coreutils/022320061637.4398.43FDE4D7000110830000112E22007507440A050E040D0C079D0A@comcast.net/
>
> Maybe they could be a good reference for future discussion by austin group.
>
> Just my personal idea: If there would be some xgetdents syscall (like
> there statx over stat), it could return both inode numbers with dev_t
> and application can take which it wants.
>
> For example, NFS4's readdir can return both inode numbers (depending
> what is client asking). NFSv4.1 spec has nicely documented this problem
> with UNIX background of mount point crossing:
> https://www.rfc-editor.org/rfc/rfc8881.html#section-5.8.2.23
>
> Pali
Hello Branden, did you have a time fill a ticket to austin group?
If the ticket system is public, could you send a link for reference?
Pali
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v2] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-11-21 21:10 ` Pali Rohár
@ 2025-11-21 23:39 ` G. Branden Robinson
2025-11-22 0:53 ` Pali Rohár
0 siblings, 1 reply; 24+ messages in thread
From: G. Branden Robinson @ 2025-11-21 23:39 UTC (permalink / raw)
To: Pali Rohár; +Cc: linux-man, Jan Kara, Alejandro Colomar
[-- Attachment #1: Type: text/plain, Size: 7754 bytes --]
Hi Pali,
At 2025-11-21T22:10:28+0100, Pali Rohár wrote:
> On Wednesday 29 October 2025 20:34:13 Pali Rohár wrote:
> > On Wednesday 29 October 2025 02:00:39 G. Branden Robinson wrote:
> > > At 2025-10-29T00:53:06+0100, Pali Rohár wrote:
> > > > If you are referring to the "bug" then it is written in
> > > > informative part in RATIONALE section of readdir / POSIX.1-2024.
> > > > I wrote in my first email in that email thread which Alejandro
> > > > linked above.
> > > >
> > > > Here is direct link to POSIX spec and below is quoted part:
> > > > https://pubs.opengroup.org/onlinepubs/9799919799/functions/readdir.html
> > > >
> > > > "When returning a directory entry for the root of a mounted file
> > > > system, some historical implementations of readdir() returned
> > > > the file serial number of the underlying mount point, rather
> > > > than of the root of the mounted file system. This behavior is
> > > > considered to be a bug, since the underlying file serial number
> > > > has no significance to applications."
[...]
> > > > That part is in the "informative" section. I have not found
> > > > anything in normative sections which would disallow usage of
> > > > that "historical" behavior, so my understanding was that
> > > > "historical" behavior is conforming too.
> > > >
> > > > Please correct me if I'm wrong here, or if it should be
> > > > understood in different way.
> > >
> > > I can't speak for the Austin Group, but I don't read the text
> > > quite the same way. I interpret it as saying that some historical
> > > implementations of readdir() would _not_ "return a pointer to a
> > > structure representing the directory entry at the current position
> > > in the directory stream specified by the argument dirp, and
> > > position the directory stream at the next entry." But I suspect
> > > that's not what it _intends_ to say.
> > >
> > > Instead, these implementations "returned [sic] the file serial
> > > number of the underlying mount point", which I interpret to mean
> > > that they would return a pointer to a _dirent_ struct whose
> > > _d_ino_ member was not the file serial number of the file (of
> > > directory type) named by the _d_name_ member but a pointer to a
> > > _dirent_ struct whose _d_ino_ member was the file serial number of
> > > the underlying mount point.
> > >
> > > I think there are two conclusions we can reach here.
> > >
> > > 1. POSIX.1-2024 might be a little sloppy in the wording of its
> > > "RATIONALE" for this interface. Presumably no historical
> > > implementation's readdir() returned a _d_ino_ number directly.
> > > (Though with all the exuberant integer/pointer punning that
> > > used to go in Unix, I'd wouldn't bet a lot of money that *no*
> > > implementation ever did.) I'll wager a nickel that readdir()
> > > has always, on every implementation, returned a pointer to a
> > > _dirent_ struct, and it is only the value of the _d_ino_
> > > member of the pointed-to struct that some implementations have
> > > populated inconsistently when the entry is a directory that is
> > > a mount point.
> > >
> > > If I'm right, this is an example of the common linguistic
> > > error of synecdoche: confusing a container with (a subset of)
> > > its contents.
> > >
> > > 2. The behavior POSIX describes as buggy is, in fact,
> > > nonconforming.
> >
> > Only two? I can image that somebody come up with another conclusion.
> > (just a joke)
I wouldn't bet against your joke proving out in reality. ;-)
> > Anyway, I think that it is important to document the existing Linux
> > behavior and whether it is POSIX-conforming or not is then second
> > step. We can drop the information about POSIX conformity from
> > manpage until we figure out how it is.
> >
> > > > Also I have not read all those 4000 pages,
Pity the person who has. :) And mastery of all 4000+ pages should not
be necessary for an implementor to make sense of a reference entry for a
single function, command, or data object.
> > > > so maybe there is something hidden. It is quite hard to find
> > > > information about this topic and that is why I think this should
> > > > be documented in Linux manpages.
> > >
> > > I reckon someone should open a Mantis ticket with the Austin
> > > Group's issue tracker to get clarity on what I characterized as
> > > "sloppy" wording. Either it is and we can get the standard
> > > clarified, or I'm wrong and an authority can point out how.
> > > (Maybe both!)
> > >
> > > I'm subscribed to the austin-group-l reflector and will take an
> > > action item to file this ticket. I'll try to do within a week.
> > > (I have a lot of old Unix books and would like to rummage around
> > > in them for any documented land mines in this area.)
[...]
> > Thanks for taking that part. It would be really nice if austin group
> > can clarify how the whole situation is in a non-confusing way.
> >
> > Anyway, inode number is always connected to the specific mounted
> > filesystem. So when the application is doing something with inodes,
> > it always needs a pair (dev_t, ino_t) unless inodes belongs to same
> > fs dev.
> >
> > readdir() and getdents() returns just ino_t, and without knowledge
> > of dev_t, applications cannot use returned ino_t for anything
> > useful. On "historical" implementations, the dev_t can be fetched
> > for example by one fstat(dir_fd, &st) call as dev_t would be same
> > for all readdir and getdents entries. But on non-"historical"
> > implementation, it would be needed to call stat() on every one
> > entry. For example /mnt/ directory which usually contains just
> > mountpoints, will contain entries where each one has inode number 2
> > (common inode number for root of fs).
> >
> > I looked into archives and I have found that this problem was
> > already discussed in the past. Here are some email threads from
> > coreutils:
> > https://lore.kernel.org/lkml/87y6oyhkz8.fsf@meyering.net/t/#u
> > https://public-inbox.org/bug-coreutils/8763c5wcgn.fsf@meyering.net/t/#u
> > https://public-inbox.org/bug-coreutils/87iqvi2j0q.fsf@rho.meyering.net/t/#u
> > https://public-inbox.org/bug-coreutils/87verkborm.fsf@rho.meyering.net/
> > https://public-inbox.org/bug-coreutils/022320061637.4398.43FDE4D7000110830000112E22007507440A050E040D0C079D0A@comcast.net/
> >
> > Maybe they could be a good reference for future discussion by austin
> > group.
> >
> > Just my personal idea: If there would be some xgetdents syscall
> > (like there statx over stat), it could return both inode numbers
> > with dev_t and application can take which it wants.
> >
> > For example, NFS4's readdir can return both inode numbers (depending
> > what is client asking). NFSv4.1 spec has nicely documented this
> > problem with UNIX background of mount point crossing:
> > https://www.rfc-editor.org/rfc/rfc8881.html#section-5.8.2.23
> >
> > Pali
>
> Hello Branden, did you have a time fill a ticket to austin group?
Not yet--I procrastinated and got preoccupied by exciting new
undefined or ambiguously interpretable behavior of GNU troff.
https://www.mail-archive.com/groff@gnu.org/msg20834.html
> If the ticket system is public, could you send a link for reference?
It is public...
https://austingroupbugs.net/view_all_bug_page.php
...but to file a ticket or comment on one, I believe you need to create
an account. If you file a ticket yourself because you tire of waiting
on me (which I'll understand), please let me know when you do so I can
take this item off my to do list.
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: [PATCH v2] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino
2025-11-21 23:39 ` G. Branden Robinson
@ 2025-11-22 0:53 ` Pali Rohár
0 siblings, 0 replies; 24+ messages in thread
From: Pali Rohár @ 2025-11-22 0:53 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: linux-man, Jan Kara, Alejandro Colomar
On Friday 21 November 2025 17:39:57 G. Branden Robinson wrote:
> Hi Pali,
>
> At 2025-11-21T22:10:28+0100, Pali Rohár wrote:
> > On Wednesday 29 October 2025 20:34:13 Pali Rohár wrote:
> > > On Wednesday 29 October 2025 02:00:39 G. Branden Robinson wrote:
> > > > At 2025-10-29T00:53:06+0100, Pali Rohár wrote:
> > > > > If you are referring to the "bug" then it is written in
> > > > > informative part in RATIONALE section of readdir / POSIX.1-2024.
> > > > > I wrote in my first email in that email thread which Alejandro
> > > > > linked above.
> > > > >
> > > > > Here is direct link to POSIX spec and below is quoted part:
> > > > > https://pubs.opengroup.org/onlinepubs/9799919799/functions/readdir.html
> > > > >
> > > > > "When returning a directory entry for the root of a mounted file
> > > > > system, some historical implementations of readdir() returned
> > > > > the file serial number of the underlying mount point, rather
> > > > > than of the root of the mounted file system. This behavior is
> > > > > considered to be a bug, since the underlying file serial number
> > > > > has no significance to applications."
> [...]
> > > > > That part is in the "informative" section. I have not found
> > > > > anything in normative sections which would disallow usage of
> > > > > that "historical" behavior, so my understanding was that
> > > > > "historical" behavior is conforming too.
> > > > >
> > > > > Please correct me if I'm wrong here, or if it should be
> > > > > understood in different way.
> > > >
> > > > I can't speak for the Austin Group, but I don't read the text
> > > > quite the same way. I interpret it as saying that some historical
> > > > implementations of readdir() would _not_ "return a pointer to a
> > > > structure representing the directory entry at the current position
> > > > in the directory stream specified by the argument dirp, and
> > > > position the directory stream at the next entry." But I suspect
> > > > that's not what it _intends_ to say.
> > > >
> > > > Instead, these implementations "returned [sic] the file serial
> > > > number of the underlying mount point", which I interpret to mean
> > > > that they would return a pointer to a _dirent_ struct whose
> > > > _d_ino_ member was not the file serial number of the file (of
> > > > directory type) named by the _d_name_ member but a pointer to a
> > > > _dirent_ struct whose _d_ino_ member was the file serial number of
> > > > the underlying mount point.
> > > >
> > > > I think there are two conclusions we can reach here.
> > > >
> > > > 1. POSIX.1-2024 might be a little sloppy in the wording of its
> > > > "RATIONALE" for this interface. Presumably no historical
> > > > implementation's readdir() returned a _d_ino_ number directly.
> > > > (Though with all the exuberant integer/pointer punning that
> > > > used to go in Unix, I'd wouldn't bet a lot of money that *no*
> > > > implementation ever did.) I'll wager a nickel that readdir()
> > > > has always, on every implementation, returned a pointer to a
> > > > _dirent_ struct, and it is only the value of the _d_ino_
> > > > member of the pointed-to struct that some implementations have
> > > > populated inconsistently when the entry is a directory that is
> > > > a mount point.
> > > >
> > > > If I'm right, this is an example of the common linguistic
> > > > error of synecdoche: confusing a container with (a subset of)
> > > > its contents.
> > > >
> > > > 2. The behavior POSIX describes as buggy is, in fact,
> > > > nonconforming.
> > >
> > > Only two? I can image that somebody come up with another conclusion.
> > > (just a joke)
>
> I wouldn't bet against your joke proving out in reality. ;-)
>
> > > Anyway, I think that it is important to document the existing Linux
> > > behavior and whether it is POSIX-conforming or not is then second
> > > step. We can drop the information about POSIX conformity from
> > > manpage until we figure out how it is.
> > >
> > > > > Also I have not read all those 4000 pages,
>
> Pity the person who has. :) And mastery of all 4000+ pages should not
> be necessary for an implementor to make sense of a reference entry for a
> single function, command, or data object.
>
> > > > > so maybe there is something hidden. It is quite hard to find
> > > > > information about this topic and that is why I think this should
> > > > > be documented in Linux manpages.
> > > >
> > > > I reckon someone should open a Mantis ticket with the Austin
> > > > Group's issue tracker to get clarity on what I characterized as
> > > > "sloppy" wording. Either it is and we can get the standard
> > > > clarified, or I'm wrong and an authority can point out how.
> > > > (Maybe both!)
> > > >
> > > > I'm subscribed to the austin-group-l reflector and will take an
> > > > action item to file this ticket. I'll try to do within a week.
> > > > (I have a lot of old Unix books and would like to rummage around
> > > > in them for any documented land mines in this area.)
> [...]
> > > Thanks for taking that part. It would be really nice if austin group
> > > can clarify how the whole situation is in a non-confusing way.
> > >
> > > Anyway, inode number is always connected to the specific mounted
> > > filesystem. So when the application is doing something with inodes,
> > > it always needs a pair (dev_t, ino_t) unless inodes belongs to same
> > > fs dev.
> > >
> > > readdir() and getdents() returns just ino_t, and without knowledge
> > > of dev_t, applications cannot use returned ino_t for anything
> > > useful. On "historical" implementations, the dev_t can be fetched
> > > for example by one fstat(dir_fd, &st) call as dev_t would be same
> > > for all readdir and getdents entries. But on non-"historical"
> > > implementation, it would be needed to call stat() on every one
> > > entry. For example /mnt/ directory which usually contains just
> > > mountpoints, will contain entries where each one has inode number 2
> > > (common inode number for root of fs).
> > >
> > > I looked into archives and I have found that this problem was
> > > already discussed in the past. Here are some email threads from
> > > coreutils:
> > > https://lore.kernel.org/lkml/87y6oyhkz8.fsf@meyering.net/t/#u
> > > https://public-inbox.org/bug-coreutils/8763c5wcgn.fsf@meyering.net/t/#u
> > > https://public-inbox.org/bug-coreutils/87iqvi2j0q.fsf@rho.meyering.net/t/#u
> > > https://public-inbox.org/bug-coreutils/87verkborm.fsf@rho.meyering.net/
> > > https://public-inbox.org/bug-coreutils/022320061637.4398.43FDE4D7000110830000112E22007507440A050E040D0C079D0A@comcast.net/
> > >
> > > Maybe they could be a good reference for future discussion by austin
> > > group.
> > >
> > > Just my personal idea: If there would be some xgetdents syscall
> > > (like there statx over stat), it could return both inode numbers
> > > with dev_t and application can take which it wants.
> > >
> > > For example, NFS4's readdir can return both inode numbers (depending
> > > what is client asking). NFSv4.1 spec has nicely documented this
> > > problem with UNIX background of mount point crossing:
> > > https://www.rfc-editor.org/rfc/rfc8881.html#section-5.8.2.23
> > >
> > > Pali
> >
> > Hello Branden, did you have a time fill a ticket to austin group?
>
> Not yet--I procrastinated and got preoccupied by exciting new
> undefined or ambiguously interpretable behavior of GNU troff.
>
> https://www.mail-archive.com/groff@gnu.org/msg20834.html
>
> > If the ticket system is public, could you send a link for reference?
>
> It is public...
>
> https://austingroupbugs.net/view_all_bug_page.php
>
> ...but to file a ticket or comment on one, I believe you need to create
> an account. If you file a ticket yourself because you tire of waiting
> on me (which I'll understand), please let me know when you do so I can
> take this item off my to do list.
>
> Regards,
> Branden
You are experienced with austin group, so I will let this to you.
I'm fine with waiting here.
^ permalink raw reply [flat|nested] 24+ messages in thread
end of thread, other threads:[~2025-11-22 0:53 UTC | newest]
Thread overview: 24+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-05-25 10:33 Improving inode number documentation Pali Rohár
2025-05-25 23:30 ` Alejandro Colomar
2025-05-28 18:25 ` Pali Rohár
2025-05-28 19:03 ` Alejandro Colomar
2025-05-28 19:41 ` Pali Rohár
2025-05-28 19:59 ` Alejandro Colomar
2025-05-28 21:31 ` [RFC v1] man/man3/readdir.3, man/man3type/stat.3type: Improve documentation about .d_ino and .st_ino Alejandro Colomar
2025-05-28 22:54 ` G. Branden Robinson
2025-10-28 23:15 ` [PATCH v2] " Alejandro Colomar
2025-10-28 23:53 ` Pali Rohár
2025-10-29 7:00 ` G. Branden Robinson
2025-10-29 19:34 ` Pali Rohár
2025-11-21 21:10 ` Pali Rohár
2025-11-21 23:39 ` G. Branden Robinson
2025-11-22 0:53 ` Pali Rohár
2025-10-30 11:58 ` Jan Kara
2025-10-31 10:44 ` [PATCH v3] " Alejandro Colomar
2025-10-31 10:56 ` Jan Kara
2025-10-31 11:31 ` Alejandro Colomar
2025-10-31 17:10 ` Pali Rohár
2025-10-31 15:25 ` Darrick J. Wong
2025-11-02 21:17 ` Alejandro Colomar
2025-11-03 11:28 ` Jan Kara
2025-11-09 12:07 ` Alejandro Colomar
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox