Re: [PATCH v2 1/4] man/man3*: document the glibc 2.42+ baud_t termios interface

On 2026-06-30 14:17, Alejandro Colomar wrote:
>>
>> However, doing that using the broken-up diffs that you want would be very
>> difficult at least for me, as I'm neither particularly comfortable with troff
>> nor a good technical writer, plus that this is a "spare time" project for me.
>> I would be willing to try to submit such a rewrite, but if that means
>> refactoring it into small diffs it isn't going to happen.
> 
> I can break the page myself.  I can use the break points that you told
> me above.
> 
> Do you prefer that I break the page in small bits and then you apply
> your patches on top of that?  Or would that be inconvenient for you?
> 

No, that would probably be the best way forward.

>> In fact, I *did* rewrite and restructure significant chunks of the termios
>> chapter of the glibc texinfo manual during this work partly due to the sheer
>> number of errors that had collected over the years, partly because the clarity
>> was muffled by unclear language caused by wanting to pretend that the tty
>> interface is anything other than an emulation of an RS232 interface.
>> Explaining it as an *abstraction* of an RS232 interface that may be real or
>> virtual really clarifies a whole lot of things.
>>
>> As such, I would be very very interested in what you think of the formulations
>> I used in that document. Perhaps we could use some of them if you think that
>> such a rewrite would be worthwhile.
>>
>> I *very* strongly believe, however, that the ioctl_tty(2) interface needs to
>> be kept separate and that we shouldn't muddle that into the termios(3) man
>> page. It's possible that we should be factoring out the termios parts of the
>> kernel interface into ioctl_termios(2), as the rest of the tty ioctls
>> generally coexist just fine with the termios(3) interface and thus fall into a
>> separate class.
> 
> Okay; I'll try to do that, and send the patches to you for a review of
> the overall break points.  When I'm finished, you can rewrite the text
> as you wish.  Does that sound good?

Sounds great to me.

>>
>> Speaking of ioctl_tty(2)...
>>
>> One thing I have wondered about is that in ioctl_tty(2) you state to use
>> <asm/termbits.h> as the include, but in practice applications use
>> <linux/termios.h>.
> 
> IIRC, we weren't sure which header was preferred, so I put one that
> looked correct.  I never used these interfaces myself, so it's probably
> good to change it.  Feel free to send patches for that.

Yep, I will look at ioctl_tty(2) and its fellows, but I think that needs 
to be separate.

>> There are considerable subtleties in using the kernel
>> termios interfaces, as they are architecture-specific *AND* mutually exclusive
>> from the glibc one (neither the types nor the constants necessarily match up.)
>> On PowerPC, for historical reasons, the ioctl values in <sys/ioctl.h> for
>> TC[GS]ETS* don't even match the kernel ones and are intercepted in glibc and
>> redirected to the *glibc* tc[gs]etattr() functions, expecting the glibc
>> structure which I do believe is different in that it has a different number of
>> reserved special character slots which also pushes out the c_ispeed and
>> c_ospeed members.
>>
>> Let me know what you think.
> 
> I mostly agree with everything, I think.  There's too much to be
> specific, so maybe I should split the page, and then we can discuss more
> concrete patches.
> 
> I'll wait for your confirmation to start breaking the page into many
> bits.