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

[H. Peter Anvin]

On August 17, 2026 2:03:09 AM PDT, Alejandro Colomar <alx@kernel.org> wrote:
>Hi all,
>
>> Date: 2026-08-16 12:49:59-0700
>> From: "H. Peter Anvin" <hpa@zytor.com>
>>
>> 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.
>
>So, any suggested changes to the manual pages?
>
>
>Have a lovely day!
>Alex
>

Didn't we talk about this about two months ago?