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

[Alejandro Colomar <alx@kernel.org>]

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

Hi H. Peter,

On 2026-06-28T23:02:26-0700, H. Peter Anvin wrote:
> glibc 2.42+ has a new set of interfaces to get and set arbitrary baud
> rates as numbers rather than strange enumeration constants. Add them
> to the man pages.
> 
> This also removes the specific list of Bxxx constants, as they no
> longer match the list of constants supported by glibc, which is now an
> open set anyway.
> 
> [ I was the developer of that interface. ]
> 
> Signed-off-by: H. Peter Anvin (Intel) <hpa@zytor.com>

Thanks!

> ---
>  man/man3/termios.3        | 307 +++++++++++++++++++-------------------
>  man/man3type/baud_t.3type |   1 +
>  man/man3type/cc_t.3type   |  42 +++++-
>  3 files changed, 190 insertions(+), 160 deletions(-)
>  create mode 100644 man/man3type/baud_t.3type
> 
> diff --git a/man/man3/termios.3 b/man/man3/termios.3
> index 0942cca8084e..7aa29b39ea73 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,6 +323,25 @@ flag constants:
>  .B _BSD_SOURCE
>  or
>  .BR _SVID_SOURCE ]
> +.IP
> +This bitmask should only be used when invoking the kernel
> +.BR ioctl ()
> +interface directly.
> +.P
> +The
> +.BR cfgetospeed (),
> +.BR cfgetobaud (),
> +.BR cfsetospeed ()
> +and
> +.BR cfsetobaud ()
> +functions should instead.
> +.P
> +Some systems use bits selected by
> +.B CBAUD
> +in
> +.IR c_cflag ,
> +other systems use separate fields, Linux uses
> +.IR both .
>  .TP
>  .B CBAUDEX
>  (not in POSIX) Extra baud speed mask (1 bit), included in
> @@ -313,22 +350,6 @@ or
>  .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 ()
> -and
> -.BR cfsetispeed ()
> -for getting at it.
> -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 .)
>  .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
> -.BR TCGET *
> +This bitmask should only be used when invoking the kernel
> +.BR ioctl ()
> +interface directly (see
> +.BR ioctl_tty (2)).
> +The
> +.BR cfgetispeed (),
> +.BR cfgetibaud (),
> +.BR cfsetispeed ()
>  and
> -.BR TCSET *
> -ioctls;
> -see
> -.BR ioctl_tty (2))
> +.BR cfsetibaud ()
> +functions should instead.
>  .TP
>  .B CMSPAR
>  (not in POSIX)
> @@ -1068,182 +1093,122 @@ until
>  .BR tcsetattr ()
>  is successfully called.
>  .P
> -Setting the speed to
> -.B B0
> -instructs the modem to "hang up".
> +Setting the output speed to zero instructs the modem to "hang up".
> +.P
> +If a certain device does not support different input and output
> +speeds, the output speed takes precedence if the user tries to set
> +them to different values.
> +.P
> +When using the
> +.I baud_t
> +.BR -baud ()

Maybe

	.IR * baud()

The '*' is more common for denoting an arbitrary set of characters (as
in globs).  Also, since this is not an actual function name, it should
not be in bold.  And since * is a variable part, it should be in
italics.

> +functions, the baud rate is specified directly as a numeric value.
> +.P
> +When using the
> +.I speed_t
> +.BR -speed ()

Same here.

> +functions, the line rate needs to be specified as one of a set of an
> +enumerated macros defined in
> +.I <termios.h>
> +of the form
> +.BI B nnn.

Are Bnnn macros considered deprecated, or are they still intended for
new code?

> +.P
> +Due to differences between architectures,
> +portable applications should check
> +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).
> +.BR setserial (8);
> +doing so is however discouraged as it may break other applications
> +later trying to use the same serial port.
>  .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
> +and
> +.BR cfgetobaud ()
> +return 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
> +and
> +.BR cfsetobaud ()
> +set 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
> -.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
> -.P
> -Due to differences between architectures,
> -portable applications should check
> -if a particular
> -.BI B nnn
> -constant is defined prior to using it.
> +structure pointed to by
> +.IR termios_p .
>  .P
>  The zero baud rate,
> -.BR B0 ,
> -is used to terminate the connection.
> -If
>  .B B0
> -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.
> +for
> +.BR cfsetospeed (),
> +is used to terminate the connection.
>  .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).
> +If a baud rate of zero is specified,
> +the modem control lines shall no longer be asserted.

I wonder if you can pass --diff-algorithm=patience to
git-format-patch(1) when generating the patch.  The diff seems to
include text that hasn't really changed.

> +Normally, this will disconnect the line.

Please don't change the whitespace unnecessarily; this complicates the
diff unnecessarily.

>  .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
> +POSIX.1-2024 considers this functionality deprecated.

Text talking about deprecation should be in a different commit than one
that adds new interfaces.  Please consider breaking this commit in two
or more commits that do just one thing.

>  .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 +1254,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 +1298,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 +1336,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 +1406,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.

'all' is superfluous here.  Less text will be easier to read.  Thus,
s/all//

> +.P
> +.I baud_t
> +is a numeric type.

By numeric you mean that it might be a floating type?  If not, then it
should be specified as an integer type.  If you really mean that it
might be a float/double, then the standard term is 'arithmetic types'
(see <https://port70.net/~nsz/c/c11/n1570.html#6.2.5p18>).


Have a lovely day!
Alex

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