Re: On <asm/termbits.h> and <asm/termios.h> usage in man pages

["Pali Rohár" <pali@kernel.org>]

On Sunday 16 August 2026 13:54:24 Guillem Jover wrote:
> Hi!
> 
> I was just refreshing my mind about documentation around TIOCGWINSZ,
> and noticed the weird <asm/termbits.h> and <asm/termios.h> usage in
> various ioctl man pages.
> 
> These originate from commit c023614536251bd6b47a0eab45ab3bcfd2ad9ec2,
> where it states that the «struct termios» definitions in the
> <termios.h> header are incompatible with the defined ioctl calls.
> 
> This seems problematic, for one because the <asm/*> headers are Linux
> specific, so they reduce portability for all these macros, even when
> they do not rely or make use of «struct termios». For another because if
> there is a problem in glibc with the interaction between «struct termios»
> and the ioctl calls, then that should be fixed in glibc, instead of
> adding these workarounds in the man pages.
> 
> It seems the problem is that in glibc «struct termios» maps to the Linux
> «struct termios2», but the macros for ioctls that use «struct termios»
> do not match (for example TCGETS instead of TCGETS2)?
> 
> 
> I think this should be fixed both in glibc, to make the definitions
> coherent, and in man-pages to not use those Linux-only headers where
> it is not necessary and then on a second stage to point back to the
> portable headers once glibc has been fixed?
> 
> Thanks,
> Guillem

Hello! The main problem is that glibc has different API and ABI for
termios functions and structures than the raw Linux syscalls.

And at the same time glibc does not provide API for all functionality
which Linux syscall provides.

And POSIX, nor GNU does not provide functions / API for setting
arbitrary baudrate on the tty device.

So all this functionality and information in the manpage are Linux
specific, they are not portable.

Therefore in this case it is necessary for Linux specific thing to use
Linux-only headers.

When I was looking at it in the past, I had feeling that glibc cannot
easily fix it because it would break existing glibc ABI and contract for
all existing applications.

But once glibc provides API for setting the arbitrary baudrate on tty
device, we can improve the manpages. But as this did not happened
for 30 years (in past I saw that there were some attempts), I doubt that
it would be in near future. It is not easy thing.

Pali