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

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 4890 bytes --]

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

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]