I was reading tty(4) manual page, in particular the description for TIOCGWINSZ request. In the end of it it says "The winsize structure is defined in <sys/ioctl.h>.". I never worked with winsize structure, so I didn't know what's in it and decided to have a look. I did a quick search for "winsize" in /usr/include/sys/ioctl.h, but it didn't give any result. I figured that struct winsize is actually defined in /usr/include/sys/_winsize.h and then it's included in ioctl.h like that: _winsize.h -> ttycom.h -> ioctl.h. So it's true that winsize is defined in ioctl.h, but it's actually not that helpful if you want to look at the structure itself. Honestly, I'm not sure: maybe it's normal for manual pages to refer structures in such way; I don't have much knowledge about header files internals and the way they should be named in the manual pages, maybe their locations are machine-dependent. However, I'm thinking maybe it would be good to mention the <sys/_winsize.h> in the page too, so that it will be clear for one who wants to look at the structure where to go.
The man page references the header that needs to be included into C source to get the definition. All _XXX.h headers are internal and not supposed to be included directly. Typically they are introduced to split larger header and allow some definition to appear in multiple top-level headers without code duplication. That said, the change that could improve the man page is to say that the structure definition is made available by inclusion of sys/ioctl.h, instead of it being defined in the header.
Thank you for the explanation, Konstantin. Yes, I agree, this notion would make things clearer. But can't we still also mention the file where the struct is actually defined? In my opinion, it pretty fits the concept of the manual page and makes it much easier to follow. We don't include the structure description in the page itself, but just give a good reference if someone wants to get more details about the struct. I think this will be much easier for reader than manually "unwrapping" the chain of header files.
(In reply to Artem Bunichev from comment #2) Again, the headers named with the underscore prefix are private. If you think that having the definition of the structure exposed to the man page reader is important, then perhaps add its edited definition to the man page in verbatim block.
Created attachment 257272 [details] tty.4: correct description of header file. I just found the tcgetwinsize(3) page, where winsize structure is described and its definition is present. I suppose that then it's not necessary to include the winsize definition in tty(4). I made the change we've discussed and edited the text about <sys/ioctl.h>.
I remember that the usual wording is "is provided by" not "avaliable via".
Hi Artem, While I understand your challenge I don't think that the idea to have all and every definition described in man pages is a maintainable and viable solution. Moreover, sometime it is desirable to hide internals from the reader. For instance, we don't want anyone to have _winsize.h included in their sources. Btw, /usr/src/Makefile support cscope(1), the tool I personally found very valuable for such tasks.
Created attachment 257276 [details] updated patch for tty(4). "provided by" it is! :)
(In reply to Maxim Konovalov from comment #6) Hi Maxim, Well, yeah, I must agree that it's not that easy to have every thing documented in the manuals. And thank you for telling about cscope(1)! Cool thing indeed.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=8d4a464412d0bd9f214ecefa2298cbe7f85f2c0f commit 8d4a464412d0bd9f214ecefa2298cbe7f85f2c0f Author: artembunichev <artembunichev@zohomail.com> AuthorDate: 2025-02-05 20:43:46 +0000 Commit: Konstantin Belousov <kib@FreeBSD.org> CommitDate: 2025-02-05 21:41:31 +0000 tty.4: correct description of header file PR: 284596 MFC after: 3 days share/man/man4/tty.4 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
A commit in branch stable/14 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=743d6ba0f29045a9a1d087a798520b8e3505205d commit 743d6ba0f29045a9a1d087a798520b8e3505205d Author: artembunichev <artembunichev@zohomail.com> AuthorDate: 2025-02-05 20:43:46 +0000 Commit: Konstantin Belousov <kib@FreeBSD.org> CommitDate: 2025-02-08 00:26:55 +0000 tty.4: correct description of header file PR: 284596 (cherry picked from commit 8d4a464412d0bd9f214ecefa2298cbe7f85f2c0f) share/man/man4/tty.4 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)