[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:
signature.asc
Description: PGP signature
