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

[Alejandro Colomar]

Hi,

On 2026-06-30T15:01:02-0700, H. Peter Anvin wrote:
> 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.

I've pushed the patches in a branch:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=t>

I can send patches via email, but I suspect you prefer to pull the
branch.  Let me know if you want the mailed patches.  Please review, and
let me know if I should push these to master.


Have a lovely day!
Alex

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

-- 
<https://www.alejandro-colomar.es>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://sourceware.org/pipermail/libc-alpha/attachments/20260701/4fffbed8/attachment.sig>