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

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 14860 bytes --]

Hi,

On 2026-06-29T06:59:05-0700, H. Peter Anvin wrote:
> glibc 2.42+ has a new set of interfaces to get and set arbitrary baud
> rates. Add them to the man pages.
> 
> This removes from termios(3) some details about the baud rate
> constants: they are now an open set in glibc, simply defined to be
> equivalent to their numeric value (e.g. B300 == 300). Thus, stating
> that certain architectures only support certain values is no longer
> correct.
> 
> This also removes references from termios(3) about the interior of the
> ioctl interfaces: the statement about TCSETS2, for example, was always
> incorrect (TCSETS2 doesn't exist on all Linux architectures.) That
> kind of information belongs in ioctl_tty(2), anyway, especially since
> including <linux/termios.h> -> <asm/termbits.h> is not compatible with
> including <termios.h>.
> 
> Signed-off-by: H. Peter Anvin (Intel) <hpa@zytor.com>
> ---
>  man/man3/termios.3        | 318 ++++++++++++++++++--------------------
>  man/man3type/baud_t.3type |   1 +
>  man/man3type/cc_t.3type   |  42 ++++-
>  3 files changed, 193 insertions(+), 168 deletions(-)
>  create mode 100644 man/man3type/baud_t.3type
> 
> diff --git a/man/man3/termios.3 b/man/man3/termios.3
> index 0942cca8084e..cd3f9ce4d7c0 100644
> --- a/man/man3/termios.3
> +++ b/man/man3/termios.3
> @@ -7,7 +7,8 @@
>  .TH termios 3 (date) "Linux man-pages (unreleased)"
>  .SH NAME
>  termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow,
> -cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \-
> +cfmakeraw, cfgetispeed, cfgetospeed, cfsetispeed, cfsetospeed,
> +cfsetspeed, cfgetobaud, cfgetibaud, cfsetibaud, cfsetobaud, cfsetbaud \-
>  get and set terminal attributes, line control, get and set baud rate
>  .SH LIBRARY
>  Standard C library
> @@ -34,6 +35,13 @@ Standard C library
>  .BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed );
>  .BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed );
>  .BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed );
> +.P
> +.BI "baud_t cfgetibaud(const struct termios *" termios_p );
> +.BI "baud_t cfgetobaud(const struct termios *" termios_p );
> +.P
> +.BI "int cfsetibaud(struct termios *" termios_p ", baud_t " baud );
> +.BI "int cfsetobaud(struct termios *" termios_p ", baud_t " baud );
> +.BI "int cfsetbaud(struct termios *" termios_p ", baud_t " baud );
>  .fi
>  .P
>  .RS -4
> @@ -49,6 +57,16 @@ Feature Test Macro Requirements for glibc (see
>      glibc 2.19 and earlier:
>          _BSD_SOURCE
>  .fi
> +.P
> +.BR cfgetibaud (),
> +.BR cfgetobaud (),
> +.BR cfsetibaud (),
> +.BR cfsetobaud (),
> +.BR cfsetbaud ():
> +.nf
> +    Since glibc 2.42:
> +        _GNU_SOURCE
> +.fi
>  .SH DESCRIPTION
>  The termios functions describe a general terminal interface that is
>  provided to control asynchronous communications ports.
> @@ -305,30 +323,33 @@ flag constants:
>  .B _BSD_SOURCE
>  or
>  .BR _SVID_SOURCE ]
> -.TP
> -.B CBAUDEX

Hmmm, even with --diff-algorithm=patience it shows the diff too badly.
I've been trying, and --diff-algorithm=histogram shows a much nicer
diff.  I have the following in my gitconfig:

	[diff]
		algorithm = histogram

I suggest adding that to your gitconfig file.  It is implicitly also
used when you generate patches.  The histogram algorithm works quite
nicely (I've been using for a few years already).

> -(not in POSIX) Extra baud speed mask (1 bit), included in
> -.BR CBAUD .
> -[requires
> -.B _BSD_SOURCE
> -or
> -.BR _SVID_SOURCE ]
>  .IP
> -(POSIX says that the baud speed is stored in the
> -.I termios
> -structure without specifying where precisely, and provides
> -.BR cfgetispeed ()

Why is the above removed in this commit?  I think this belongs in
a separate commit.

> +This bitmask should only be used when invoking the kernel
> +.BR ioctl ()
> +interface directly.

ioctl() should be ioctl(2).

However, is there a specific ioctl that we should mention?  There are
manual pages for the specific ioctl's, so if it's a specific one, we
could refer to that instead.

> +.P
> +Instead, the
> +.BR cfgetospeed (),
> +.BR cfgetobaud (),
> +.BR cfsetospeed ()
>  and
> -.BR cfsetispeed ()
> -for getting at it.
> +.BR cfsetobaud ()
> +functions should be used in application code.

This sentence reads ambiguously; I'd rephrase it so say:

Instead,
application code should use the
.BR ...
functions.

> +.P
>  Some systems use bits selected by
>  .B CBAUD
>  in
>  .IR c_cflag ,
> -other systems use separate fields, for example,
> -.I sg_ispeed
> -and
> -.IR sg_ospeed .)
> +other systems use separate fields, Linux uses
> +.IR both .
> +.TP
> +.B CBAUDEX
> +(not in POSIX) Extra baud speed mask (1 bit), included in
> +.BR CBAUD .
> +[requires
> +.B _BSD_SOURCE
> +or
> +.BR _SVID_SOURCE ]
>  .TP
>  .B CSIZE
>  Character size mask.
> @@ -379,13 +400,17 @@ bits.
>  .B _BSD_SOURCE
>  or
>  .BR _SVID_SOURCE ]
> -(Not implemented in glibc, supported on Linux via

Does this removal mean that it's now implemented in glibc?

> -.BR TCGET *
> +This bitmask should only be used when invoking the kernel

'should' sounds like a recommendation.  If it's unsupported in libc,
then we should say something like

	This bitmask
	is only supported
	when invoking ...

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

> +interface directly (see
> +.BR ioctl_tty (2)).
> +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.

>  .TP
>  .B CMSPAR
>  (not in POSIX)
> @@ -1068,114 +1093,22 @@ until
>  .BR tcsetattr ()
>  is successfully called.
>  .P
> -Setting the speed to
> -.B B0
> +Setting the output speed to zero
>  instructs the modem to "hang up".
> -The actual bit rate corresponding to
> -.B B38400
> -may be altered with
> -.BR setserial (8).
>  .P
> -The input and output baud rates are stored in the
> -.I termios
> -structure.
> -.P
> -.BR cfgetospeed ()
> -returns the output baud rate stored in the
> -.I termios
> -structure
> -pointed to by
> -.IR termios_p .
> -.P
> -.BR cfsetospeed ()
> -sets the output baud rate stored in the
> -.I termios
> -structure
> -pointed to by
> -.I termios_p
> -to
> -.IR speed ,
> -which must be one of these constants:
> -.RS
> -.TP
> -.B B0
> -.TQ
> -.B B50
> -.TQ
> -.B B75
> -.TQ
> -.B B110
> -.TQ
> -.B B134
> -.TQ
> -.B B150
> -.TQ
> -.B B200
> -.TQ
> -.B B300
> -.TQ
> -.B B600
> -.TQ
> -.B B1200
> -.TQ
> -.B B1800
> -.TQ
> -.B B2400
> -.TQ
> -.B B4800
> -.TQ
> -.B B9600
> -.TQ
> -.B B19200
> -.TQ
> -.B B38400
> -.TQ
> -.B B57600
> -.TQ
> -.B B115200
> -.TQ
> -.B B230400
> -.TQ
> -.B B460800
> -.TQ
> -.B B500000
> -.TQ
> -.B B576000
> -.TQ
> -.B B921600
> -.TQ
> -.B B1000000
> -.TQ
> -.B B1152000
> -.TQ
> -.B B1500000
> -.TQ
> -.B B2000000
> -.RE

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

> -.P
> -These constants are additionally supported on the SPARC architecture:
> -.RS
> -.TP
> -.B B76800
> -.TQ
> -.B B153600
> -.TQ
> -.B B307200
> -.TQ
> -.B B614400
> -.RE
> -.P
> -These constants are additionally supported on non-SPARC architectures:
> -.RS
> -.TP
> -.B B2500000
> -.TQ
> -.B B3000000
> -.TQ
> -.B B3500000
> -.TQ
> -.B B4000000
> -.RE
> +When using the
> +.I baud_t
> +.IR * baud()
> +functions, the baud rate is specified directly as a numeric value.
> +.P
> +When using the
> +.I speed_t
> +.IR * speed()
> +functions, the line rate needs to be specified as one of a set of an
> +enumerated macros defined in

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

> +.I <termios.h>
> +of the form
> +.BI B nnn.
>  .P
>  Due to differences between architectures,
>  portable applications should check
> @@ -1183,67 +1116,94 @@ if a particular
>  .BI B nnn
>  constant is defined prior to using it.
>  .P
> +The actual bit rate corresponding to
> +.B B38400
> +may be altered with
> +.BR setserial (8).
> +.P
> +The input and output baud rates are stored in the
> +.I termios
> +structure.

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.


Have a lovely day!
Alex

> +.P
> +.BR cfgetospeed ()
> +and
> +.BR cfgetobaud ()
> +return the output baud rate stored in the
> +.I termios
> +structure
> +pointed to by
> +.IR termios_p .
> +.P
> +.BR cfsetospeed ()
> +and
> +.BR cfsetobaud ()
> +set the output baud rate stored in the
> +.I termios
> +structure pointed to by
> +.IR termios_p .
> +.P
>  The zero baud rate,
> -.BR B0 ,
> +.B B0
> +for
> +.BR cfsetospeed (),
>  is used to terminate the connection.
> -If
> -.B B0
> -is specified,
> +.P
> +If a baud rate of zero is specified,
>  the modem control lines shall no longer be asserted.
>  Normally,
>  this will disconnect the line.
> -.B CBAUDEX
> -is a mask
> -for the speeds beyond those defined in POSIX.1
> -(57600 and above).
> -Thus,
> -.BR B57600 " & " CBAUDEX
> -is nonzero.
> -.P
> -Setting the baud rate to a value other than those defined by
> -.BI B nnn
> -constants is possible via the
> -.B TCSETS2
> -ioctl;
> -see
> -.BR ioctl_tty (2).
>  .P
>  .BR cfgetispeed ()
> -returns the input baud rate stored in the
> +and
> +.BR cfgetobaud ()
> +return the input baud rate stored in the
>  .I termios
>  structure.
>  .P
>  .BR cfsetispeed ()
> +and
> +.BR cfsetibaud ()
>  sets the input baud rate stored in the
>  .I termios
> -structure to
> -.IR speed ,
> -which must be specified as one of the
> -.BI B nnn
> -constants listed above for
> -.BR cfsetospeed ().
> +structure.
> +.P
>  If the input baud rate is set to the literal constant
>  .B 0
>  (not the symbolic constant
> -.BR B0 ),
> -the input baud rate will be
> -equal to the output baud rate.
> +.B B0
> +even when using
> +.BR cfsetispeed ())
> +the input baud rate
> +will be equal to the output baud rate.
>  .P
>  .BR cfsetspeed ()
>  is a 4.4BSD extension.
>  It takes the same arguments as
>  .BR cfsetispeed (),
>  and sets both input and output speed.
> +.P
> +.BR cfsetbaud ()
> +is the equivalent function using the explicitly numeric
> +.I baud_t
> +interface.
>  .SH RETURN VALUE
>  .BR cfgetispeed ()
> -returns the input baud rate stored in the
> +and
> +.BR cfgetobaud ()
> +return the input baud rate stored in the
>  .I termios
> -structure.
> +structure as a
> +.I speed_t
> +enumeration value or a numeric value, respectively.
>  .P
>  .BR cfgetospeed ()
> -returns the output baud rate stored in the
> +and
> +.BR cfgetobaud ()
> +return the output baud rate stored in the
>  .I termios
> -structure.
> +structure as a
> +.I speed_t
> +enumeration value or a numeric value, respectively.
>  .P
>  All other functions return:
>  .TP
> @@ -1289,7 +1249,12 @@ T{
>  .BR cfgetospeed (),
>  .BR cfsetispeed (),
>  .BR cfsetospeed (),
> -.BR cfsetspeed ()
> +.BR cfsetspeed (),
> +.BR cfgetibaud (),
> +.BR cfgetobaud (),
> +.BR cfsetibaud (),
> +.BR cfsetobaud (),
> +.BR cfsetbaud ()
>  T}	Thread safety	MT-Safe
>  .TE
>  .\" FIXME: The markings are different from that in the glibc manual.
> @@ -1328,6 +1293,17 @@ POSIX.1-2008.
>  .TQ
>  .BR cfsetspeed ()
>  BSD.
> +.TP
> +.BR cfgetibaud ()
> +.TQ
> +.BR cfgetobaud ()
> +.TQ
> +.BR cfsetibaud ()
> +.TQ
> +.BR cfsetobaud ()
> +.TQ
> +.BR cfsetbaud ()
> +GNU.
>  .SH HISTORY
>  .TP
>  .BR tcgetattr ()
> @@ -1355,6 +1331,17 @@ POSIX.1-2001.
>  .TQ
>  .BR cfsetspeed ()
>  BSD.
> +.TP
> +.BR cfgetibaud ()
> +.TQ
> +.BR cfgetobaud ()
> +.TQ
> +.BR cfsetibaud ()
> +.TQ
> +.BR cfsetobaud ()
> +.TQ
> +.BR cfsetbaud ()
> +glibc 2.42.
>  .SH NOTES
>  UNIX\ V7 and several later systems have a list of baud rates
>  where after the values
> @@ -1414,6 +1401,7 @@ mask).
>  .BR tty (1),
>  .BR ioctl_console (2),
>  .BR ioctl_tty (2),
> +.BR baud_t (3type),
>  .BR cc_t (3type),
>  .BR speed_t (3type),
>  .BR tcflag_t (3type),
> diff --git a/man/man3type/baud_t.3type b/man/man3type/baud_t.3type
> new file mode 100644
> index 000000000000..26cfd017180e
> --- /dev/null
> +++ b/man/man3type/baud_t.3type
> @@ -0,0 +1 @@
> +.so man3type/cc_t.3type
> diff --git a/man/man3type/cc_t.3type b/man/man3type/cc_t.3type
> index 31c2dbcf8dbe..fa16e4cc3915 100644
> --- a/man/man3type/cc_t.3type
> +++ b/man/man3type/cc_t.3type
> @@ -5,7 +5,8 @@
>  .\"
>  .TH cc_t 3type (date) "Linux man-pages (unreleased)"
>  .SH NAME
> -cc_t, speed_t, tcflag_t \- terminal special characters, baud rates, modes
> +cc_t, baud_t, speed_t, tcflag_t \- terminal special characters, baud
> +rates, modes
>  .SH LIBRARY
>  Standard C library
>  .RI ( libc )
> @@ -13,6 +14,7 @@ Standard C library
>  .nf
>  .B #include <termios.h>
>  .P
> +.BR typedef " /* ... */ " baud_t;
>  .BR typedef " /* ... */ " cc_t;
>  .BR typedef " /* ... */ " speed_t;
>  .BR typedef " /* ... */ " tcflag_t;
> @@ -21,14 +23,48 @@ Standard C library
>  .I cc_t
>  is used for terminal special characters,
>  .I speed_t
> -for baud rates, and
> +for baud rates using
> +.BI B nnn
> +enumerated constants defined in
> +.IR <termios.h> ,
> +.I baud_t
> +for baud rates explicitly defined as numbers, and
>  .I tcflag_t
>  for modes.
>  .P
> -All are unsigned integer types.
> +.IR cc_t ,
> +.IR speed_t ,
> +and
> +.I tcflag_t
> +are all unsigned integer types.
> +.P
> +.I baud_t
> +is a numeric type.
> +.P
> +It is currently the same as
> +.IR speed_t ,
> +but it is not guaranteed to remain so in the future.
>  .SH STANDARDS
> +.TP
> +.I cc_t
> +.TQ
> +.I speed_t
> +.TQ
> +.I tcflag_t
>  POSIX.1-2024.
> +.TP
> +.I baud_t
> +GNU.
>  .SH HISTORY
> +.TP
> +.I cc_t
> +.TQ
> +.I speed_t
> +.TQ
> +.I tcflag_t
>  POSIX.1-1988.
> +.TP
> +.I baud_t
> +glibc 2.42.
>  .SH SEE ALSO
>  .BR termios (3)
> -- 
> 2.54.0
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]