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

[H. Peter Anvin]

On August 16, 2026 6:19:55 AM PDT, "Pali Rohár" <pali@kernel.org> wrote:
>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.

It is not just the structure but the Bxxx and several other constants as well. My advice is to use <linux/termios.h> in a separate translation unit if one is to use the ioctl interface directly. 

It is *also* important to note that not all platforms have the TC*ETS*2 ioctls, and on powerpc the ioctl numbers in glibc are different. Virtually all code I have seen gets this wrong, together with the handling of CIBAUD.

glibc now also has an explicitly numeric interface, with -baud instead of -speed; the hope is that POSIX will eventually adopt that interface too.