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

Alejandro Colomar <[email protected]> Tue, 30 Jun 2026 23:17:03 +0200
Newsgroups	org.kernel.vger.linux-man
Message-ID	<akQw0mjXu4yTzofX@devuan>
Hi H. Peter,

On 2026-06-30T13:37:25-0700, H. Peter Anvin wrote:
> On 2026-06-30 03:39, Alejandro Colomar wrote:
> > 
> >> +.BR ioctl ()
> > 
> > I think this should probably refer to
> > 
> > 	.BR TC { G , S } ET { A , S , S2 }(2const)
> > 
> > instead, right?
> > 
> > Also, I think this belongs in a separate preceding commit.
> > 
> 
> Yes, I didn't think that belonged in this page though. I have to say I think
> it *really* doesn't belong in termios(3); it just continues the confusion
> behind the fact that these are entirely different interfaces. If someone wants
> to know the details of the ioctl interface, they should look in ioctl_tty(2).
> 
> >> +interface directly (see
> >> +.BR ioctl_tty (2)).
> 
> ... which is why I added this cross-reference.

Ahh, okay.  I got very confused by the diff.  :)

[...]
> > This text isn't really being added.  The weirdness of this diff is in
> > part because of including too many changes in a single commit.  In this
> > case, it seems to be a movement of text from elsewhere.  Separating
> > commits would improve the diff significantly. 
> 
> I'm having some challenges with the structure of this man page in general; I
> feel it contains way too much for a single Unix man page and it makes it hard
> to read. I almost thinking it should be rewritten entirely and refactored.
> Perhaps termios(3type), tc*attr(3), cf*speed(3), cf*baud(3), cfmakeraw(3),
> with the remaining tc*() functions either kept together or broken up. Some of
> the underlying concepts may want to go either into something like tty(7).
> 
> 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?

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

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

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


Have a lovely night!
Alex

> 
> 	-hpa
> 

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