Skip to contentSkip to conversation

ioctl_tty.2: Fix information about header include file

PATCH Superseded Pali Rohár 2 participants 7 messages Jul 30, 2021 – Sep 10, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 ioctl_tty.2: Fix information about header include file

Header file termios.h contains incompatible definitions for linux ioctl calls. Correct definitions are exported by header file linux/termios.h but this file conflicts with sys/ioctl.h header file (required for ioctl() call). Therefore include direct asm header file asm/termbits.h which contains compatible definitions and structures for ioctl calls.

---
 man2/ioctl_tty.2 | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)
man2/ioctl_tty.2 +15 -2
index c1875530f0b1..91aceddb7828 100644
@@ -11,8 +11,8 @@ ioctl_tty \- ioctls for terminals and serial lines
 .SH SYNOPSIS
 .nf
 .B #include <sys/ioctl.h>
-.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
-.BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
+.BR "#include <asm/termbits.h>"   "   /* Definition of " struct " " termios ", " struct " " termios2 ","
+.BR "                              " " " BOTHER ", " CLOCAL ", and " TC* { FLUSH , ON , OFF "} constants */"
 .PP
 .BI "int ioctl(int " fd ", int " cmd ", ...);"
 .fi
@@ -31,6 +31,19 @@ makes for nonportable programs.
 Use the POSIX interface described in
 .BR termios (3)
 whenever possible.
+.PP
+Please note that
+.B struct termios
+from
+.B #include <asm/termbits.h>
+is different and incompatible with
+.B struct termios
+from
+.BR "#include <termios.h>" .
+These ioctl calls require
+.B struct termios
+from
+.BR "#include <asm/termbits.h>" .
 .SS Get and set terminal attributes
 .TP
 .B TCGETS
Signature · 1 line
2.20.1
#1 lore raw

Hi Pali,

Quoted 7 lines · Pali Rohár

Header file termios.h contains incompatible definitions for linux ioctl calls. Correct definitions are exported by header file linux/termios.h but this file conflicts with sys/ioctl.h header file (required for ioctl() call). Therefore include direct asm header file asm/termbits.h which contains compatible definitions and structures for ioctl calls.

Thanks for the patch. I'll wait to see if someone from glibc reviews the change. I'll add some comments about the formatting for now.

Cheers,

Alex

Quoted 9 lines
---
  man2/ioctl_tty.2 | 17 +++++++++++++++--
  1 file changed, 15 insertions(+), 2 deletions(-)
man2/ioctl_tty.2 +0 -0
index c1875530f0b1..91aceddb7828 100644

man2/ioctl_tty.2 ioctl_tty \- ioctls for terminals and serial lines · line 14

Quoted 6 lines
man2/ioctl_tty.2 +1 -2
@@ -11,8 +11,8 @@ ioctl_tty \- ioctls for terminals and serial lines
  .SH SYNOPSIS
  .nf
  .B #include <sys/ioctl.h>
-.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
-.BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
+.BR "#include <asm/termbits.h>"   "   /* Definition of " struct " " termios ", " struct " " termios2 ","

A single space between tokens is enough: s/>" "/>" "/

Join related tokens: s/struct " " termios/"struct termios"/

Tokens without spaces don't need quoting: s/","$/,/

man2/ioctl_tty.2 ioctl_tty \- ioctls for terminals and serial lines · line 15

Quoted 1 line
man2/ioctl_tty.2 +1 -0
+.BR "                              " " " BOTHER ", " CLOCAL ", and " TC* { FLUSH , ON , OFF "} constants */"

Please format everything into at most 80 columns, and preferably 78.

Right now I see:

[
SYNOPSIS

       #include <sys/ioctl.h>
       #include <asm/termbits.h>   /* Definition of struct termios, 

struct termios2,
BOTHER, CLOCAL, and
TC*{FLUSH,ON,OFF} constants */

       int ioctl(int fd, int cmd, ...);

]

Maybe break between the 2 structs, and after that "and".
Also, I'd add an "and" just before the constants to make clear that "constants" only applies to them.

Quoted 24 lines
man2/ioctl_tty.2 +13 -0
  .PP
  .BI "int ioctl(int " fd ", int " cmd ", ...);"
  .fi
@@ -31,6 +31,19 @@ makes for nonportable programs.
  Use the POSIX interface described in
  .BR termios (3)
  whenever possible.
+.PP
+Please note that
+.B struct termios
+from
+.B #include <asm/termbits.h>
+is different and incompatible with
+.B struct termios
+from
+.BR "#include <termios.h>" .
+These ioctl calls require
+.B struct termios
+from
+.BR "#include <asm/termbits.h>" .
  .SS Get and set terminal attributes
  .TP
  .B TCGETS
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#2 lore raw

PATCH v2 1/1 ioctl_tty.2: Fix information about header include file

In reply to Pali Rohár

Header file termios.h contains incompatible definitions for linux ioctl calls. Correct definitions are exported by header file linux/termios.h but this file conflicts with sys/ioctl.h header file (required for ioctl() call). Therefore include direct asm header file asm/termbits.h which contains compatible definitions and structures for ioctl calls.

---
Changes in v2:
* Reformat SYNOPSIS for 80 chars per line

---
 man2/ioctl_tty.2 | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)
man2/ioctl_tty.2 +17 -2
index 771a9a470bf0..ecbae4f887c4 100644
@@ -11,8 +11,10 @@ ioctl_tty \- ioctls for terminals and serial lines
 .SH SYNOPSIS
 .nf
 .B #include <sys/ioctl.h>
-.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
-.BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
+.BR "#include <asm/termbits.h>" "   /* Definition of " "struct termios" ,
+.BR    "                               struct termios2" ", and"
+.BR    "                               Bnn" ", " BOTHER ", " CBAUD ", " CLOCAL ,
+.BR    "                               TC*" { FLUSH , ON , OFF "} and other constants */"
 .PP
 .BI "int ioctl(int " fd ", int " cmd ", ...);"
 .fi
@@ -31,6 +33,19 @@ makes for nonportable programs.
 Use the POSIX interface described in
 .BR termios (3)
 whenever possible.
+.PP
+Please note that
+.B struct termios
+from
+.B #include <asm/termbits.h>
+is different and incompatible with
+.B struct termios
+from
+.BR "#include <termios.h>" .
+These ioctl calls require
+.B struct termios
+from
+.BR "#include <asm/termbits.h>" .
 .SS Get and set terminal attributes
 .TP
 .B TCGETS
Signature · 1 line
2.20.1
#3 lore raw

Hi Pali,

Quoted 5 lines · Pali Rohár

Header file termios.h contains incompatible definitions for linux ioctl calls. Correct definitions are exported by header file linux/termios.h but this file conflicts with sys/ioctl.h header file (required for ioctl() call). Therefore include direct asm header file asm/termbits.h which contains compatible definitions and structures for ioctl calls.

No one screamed so far, so I was going to apply this one, but I just noticed a minor formatting issue; see below.

Thanks,

Alex

Quoted 28 lines

---
Changes in v2:
* Reformat SYNOPSIS for 80 chars per line

---
  man2/ioctl_tty.2 | 19 +++++++++++++++++--
  1 file changed, 17 insertions(+), 2 deletions(-)
man2/ioctl_tty.2 +4 -2
index 771a9a470bf0..ecbae4f887c4 100644
@@ -11,8 +11,10 @@ ioctl_tty \- ioctls for terminals and serial lines
  .SH SYNOPSIS
  .nf
  .B #include <sys/ioctl.h>
-.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
-.BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
+.BR "#include <asm/termbits.h>" "   /* Definition of " "struct termios" ,
+.BR    "                               struct termios2" ", and"
+.BR    "                               Bnn" ", " BOTHER ", " CBAUD ", " CLOCAL ,
+.BR    "                               TC*" { FLUSH , ON , OFF "} and other constants */"
  .PP
  .BI "int ioctl(int " fd ", int " cmd ", ...);"
  .fi

man2/ioctl_tty.2 makes for nonportable programs. · line 40

Quoted 8 lines
man2/ioctl_tty.2 +5 -0
@@ -31,6 +33,19 @@ makes for nonportable programs.
  Use the POSIX interface described in
  .BR termios (3)
  whenever possible.
+.PP
+Please note that
+.B struct termios
+from
+.B #include <asm/termbits.h>

Instead, just (with no "#include"):

.I <asm/termbits.h>

See man-pages(7):
Formatting conventions (general)
[...]

Filenames (whether pathnames, or references to header files) are always in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where included files are in bold (e.g., #include <stdio.h>). When referring to a standard header file include, specify the header file surrounded by angle brackets, in the usual C way (e.g., <stdio.h>).

man2/ioctl_tty.2 makes for nonportable programs. · line 44

Quoted 4 lines
man2/ioctl_tty.2 +4 -0
+is different and incompatible with
+.B struct termios
+from
+.BR "#include <termios.h>" .

ditto

man2/ioctl_tty.2 makes for nonportable programs. · line 48

Quoted 4 lines
man2/ioctl_tty.2 +4 -0
+These ioctl calls require
+.B struct termios
+from
+.BR "#include <asm/termbits.h>" .

ditto

Quoted 4 lines
man2/ioctl_tty.2 +0 -0
  .SS Get and set terminal attributes
  .TP
  .B TCGETS
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#4 lore raw

PATCH v3 1/1 ioctl_tty.2: Fix information about header include file

Header file termios.h contains incompatible definitions for linux ioctl calls. Correct definitions are exported by header file linux/termios.h but this file conflicts with sys/ioctl.h header file (required for ioctl() call). Therefore include direct asm header file asm/termbits.h which contains compatible definitions and structures for ioctl calls.

---
Changes in v3:
* Use .I <file> instead of .B #include <file>
* Use Bnnn instead of Bnn

Changes in v2:
* Reformat SYNOPSIS for 80 chars per line

---
 man2/ioctl_tty.2 | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)
man2/ioctl_tty.2 +17 -2
index 186011ee7c33..7d866867c6bd 100644
@@ -11,8 +11,10 @@ ioctl_tty \- ioctls for terminals and serial lines
 .SH SYNOPSIS
 .nf
 .B #include <sys/ioctl.h>
-.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
-.BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
+.BR "#include <asm/termbits.h>" "   /* Definition of " "struct termios" ,
+.BR    "                               struct termios2" ", and"
+.BR    "                               Bnnn" ", " BOTHER ", " CBAUD ", " CLOCAL ,
+.BR    "                               TC*" { FLUSH , ON , OFF "} and other constants */"
 .PP
 .BI "int ioctl(int " fd ", int " cmd ", ...);"
 .fi
@@ -31,6 +33,19 @@ makes for nonportable programs.
 Use the POSIX interface described in
 .BR termios (3)
 whenever possible.
+.PP
+Please note that
+.B struct termios
+from
+.I <asm/termbits.h>
+is different and incompatible with
+.B struct termios
+from
+.IR <termios.h> .
+These ioctl calls require
+.B struct termios
+from
+.IR <asm/termbits.h> .
 .SS Get and set terminal attributes
 .TP
 .B TCGETS
Signature · 1 line
2.20.1
#5 lore raw
Quoted 7 lines · On Tuesday 31 August 2021 22:28:09 Pali Rohár wrote:

Header file termios.h contains incompatible definitions for linux ioctl calls. Correct definitions are exported by header file linux/termios.h but this file conflicts with sys/ioctl.h header file (required for ioctl() call). Therefore include direct asm header file asm/termbits.h which contains compatible definitions and structures for ioctl calls.

Hello Alejandro! Could you check also this patch?

Quoted 51 lines

---
Changes in v3:
* Use .I <file> instead of .B #include <file>
* Use Bnnn instead of Bnn

Changes in v2:
* Reformat SYNOPSIS for 80 chars per line

---
 man2/ioctl_tty.2 | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)
man2/ioctl_tty.2 +17 -2
index 186011ee7c33..7d866867c6bd 100644
@@ -11,8 +11,10 @@ ioctl_tty \- ioctls for terminals and serial lines
 .SH SYNOPSIS
 .nf
 .B #include <sys/ioctl.h>
-.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
-.BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
+.BR "#include <asm/termbits.h>" "   /* Definition of " "struct termios" ,
+.BR    "                               struct termios2" ", and"
+.BR    "                               Bnnn" ", " BOTHER ", " CBAUD ", " CLOCAL ,
+.BR    "                               TC*" { FLUSH , ON , OFF "} and other constants */"
 .PP
 .BI "int ioctl(int " fd ", int " cmd ", ...);"
 .fi
@@ -31,6 +33,19 @@ makes for nonportable programs.
 Use the POSIX interface described in
 .BR termios (3)
 whenever possible.
+.PP
+Please note that
+.B struct termios
+from
+.I <asm/termbits.h>
+is different and incompatible with
+.B struct termios
+from
+.IR <termios.h> .
+These ioctl calls require
+.B struct termios
+from
+.IR <asm/termbits.h> .
 .SS Get and set terminal attributes
 .TP
 .B TCGETS
Signature · 1 line
2.20.1
#6 lore raw

Hi Pali,

Quoted 10 lines · Pali Rohár
Quoted 7 lines · On Tuesday 31 August 2021 22:28:09 Pali Rohár wrote:

Header file termios.h contains incompatible definitions for linux ioctl calls. Correct definitions are exported by header file linux/termios.h but this file conflicts with sys/ioctl.h header file (required for ioctl() call). Therefore include direct asm header file asm/termbits.h which contains compatible definitions and structures for ioctl calls.

Hello Alejandro! Could you check also this patch?

Sure, patch applied!
BTW, if at some point you feel like adding entries for termios and termios2 into system_data_types(7), I'll be happy to merge those!!

Thank you!

Alex

Quoted 52 lines
Quoted 52 lines

---
Changes in v3:
* Use .I <file> instead of .B #include <file>
* Use Bnnn instead of Bnn

Changes in v2:
* Reformat SYNOPSIS for 80 chars per line

---
  man2/ioctl_tty.2 | 19 +++++++++++++++++--
  1 file changed, 17 insertions(+), 2 deletions(-)
man2/ioctl_tty.2 +17 -2
index 186011ee7c33..7d866867c6bd 100644
@@ -11,8 +11,10 @@ ioctl_tty \- ioctls for terminals and serial lines
  .SH SYNOPSIS
  .nf
  .B #include <sys/ioctl.h>
-.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
-.BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
+.BR "#include <asm/termbits.h>" "   /* Definition of " "struct termios" ,
+.BR    "                               struct termios2" ", and"
+.BR    "                               Bnnn" ", " BOTHER ", " CBAUD ", " CLOCAL ,
+.BR    "                               TC*" { FLUSH , ON , OFF "} and other constants */"
  .PP
  .BI "int ioctl(int " fd ", int " cmd ", ...);"
  .fi
@@ -31,6 +33,19 @@ makes for nonportable programs.
  Use the POSIX interface described in
  .BR termios (3)
  whenever possible.
+.PP
+Please note that
+.B struct termios
+from
+.I <asm/termbits.h>
+is different and incompatible with
+.B struct termios
+from
+.IR <termios.h> .
+These ioctl calls require
+.B struct termios
+from
+.IR <asm/termbits.h> .
  .SS Get and set terminal attributes
  .TP
  .B TCGETS
Signature · 1 line
2.20.1
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/