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

On August 16, 2026 12:49:59 PM PDT, "H. Peter Anvin" <[email protected]> wrote:
>On August 16, 2026 6:19:55 AM PDT, "Pali Rohár" <[email protected]> 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.
I also am expecting that at some point we are going to represent more than 4 Gbps. This is why baud_t is explicitly *not* defined to be an integer; it would be far more logical to make the kernel interface contain a scaling factor – in other words, floating point.

A single precision floating-point number (with a suitable cflag to indicate that encoding) would fit quite nicely and be able to encode up to 3.4×10³⁸ bps to a precision of ±60 ppb both of which provide enormous headroom for any real-life application.

It also gives *downward* headroom for extremely slow baud rates, like "B134" which is really supposed to be 134.5 or the teletype 45.45. Extremely low rates can be important in some specialized applications like radio.

This doesn't mean the kernel would use floating-point math, just that since the format exists we might as well use it.

Most advanced hardware implementations these days end up with a base frequency which can be chosen from a limited number of prescaler values and/or base oscillators (often rather arbitrary), a multiplier, and a divider, all of which have a specific limited ranges. These values can sometimes be fractional and nearly always includes a fixed constant like 16, but from an algorithm point of view that can always be absorbed into the base frequency.