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

Alejandro Colomar <[email protected]> Mon, 17 Aug 2026 11:52:54 +0200
Newsgroups	gmane.linux.man,gmane.comp.lib.glibc.alpha
Message-ID	<aoLZuTZjb1L-4CVe@debian>
Hi H. Peter,

> Date: 2026-07-01 16:53:34+0200
> From: Alejandro Colomar <[email protected]>
>
> 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.

Since you didn't respond, and the patches looked good to me, I've pushed
them already to master.

You should be able to fetch the changes and work on your patches on top
of them now.


Have a lovely day!
Alex

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



-- 
<https://www.alejandro-colomar.es>
signature.asc (application/pgp-signature, 833 B)