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

[Pali Rohár]

On Sunday 16 August 2026 10:03:24 Adhemerval Zanella Netto wrote:
> On 16/08/26 09:15, Pali Rohár wrote:
> > 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.
> 
> From NEWS:
> 
>  464 Version 2.42
>  [...]
>  481 * On Linux, the <termios.h> interface now supports arbitrary baud rates;
>  482   speed_t is redefined to simply be the baud rate specified as an
>  483   unsigned int, which matches the kernel interface.

Nice! So it was finally done.

> > 
> > 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.
> 
> It turned out to be doable, speed_t was already an unsigned int, old binaries
> and the legacy Bxxxx bit-pattern values remain accepted for compatibility.
> 
> The struct termios ABI was preserved (the kernel conversion happens inside
> tcgetattr/tcsetattr).
> 
> There was one regression in the transition (BZ 33340, non-standard baud handling
> of CIBAUD), fixed for 2.43 by 8d999a69936.
> 
> > 
> > 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.
> 
> The incompatibility we have is glibc and kernel struct termios have different
> layout, so mixing them is a recipe for trouble.

Yes, this is what I remember that there are two structures with same
name but different layout and I was passing the wrong one to ioctl and
it did not worked.

> Kudos to H. Peter Anvin for this work.

Thank you very much for this work.