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

[Adhemerval Zanella Netto]

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.

> 
> 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.

Kudos to H. Peter Anvin for this work.