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

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.

>> +Instead, the
>> +.BR cfgetispeed (),
>> +.BR cfgetibaud (),
>> +.BR cfsetispeed ()
>>  and
>> -.BR TCSET *
>> -ioctls;
>> -see
>> -.BR ioctl_tty (2))
>> +.BR cfsetibaud ()
>> +functions should be used in application code.
> 
> Same rephrasing as above.
> 

See the same consideration.

> 
> The removal of old documentation should be done in a separate commit.
> 

OK.

> 
> There seems to be some wording inconsistency here.  It's hard to read.
> Maybe:
> 
> 	functions,
> 	the line rate needs to be specified
> 	as one of a set of enumerated macros
> 	defined in
> 
> That is, 'an' should be removed (and semantic newlines can be improved).

OK,


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

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.

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

	-hpa