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

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

[Guillem Jover]

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

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

[Andreas Schwab]

On Aug 16 2026, Guillem Jover wrote:

> the <asm/*> headers are Linux specific,

As are the ioctls.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

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

[Pali Rohár]

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.

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.

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.

Pali

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

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

[Pali Rohár]

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.

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

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

[H. Peter Anvin]

On August 16, 2026 12:49:59 PM PDT, "H. Peter Anvin" <hpa@zytor.com> wrote:
>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.
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.

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

[Alejandro Colomar]

[-- 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 --]

Re: 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?

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

[Alejandro Colomar]

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

Hi H. Peter,

> Date: 2026-08-17 02:23:39-0700
> From: "H. Peter Anvin" <hpa@zytor.com>
>
[...]
> >So, any suggested changes to the manual pages?
> >
> >
> >Have a lovely day!
> >Alex
> >
> 
> Didn't we talk about this about two months ago?

Yes, I pushed an extensive set of changes to the manual pages, splitting
termios(3) into many small pages.

I'm now waiting for your patches to the smaller pages.  I've replied to
that old thread too.


Cheers,
Alex

> 

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

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