Skip to contentSkip to conversation

man/man3*: document the glibc 2.42+ baud_t termios interface

PATCH Superseded H. Peter Anvin 3 participants 17 messages Jun 29 – Aug 17 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

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

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

---
 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
man/man3/termios.3 +150 -157
index 0942cca8084e..7aa29b39ea73 100644
@@ -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),
man/man3type/baud_t.3type new file +1 -0
new file mode 100644
index 000000000000..26cfd017180e
@@ -0,0 +1 @@
+.so man3type/cc_t.3type
man/man3type/cc_t.3type +39 -3

66 lines not on this page · raw message

Signature · 1 line
2.54.0
#1 lore raw

Hi H. Peter,

Quoted 11 lines · 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. ]

Thanks!

Quoted 131 lines
---
 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
man/man3/termios.3 +48 -25
index 0942cca8084e..7aa29b39ea73 100644
@@ -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

man/man3/termios.3 until · line 1104

Quoted 10 lines
man/man3/termios.3 +9 -1
-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.

man/man3/termios.3 until · line 1109

Quoted 5 lines
man/man3/termios.3 +5 -0
+functions, the baud rate is specified directly as a numeric value.
+.P
+When using the
+.I speed_t
+.BR -speed ()

Same here.

man/man3/termios.3 until · line 1114

Quoted 5 lines
man/man3/termios.3 +5 -0
+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?

Quoted 149 lines
man/man3/termios.3 +21 -109
+.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.

man/man3/termios.3 until · line 1157

Quoted 10 lines
man/man3/termios.3 +2 -7
 .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.

man/man3/termios.3 until · line 1158

Quoted 1 line
man/man3/termios.3 +1 -0
+Normally, this will disconnect the line.

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

Quoted 24 lines
man/man3/termios.3 +7 -7
 .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

man/man3/termios.3 until · line 1182

Quoted 10 lines
man/man3/termios.3 +6 -3
 (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.

Quoted 133 lines
man/man3/termios.3 +46 -5
 .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),
man/man3type/baud_t.3type new file +1 -0
new file mode 100644
index 000000000000..26cfd017180e
@@ -0,0 +1 @@
+.so man3type/cc_t.3type
man/man3type/cc_t.3type +8 -2
index 31c2dbcf8dbe..fa16e4cc3915 100644
@@ -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

man/man3type/cc_t.3type Standard C library · line 39

Quoted 10 lines
man/man3type/cc_t.3type +6 -1
+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//

man/man3type/cc_t.3type Standard C library · line 42

Quoted 3 lines
man/man3type/cc_t.3type +3 -0
+.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

Quoted 31 lines
man/man3type/cc_t.3type +22 -0
+.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)
Signature · 1 line
2.54.0
Signature · 1 line
<https://www.alejandro-colomar.es>
#2 lore raw

v2 cover update termios(3) for glibc 2.42+ and POSIX.1-2024

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(-)
#3 lore raw

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

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

---
 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
man/man3/termios.3 +153 -165
index 0942cca8084e..cd3f9ce4d7c0 100644
@@ -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),
man/man3type/baud_t.3type new file +1 -0
new file mode 100644
index 000000000000..26cfd017180e
@@ -0,0 +1 @@
+.so man3type/cc_t.3type
man/man3type/cc_t.3type +39 -3

66 lines not on this page · raw message

Signature · 1 line
2.54.0
#4 lore raw

Hi,

Quoted 70 lines · 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>.

---
 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
man/man3/termios.3 +19 -1
index 0942cca8084e..cd3f9ce4d7c0 100644
@@ -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.

man/man3/termios.3 flag constants: · line 309

Quoted 5 lines
man/man3/termios.3 +0 -2
@@ -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).

man/man3/termios.3 flag constants: · line 320

Quoted 11 lines
man/man3/termios.3 +0 -10
-(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.

man/man3/termios.3 flag constants: · line 329

Quoted 3 lines
man/man3/termios.3 +3 -0
+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.

man/man3/termios.3 flag constants: · line 337

Quoted 10 lines
man/man3/termios.3 +7 -2
+.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.

Quoted 23 lines
man/man3/termios.3 +11 -4
+.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.

man/man3/termios.3 bits. · line 382

Quoted 4 lines
man/man3/termios.3 +0 -1
@@ -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?

man/man3/termios.3 bits. · line 403

Quoted 2 lines
man/man3/termios.3 +1 -1
-.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 ...

man/man3/termios.3 bits. · line 404

Quoted 1 line
man/man3/termios.3 +1 -0
+.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.

man/man3/termios.3 bits. · line 413

Quoted 13 lines
man/man3/termios.3 +8 -4
+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.

Quoted 82 lines
man/man3/termios.3 +1 -72
 .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

man/man3/termios.3 until · line 1154

Quoted 10 lines
man/man3/termios.3 +0 -10
-.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.

Quoted 24 lines
man/man3/termios.3 +0 -24
-.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

man/man3/termios.3 until · line 1108

Quoted 10 lines
man/man3/termios.3 +10 -0
+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).

Quoted 8 lines
man/man3/termios.3 +3 -0
+.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

man/man3/termios.3 if a particular · line 1126

Quoted 10 lines
man/man3/termios.3 +8 -0
 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

Quoted 258 lines
man/man3/termios.3 +81 -34
+.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),
man/man3type/baud_t.3type new file +1 -0
new file mode 100644
index 000000000000..26cfd017180e
@@ -0,0 +1 @@
+.so man3type/cc_t.3type
man/man3type/cc_t.3type +39 -3
index 31c2dbcf8dbe..fa16e4cc3915 100644
@@ -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)
Signature · 1 line
2.54.0
Signature · 1 line
<https://www.alejandro-colomar.es>
#5 lore raw
Quoted 11 lines · Alejandro Colomar
Quoted 2 lines

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

Quoted 2 lines
Quoted 2 lines

+interface directly (see
+.BR ioctl_tty (2)).

... which is why I added this cross-reference.

Quoted 5 lines
Quoted 5 lines

+Instead, the
+.BR cfgetispeed (),
+.BR cfgetibaud (),
+.BR cfsetispeed ()
and

Quoted 9 lines

man/man3/termios.3 bits. · line 413

Quoted 6 lines

-.BR TCSET *

man/man3/termios.3 +2 -3
-ioctls;
-see
-.BR ioctl_tty (2))
+.BR cfsetibaud ()
+functions should be used in application code.

Same rephrasing as above.

See the same consideration.

Quoted 3 lines

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

OK.

Quoted 10 lines

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,

Quoted 4 lines

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

#6 lore raw

Hi H. Peter,

Quoted 18 lines · H. Peter Anvin
Quoted 11 lines · Alejandro Colomar
Quoted 2 lines

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

Quoted 4 lines
Quoted 2 lines
Quoted 2 lines

+interface directly (see
+.BR ioctl_tty (2)).

... which is why I added this cross-reference.

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

[...]

Quoted 12 lines
Quoted 4 lines

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

Quoted 5 lines

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?

Quoted 12 lines

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.

Quoted 6 lines

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?

Quoted 6 lines

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.

Quoted 11 lines

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

Quoted 3 lines

-hpa

Signature · 1 line
<https://www.alejandro-colomar.es>
#7 lore raw
Quoted 7 lines · Alejandro Colomar
Quoted 6 lines

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.

Quoted 6 lines

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.

Quoted 19 lines
Quoted 12 lines

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.

Quoted 6 lines

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.

Quoted 3 lines

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.

Quoted 10 lines
Quoted 6 lines

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.

Quoted 18 lines
Quoted 11 lines

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.

#8 lore raw

Hi,

Quoted 8 lines · H. Peter Anvin
Quoted 7 lines · Alejandro Colomar
Quoted 6 lines

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.

Quoted 8 lines
Quoted 6 lines

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

Quoted 59 lines
Quoted 20 lines
Quoted 13 lines

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.

Quoted 6 lines

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.

Quoted 3 lines

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.

Quoted 10 lines
Quoted 6 lines

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.

Quoted 18 lines
Quoted 11 lines

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.

Signature · 1 line
<https://www.alejandro-colomar.es>
#9 lore raw

Hi H. Peter,

Quoted 23 lines

Date: 2026-07-01 16:53:34+0200
From: Alejandro Colomar <[email protected]>

Hi,

Quoted 8 lines · H. Peter Anvin
Quoted 7 lines · Alejandro Colomar
Quoted 6 lines

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.

Quoted 8 lines
Quoted 6 lines

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.

Quoted 7 lines

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.

Since you didn't respond, and the patches looked good to me, I've pushed them already to master.

You should be able to fetch the changes and work on your patches on top of them now.

Have a lovely day!
Alex

Quoted 67 lines

Have a lovely day!
Alex

Quoted 59 lines
Quoted 20 lines
Quoted 13 lines

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.

Quoted 6 lines

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.

Quoted 3 lines

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.

Quoted 10 lines
Quoted 6 lines

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.

Quoted 18 lines
Quoted 11 lines

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.

Signature · 1 line
<https://www.alejandro-colomar.es>
Signature · 1 line
<https://www.alejandro-colomar.es>
#10 lore raw
In reply to H. Peter Anvin

Hi Peter,

Quoted 6 lines · H. Peter Anvin
Quoted 4 lines · Alejandro Colomar

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.

[...]

Quoted 6 lines

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

#11 lore raw
In reply to Alejandro Colomar
Quoted 5 lines · Alejandro Colomar

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:

Quoted 7 lines
	[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

#12 lore raw

Hi,

Quoted 9 lines · H. Peter Anvin
Quoted 8 lines · Alejandro Colomar

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
Quoted 6 lines
Quoted 4 lines

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

Quoted 2 lines

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

Quoted 3 lines

-hpa

Signature · 1 line
<https://www.alejandro-colomar.es>
#13 lore raw

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

In reply to 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.

---
 man/man3/termios.3 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
man/man3/termios.3 +3 -1
index cd3f9ce4d7c0..f563923fc7cf 100644
@@ -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
Signature · 1 line
2.54.0
#14 lore raw

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

Hi,

Quoted 6 lines · 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.

Thanks! I've applied the patch.

Have a lovely day!
Alex

Quoted 23 lines
---
 man/man3/termios.3 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
man/man3/termios.3 +3 -1
index cd3f9ce4d7c0..f563923fc7cf 100644
@@ -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
Signature · 1 line
2.54.0
Signature · 1 line
<https://www.alejandro-colomar.es>
#15 lore raw

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

In reply to 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.

---
 man/man3/termios.3 | 4 ++++
 1 file changed, 4 insertions(+)
man/man3/termios.3 +4 -0
index f563923fc7cf..84b10cb7d68c 100644
@@ -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 ()
Signature · 1 line
2.54.0
#16 lore raw

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

In reply to 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.

---
 man/man3/termios.3 | 3 +++
 1 file changed, 3 insertions(+)
man/man3/termios.3 +3 -0
index 84b10cb7d68c..9a606e689e80 100644
@@ -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
Signature · 1 line
2.54.0