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

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

[H. Peter Anvin]

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>
---
 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 ()
+functions, the baud rate is specified directly as a numeric value.
+.P
+When using the
+.I speed_t
+.BR -speed ()
+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.
+.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.
+Normally, this will disconnect the line.
 .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.
 .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.
+.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

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

[Alejandro Colomar]

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

[PATCH v2 0/4] update termios(3) for glibc 2.42+ and POSIX.1-2024

[H. Peter Anvin]

Trying again:

- Document the new baud rate setting interfaces in glibc 2.42+
- Document deprecations in POSIX.1-2024
- Remove some obsolete descriptions of limitations
- Remove details from termios(3) that really only belong in ioctl_tty(2)

---
 man/man3/termios.3        | 305 +++++++++++++++++++++++-----------------------
 man/man3type/baud_t.3type |   1 +
 man/man3type/cc_t.3type   |  42 ++++++-
 3 files changed, 191 insertions(+), 157 deletions(-)

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

[H. Peter Anvin]

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
-(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 ()
+This bitmask should only be used when invoking the kernel
+.BR ioctl ()
+interface directly.
+.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.
+.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
-.BR TCGET *
+This bitmask should only be used when invoking the kernel
+.BR ioctl ()
+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.
 .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
-.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
+.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.
+.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

[PATCH v2 2/4] man/man3/termios.3: note that setserial(8) rate hacking is dangerous

[H. Peter Anvin]

The use of setserial(8) to modify the 38400 baud rate was an early
hack to support baud rates beyond those standardized by POSIX. As it
is, it is a real trap for applications that actually want to use 38400
bps if a previous user has not cleaned up the setting.

Signed-off-by: H. Peter Anvin <hpa@zytor.com>
---
 man/man3/termios.3 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/man/man3/termios.3 b/man/man3/termios.3
index cd3f9ce4d7c0..f563923fc7cf 100644
--- a/man/man3/termios.3
+++ b/man/man3/termios.3
@@ -1119,7 +1119,9 @@ constant is defined prior to using it.
 The actual bit rate corresponding to
 .B B38400
 may be altered with
-.BR setserial (8).
+.BR setserial (8);
+doing so is 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
-- 
2.54.0

[PATCH v2 3/4] man/man3/termios.3: document that output baud rate has priority

[H. Peter Anvin]

Many devices, including the good old 8250 series UARTs, cannot handle
different input and output baud rates. POSIX defines the output rate
as taking priority, and Linux follows this. Explicitly document this.

Signed-off-by: H. Peter Anvin <hpa@zytor.com>
---
 man/man3/termios.3 | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/man/man3/termios.3 b/man/man3/termios.3
index f563923fc7cf..84b10cb7d68c 100644
--- a/man/man3/termios.3
+++ b/man/man3/termios.3
@@ -1127,6 +1127,10 @@ The input and output baud rates are stored in the
 .I termios
 structure.
 .P
+If a certain device does not support different input and output
+baud rates, the output baud rate is used for both if they are
+programmed to be different.
+.P
 .BR cfgetospeed ()
 and
 .BR cfgetobaud ()
-- 
2.54.0

[PATCH v2 4/4] man/man3/termios.3: document that cfsetispeed(..., 0) is deprecated

[H. Peter Anvin]

POSIX.1-2024 deprecated cfsetispeed(..., 0). This was always rather
confusing, since all other uses of speed_t use the Bnnn symbolic
constants, although B0 == 0 was largely universal.

Document that setting the input speed to numeric-zero meaning the same
as the output speed is deprecated, and applications should explicitly
set it to the same value as the output baud rate instead.

Signed-off-by: H. Peter Anvin <hpa@zytor.com>
---
 man/man3/termios.3 | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/man/man3/termios.3 b/man/man3/termios.3
index 84b10cb7d68c..9a606e689e80 100644
--- a/man/man3/termios.3
+++ b/man/man3/termios.3
@@ -1182,6 +1182,9 @@ even when using
 the input baud rate
 will be equal to the output baud rate.
 .P
+POSIX.1-2024 deprecated this; new code should explicitly set both the
+input and output baud rates to the same value.
+.P
 .BR cfsetspeed ()
 is a 4.4BSD extension.
 It takes the same arguments as
-- 
2.54.0

Re: [PATCH v2 2/4] man/man3/termios.3: note that setserial(8) rate hacking is dangerous

[Alejandro Colomar]

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

Hi,

On 2026-06-29T06:59:06-0700, H. Peter Anvin wrote:
> The use of setserial(8) to modify the 38400 baud rate was an early
> hack to support baud rates beyond those standardized by POSIX. As it
> is, it is a real trap for applications that actually want to use 38400
> bps if a previous user has not cleaned up the setting.
> 
> Signed-off-by: H. Peter Anvin <hpa@zytor.com>

Thanks!  I've applied the patch.


Have a lovely day!
Alex

> ---
>  man/man3/termios.3 | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man3/termios.3 b/man/man3/termios.3
> index cd3f9ce4d7c0..f563923fc7cf 100644
> --- a/man/man3/termios.3
> +++ b/man/man3/termios.3
> @@ -1119,7 +1119,9 @@ constant is defined prior to using it.
>  The actual bit rate corresponding to
>  .B B38400
>  may be altered with
> -.BR setserial (8).
> +.BR setserial (8);
> +doing so is 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
> -- 
> 2.54.0
> 
> 

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

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

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

[Alejandro Colomar]

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

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

[H. Peter Anvin]

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

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

[H. Peter Anvin]

On 2026-06-30 03:39, Alejandro Colomar wrote:
> 
> 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).
> 
OK, I'll try that. I haven't played with the diff algorithms, perhaps because
I naïvely assumed that the default would be the "currently best" algorithm and
ending up using a stale algorithm choice when a new one is introduced is
unfortunate.

	-hpa

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

[Alejandro Colomar]

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

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>

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

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

[Alejandro Colomar]

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

Hi,

On 2026-06-30T13:41:16-0700, H. Peter Anvin wrote:
> On 2026-06-30 03:39, Alejandro Colomar wrote:
> > 
> > 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).
> > 
> OK, I'll try that. I haven't played with the diff algorithms, perhaps because
> I naïvely assumed that the default would be the "currently best" algorithm and

The default is the fastest (I believe), but it's actually bad.  While
there are a few weird cases where the histogram algorithm fails badly,
it regularly results in better diffs.  :)

> ending up using a stale algorithm choice when a new one is introduced is
> unfortunate.

TBH, I don't know why they didn't change the default.


Cheers,
Alex

> 
> 	-hpa
> 

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

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

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

[H. Peter Anvin]

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.

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

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

[G. Branden Robinson]

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

Hi Peter,

At 2026-06-30T13:37:25-0700, H. Peter Anvin wrote:
> On 2026-06-30 03:39, Alejandro Colomar wrote:
> > 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. 
>
[...]
> 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.

Don't worry about lack of troff comfort being a barrier.  Members of
this mailing list can fill in any gaps in your expertise.

That said, you don't need to know much troff to write a man page, and as
a rule, great expertise in troff (especially of the "old school")
seduces a man page author into writing man pages that are _less_
portable and thus render less reliably then they otherwise would.

If you're running groff 1.23 or later, your system should have a
groff_man_style(7) man page that explains only the essentials of troff
knowledge, presents the man(7) macros in detail with examples, and
offers much advice to assist the writer.

I'm acutely interested in any feedback you have on that document.

Pre-rendered versions are available here:

https://man7.org/linux/man-pages/man7/groff_man_style.7.html

...and in PDF as part of the collected groff man pages...

https://www.gnu.org/software/groff/manual/groff-man-pages.pdf

...there.

Regards,
Branden

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

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

[Alejandro Colomar]

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

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.


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>

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